API Tools

How API Tools Work

When a user asks a question, your AI analyzes the conversation and decides whether to call an API tool. If a tool is needed, the AI can:

1. Make direct API calls for static data (no user input required)
2. Show forms to collect additional information from users before making API calls
3. Use visitor data automatically (name, email, plan, etc.)
4. Handle failures gracefully with fallback strategies

Creating Your First API Tool

Basic Configuration

Start with the fundamental settings that define your tool:

Tool Name

• A unique identifier (lowercase, underscores only)
• Example: get_customer_data, check_order_status

Description

• Detailed explanation for the AI (minimum 20 characters)
• Include: what the tool does, when to use it, response format
• Example: "Fetches customer subscription details. Use when user asks about their account or plan. Returns JSON: {plan_name, billing_cycle, usage_limit, current_usage}. Format into a friendly sentence like You're on the Pro plan (monthly) and have used 45% of your limit."

Dynamic Input Fields

Add interactive forms that collect user input before calling your API:

Field Types

• Text: Single-line input (can have dropdown options)
• Number: Numeric input (can have predefined options)
• Boolean: Yes/No questions with custom labels

Field Configuration

• Key: Variable name for API calls (snake_case)
• Question: What the user sees
• Description: AI guidance for when to prefill values
• Required: Whether user must provide this information

Dropdown Options For text/numeric fields, you can provide dropdown choices:

• Label: What users see (e.g., "Premium Plan")
• Value: What gets sent to your API (e.g., "premium_plan")
• Multiple Selection: Allow users to pick multiple options

Form Display Mode

Control when forms are shown to users versus automatically submitted based on AI-prefilled values:

Display Mode Options

Always Show Form

• Visitors always see the form, even if the AI has prefilled some values
• Users must manually submit the form to proceed
• Best for: Critical information that users should always review

Auto-submit if Required Fields Prefilled

• Skip showing the form if all required fields are prefilled by the AI
• Show the form only when required information is missing
• Best for: Most use cases where you want efficiency but ensure required data

Auto-submit if All Fields Prefilled Default

• Skip showing the form only when ALL fields (required and optional) are prefilled
• Show the form if any field is empty
• Best for: Simple forms where you want maximum automation

Auto-submit if Any Field Prefilled

• Skip showing the form if ANY field is prefilled by the AI
• All required fields must still be prefilled to actually submit
• Best for: Identifying an order based on either email address or order ID

API Configuration

Configure how your tool connects to external systems:

Endpoint URL

• Your API endpoint URL
• Use {{ field }} syntax to include dynamic data:
  • Visitor data: {{ name }}, {{ email }}, {{ plan }}, {{ external_id }}, {{ country }}
  • User input: {{ order_id }}, {{ plan_type }}
• Example: https://api.yourcompany.com/customers?id={{ external_id }}&order={{ order_id }}

HTTP Method

• GET for retrieving data
• POST for sending data or complex queries

Custom Headers

• Add authentication headers, content types, or API keys
• Use interpolation for dynamic values

Request Body (POST only)

• JSON key-value pairs for POST requests
• Supports the same interpolation syntax as URLs and headers

Authentication & Security

Secure Authentication Every request includes a Signature header containing the SHA-256 hash of your secret key. Your server should verify this to authenticate requests.

// Example verification in your API
const crypto = require('crypto');
const expectedSignature = crypto.createHash('sha256').update(YOUR_SECRET_KEY).digest('hex');

if (request.headers.signature !== expectedSignature) {
    return res.status(401).json({ error: 'Invalid signature' });
}

Secret Key Management

• Generate unique keys for each tool
• Rotate keys periodically for security
• Never expose keys in client-side code

Reliability Settings

Ensure your tools are resilient in production:

Timeout

• How long to wait for API responses (1,000-30,000ms)
• Default: 5,000ms

Retry Logic

• Number of retry attempts on failure (0-5)
• Uses exponential backoff

Rate Limiting

• Maximum calls per minute (0-100)
• Prevents API quota exhaustion

Failure Handling

Define what happens when API calls fail:

Failure Actions

Show Custom Message Display a user-friendly message when the API is unavailable.

Request Human Agent Escalate to human support with a custom message.

Fallback to Other Context Continue the conversation using existing documents and FAQs.

Error Scenarios

• Network timeouts → Retry based on your settings
• API errors (4xx/5xx) → Trigger failure action
• Invalid responses → Fallback behavior
• Rate limits exceeded → Respect rate limiting settings

Testing Your Tools

Before going live, thoroughly test your API tools:

Test Endpoint Button

• Click "Test Endpoint" to validate your configuration
• For tools with input fields, provide test values
• View the actual API response to ensure correct data format

Test Scenarios

• Success cases: Valid requests returning expected data
• Error handling: Invalid inputs, timeouts, API failures
• Edge cases: Missing data, unusual responses
• Authentication: Verify signature validation works

Best Practices

Advanced Usage

Automatic Agent Request

Your API can programmatically request human agent assistance by including special flags in the response:

Triggering Agent Requests Include {"request_agent": true} in your API response when your system determines it cannot fulfill the user's request and needs human assistance.

{
  "error": "Account requires manual review",
  "request_agent": true,
  "request_agent_message": "Your account needs special attention from our support team."
}

Custom Messages Optionally include request_agent_message to specify a custom message the AI will send before connecting to an agent:

{
  "status": "requires_approval",
  "request_agent": true,
  "request_agent_message": "Your request needs approval from our team. Let me connect you with someone who can help."
}

Use Cases

• Complex account issues requiring manual review
• High-value transactions needing verification
• Technical problems beyond automated handling
• Escalation based on business rules or risk assessment

Complex Workflows

Chain multiple tools together by having the AI call different tools based on user responses and previous API results.

Conditional Logic

Design your API to handle different scenarios based on input parameters, allowing one tool to serve multiple use cases.

Data Transformation

Use the AI's natural language capabilities to transform raw API data into conversational responses.

API tools bridge the gap between static knowledge and dynamic, real-time data, making your chatbot a powerful interface to your business systems. With proper configuration and testing, they can provide personalized, accurate responses that static context alone cannot achieve.