API Connectors
API Connectors let your chatbot call external REST APIs during conversations to fetch real-time data. Use them to look up orders, check inventory, verify accounts, or integrate with any service that has an API.
Adding an API Connector
Navigate to your chatbot's Tools tab, scroll to the API Connectors section, and click Add API Connector. You can start from a pre-built template or create a custom connector.
Configuration Fields
Basic Settings
| Field | Description | Required |
|---|---|---|
| Name | A descriptive name for this connector (e.g. "Order Lookup", "Inventory Check"). | Yes |
| URL | The API endpoint URL (e.g. https://api.example.com/orders). | Yes |
| Method | HTTP method: GET, POST, PUT, PATCH, or DELETE. | Yes (default: GET) |
| Headers (JSON) | Optional HTTP headers in JSON format (e.g. {"Authorization": "Bearer abc123", "Content-Type": "application/json"}). Must be valid JSON. | No |
| Enabled | Whether this connector is active. | Yes (default: On) |
Request Body (POST/PUT/PATCH only)
| Field | Description |
|---|---|
| Body Content Type | Format of the request body: JSON or Form Data. |
| Request Body Template | Template for the request body. Use placeholders like {email}, {order_id} that correspond to your defined fields. |
Example body template:
{
"email": "{email}",
"order_id": "{order_id}"
}
Fields
Fields define what information the chatbot needs to collect from the visitor before calling the API. Each field has:
| Property | Description | Required |
|---|---|---|
| Field Name | The field identifier (e.g. order_id, email). Used as placeholder in the request body. | Yes |
| Type | Data type: string, number, email, or boolean. | Yes (default: string) |
| Description (for AI) | Explains to the AI what this field is for and how to ask the visitor for it. | No |
| Required | Whether the visitor must provide this field before the API is called. | No |
Example fields:
| Name | Type | Description | Required |
|---|---|---|---|
order_id | string | The customer's order number, usually starts with ORD- | Yes |
email | The email address used when placing the order | Yes |
Response Validation Rules
Validation rules verify that the API response matches the visitor's input. This prevents returning data for the wrong person or order.
Each rule has:
| Property | Description |
|---|---|
| Input Field | Which visitor-provided field to validate against (from your defined fields). |
| Response Path | Path to the value in the API response (e.g. billing.email, data.order.status). Use dot notation for nested objects. |
| Comparison | How to compare: equals, equals (ignore case), contains, or not empty. |
| Error Message | Message shown to the visitor when validation fails (e.g. "The email doesn't match our records"). |
Example validation:
| Input Field | Response Path | Comparison | Error Message |
|---|---|---|---|
| billing.email | equals (ignore case) | The email address doesn't match the order. Please check and try again. |
Prompt
Instructions for the AI on when and how to use this connector. This is critical for the chatbot to know when to trigger the API call.
Example prompt:
Use this connector when a customer asks about their order status, shipping
information, or delivery date. Ask for their order ID and email address before
making the API call. Present the order status, shipping method, and estimated
delivery date in a friendly format.
How It Works
- The visitor asks a question that matches the connector's prompt (e.g. "Where is my order?")
- The chatbot asks for the required fields (e.g. order ID, email)
- The visitor provides the information
- The chatbot calls the API with the collected data
- Validation rules are checked against the response
- If validation passes, the chatbot presents the data in a conversational format
Chaining Multiple API Connectors
You can combine multiple API connectors to handle complex workflows. The AI automatically chains them together when needed.
Example: Authentication + Data Retrieval
- Connector 1 — "Authenticate Customer": Calls a login endpoint with the visitor's email and password, receives an authentication token in the response.
- Connector 2 — "Fetch Order Details": Uses the token from the first request to call a protected API endpoint and retrieve order data.
The AI handles this seamlessly: it recognizes that the second connector requires data from the first, executes the calls in the correct order, and presents the final result to the visitor — all within a single conversation flow.
To set this up, configure each connector independently with its own endpoint, fields, and prompt. In the prompt of the second connector, describe that it depends on data from the first (e.g. "Use the authentication token from the Authenticate Customer connector to call this endpoint"). The AI will orchestrate the sequence automatically.
Best Practices
- Write clear prompts — The prompt is the most important field; it determines when the connector is triggered
- Add validation rules — Always validate sensitive data to prevent data leaks
- Use descriptive field descriptions — Help the AI ask the right questions in a natural way
- Test with real API responses — Ensure the response path matches your actual API structure
- Handle errors gracefully — Set meaningful error messages for validation failures
- Use authentication headers — Always secure your API endpoints with proper authentication