Skip to main content
An API call action gives the agent a tool that calls an HTTP endpoint of yours — an order lookup, a stock check, an appointment search. The agent decides when to call it from the description you write, fills in the parameters from the conversation, and answers from the response. Add one on the agent’s Actions page with Add action → API call. It is one of several action types.

​
Fields

Every {{placeholder}} in the URL or body must be a declared param; saving fails otherwise.

​
Example

A GET order lookup:
When a customer asks “where is order 10482?”, the agent calls:
The agent gets back the HTTP status code and the response body, and answers from them.

​
API credentials

Add the key under Authentication while setting up the action, rather than pasting it into the URL: choose Add a new key… under API key and enter a label and the secret. It is stored encrypted, never shown again, and never given to the agent — it is only attached to the request. Saved keys are listed under API credentials on the Actions page, by label and last four characters, where they can be reused by other actions or removed. If your API expects the key somewhere other than a header, put {{credential}} in the request body and the saved key is filled in there. It is never allowed in the URL. Deleting a key stops every action that uses it until you attach a new one.

​
Limits

  • Timeout: 5 seconds on a phone call, 15 seconds on chat and email. On a call, the agent says a short holding line before calling.
  • Response size: the agent reads the first 1,500 characters of the response on a call and the first 4,000 on chat and email. Return a small JSON object with just what the agent needs.
  • Redirects are not followed. Point the URL at the final address.
  • Addresses: the URL must be https, use a hostname rather than an IP address, and not point at a private network or localhost. This is checked again against the actual URL after parameters are filled in.
  • Only the parameters you declared are filled in. The agent cannot add others.
If the call times out or fails, the agent is told and offers to follow up or take a message, and the conversation carries on.

​
Designing the endpoint

  • Return errors the agent can say out loud: {"error": "No order 10482 — check the number on the confirmation email."}.
  • Treat every parameter as untrusted input from the public. The agent fills them from what a customer typed or said.
  • Scope the credential to read-only access on what the action needs.

​
Checking it works

Every call appears in the Action log under Inbox → Extra fields, with the tool name, ok or failed, how long it took, and a link to the conversation. failed means the request did not complete — a timeout, a redirect, a refused address. A response with an error status such as 404 still shows as ok, because your endpoint answered; read the conversation to see what the agent made of it. Ask your agent a question that should trigger the action, then look there.