AI Agent Action: Make HTTP requests

Plan eligibility: Available on Advanced, Enterprise, and selected Legacy plans. Testing is available to all users, but publishing requires an eligible plan.

The Make HTTP requests action allows your AI Agent to call external APIs during a conversation. This lets the AI Agent retrieve real-time data or trigger actions in external systems based on the Contact’s request. For example, it can check order status, retrieve account information, or create records in another system. In this article, you’ll learn how to configure the HTTP request action and test it with your AI Agent.

The AI Agent:

1. Analyzes the Contact’s message to determine whether it matches the intent defined in your action instructions.

2. Collects any required information.

3. Sends the HTTP request.

4. Interprets the API response.

5. Replies naturally to the Contact.

Add a make HTTP request action

Toggle on the action and click on “Add action” button to start configuring your HTTP request.

Define when the action should run

• Give a descriptive name for the action in the Action name field.

• In the When and how should this action be performed? field, describe:

  • When the AI Agent should use this action

  • What it retrieves or sends

  • Any conditions or outcomes to handle

Example:

Use this action to retrieve a Contact’s order status when they ask about their order. If the API returns a 404 error, inform the Contact that the order could not be found.

The AI Agent uses this description to decide when to trigger the request.

Information the AI Agent may need (optional)

Define the inputs required in this section before calling your API.

These are structured variables that the AI must collect. The request is triggered only after all required inputs are available.

If a value is:

• Already mentioned in the conversation → the AI uses it.

• Missing → the AI asks the Contact for it.

The variables created here can be used in the API configuration. Contact variables (such as $contact.email) are available automatically and don’t need to be added.

Field settings

API configuration

Define how the AI Agent should call your API.

You can configure:

• Method

• URL

• Query parameters

• Headers

• JSON body (for POST, PUT, PATCH)

Referencing variables

You can insert variables in the URL, parameters, headers, or body using $.

There are two types:

• Contact variables — existing Contact fields

  • $contact.email

• AI Agent variables — fields defined under Information the AI Agent may need

  • $agent.order_id

Variables are replaced with real values when the request runs. If a required AI Agent variable is missing, the AI will ask for it before triggering the API call.

How the AI handles API responses

Example body:

{
  "order_id": "$agent.order_id",
  "email": "$contact.email"
}

The AI Agent automatically interprets the API’s JSON response and generates a natural reply.

Example API response:

{
  "status": "shipped",
  "eta": "2025-12-12"
}

AI reply: “Good news! Your order has been shipped and is expected to arrive on December 12, 2025.”

Testing

You can test your HTTP request action in the Test AI Agent panel before publishing.

How to test

1. Start a test conversation that matches your action conditions.

   

2. When the intent is detected and required inputs are available, the AI Agent executes the HTTP request.

3. An execution event appears in the test panel:

   

   1. {AI Agent name} executed {Action name}

   2. 2xx responses are shown as success

   3. All other status codes are shown as failure

4. Click the event to view:

   1. Response tab (default) — full API response body

   2. Request tab — full cURL request payload

   3. Copy option for debugging

5. After receiving the API response, the AI Agent generates a reply based on the returned data.

Important notes

• Execution events appear only in the Test AI Agent panel. They do not appear in Inbox or Contact Activity.

• If required inputs are missing, the AI Agent will ask for them before triggering the request.

Best practices

• Be precise in your action description. Vague instructions lead to vague triggers.

• Define required inputs clearly. If the AI must ask for something, make it obvious.

• Handle error cases in your instructions.

• Always test before publishing.

• Avoid duplicating logic already handled by Workflows unless intentionally designed.

Limitations

• Maximum 10 HTTP request actions per AI Agent.

• Maximum per action:

  • 20 data input fields

  • 50 parameters

  • 50 headers

• The AI Agent determines when to call the API based on your written description. Poorly written instructions may cause unexpected triggering.

• API response handling is automatic. You cannot manually map response fields — the AI interprets the JSON contextually.

• HTTP request execution events appear only in the Test AI Agent panel and not in Contact Activity.

• Voice AI Agents can trigger the Make HTTP requests action. However, the returned API response is not passed back to the Voice AI Agent for reply generation, meaning voice conversations cannot dynamically respond based on the API result.