Skip to main content
HTTP integrations let you connect your agent to any external service that has a REST API. You define the request details, and the agent calls the API during conversations when it needs to look up data or take an action.

​
How It Works

When you create a custom HTTP tool, you configure:
  • URL — the API endpoint your agent will call
  • Method — GET, POST, PUT, PATCH, or DELETE
  • Headers — authentication tokens, API keys, or custom headers
  • Body — the JSON request body, with parameters the agent fills in
  • Description — a plain-language explanation of when the agent should use this tool
  • Parameters — the inputs the agent needs to provide (e.g., order ID, customer email)
During a call, the agent reads the description to decide when to use the tool, fills in the parameters based on the conversation, sends the request, and uses the response to continue the conversation.

​
Setting Up an HTTP Tool

  1. Go to the Tools tab on your agent in the dashboard
  2. Click Add Tool
  3. Fill in the request details:

​
Example: Order Status Lookup

FieldValue
NameLook up order status
DescriptionUse this tool to check the status of a customer’s order. Use it when the customer asks about their order or provides an order number.
MethodPOST
URLhttps://api.yourcompany.com/orders/lookup
HeadersAuthorization: Bearer your-api-key
Body{"order_id": "{{order_id}}"}

​
Example: Schedule Appointment

FieldValue
NameSchedule appointment
DescriptionUse this tool to book an appointment for the customer. Use it after collecting the customer’s preferred date and time.
MethodPOST
URLhttps://api.yourcompany.com/appointments
HeadersAuthorization: Bearer your-api-key
Body{"customer_name": "{{name}}", "date": "{{date}}", "time": "{{time}}"}

​
Example: CRM Contact Lookup

FieldValue
NameLook up contact
DescriptionUse this tool to look up the customer in the CRM by phone number. Use it at the start of the call to identify the caller.
MethodGET
URLhttps://api.yourcompany.com/contacts?phone={{phone_number}}
HeadersAuthorization: Bearer your-api-key

​
Response Handling

When the API responds, the agent reads the response body and uses the information to continue the conversation naturally. For example, if the order status API returns: 
{
  "order_id": "12345",
  "status": "shipped",
  "tracking_number": "1Z999AA10123456784",
  "estimated_delivery": "2026-04-15"
}
The agent would tell the caller something like: “Your order 12345 has been shipped. The tracking number is 1Z999AA10123456784 and the estimated delivery is April 15th.” If the API returns an error or times out, the agent handles it gracefully — it will let the caller know it was unable to retrieve the information and continue the conversation.

​
Extraction Fields

You can define extraction fields on a tool to pull specific values out of the API response. This is useful when you want the agent to focus on particular pieces of data rather than interpreting the entire response.

​
Testing Tools

You can test your HTTP tools directly from the dashboard before using them in live calls. This lets you verify that the request format, authentication, and response handling work correctly.

​
Best Practices

  • Write clear descriptions — the description is how the agent knows when to use the tool. Be specific about the trigger (“when the customer provides an order number”) rather than vague (“for order-related queries”).
  • Return concise responses — only include the data the agent needs to communicate. Large payloads slow down the conversation.
  • Use HTTPS — always use encrypted endpoints to protect data in transit.
  • Handle errors in your API — return clear error messages so the agent can communicate what went wrong.
  • Scope tools to nodes — in flow-based agents, assign each tool only to the nodes where it is relevant. This prevents the agent from using a tool at the wrong stage.