Custom actions

Let the agent call your APIs with typed parameters.

An action is an HTTP request the agent may decide to make mid-conversation. You describe it in plain English plus a small parameter schema; the model extracts parameters from the conversation, calls your endpoint, and uses the response to answer.

Defining an action #

Field	Description
`name`	Snake-case identifier the model sees, e.g. `get_order_status`.
`description`	When to use it and what it returns. Be specific — this is the main signal the model uses.
`parameters`	JSON-Schema-style object with `string`, `number`, `integer` or `boolean` properties, optional `enum` and `required`.
`method / url`	Any HTTP method. Use `{{param}}` placeholders in the URL.
`headers`	Static headers such as an API key. Stored encrypted at rest.
`bodyTemplate`	Optional JSON template with `{{param}}` placeholders. Defaults to the parameters object.
`responseMode`	`text` lets the model summarise the JSON; `widget` renders a status card from a template.

Example: order lookup #

json

{
  "name": "get_order_status",
  "description": "Look up the shipping status of an order by its order number. Use whenever a customer asks where their order is.",
  "parameters": {
    "type": "object",
    "properties": {
      "orderNumber": {
        "type": "string",
        "description": "The order number, e.g. 48213"
      }
    },
    "required": [
      "orderNumber"
    ]
  },
  "method": "GET",
  "url": "https://api.example.com/orders/{{orderNumber}}",
  "headers": {
    "Authorization": "Bearer <token>"
  },
  "responseMode": "widget",
  "widgetTemplate": "{\"kind\":\"keyValue\",\"title\":\"Order {{id}}\",\"status\":\"{{status}}\",\"statusTone\":\"success\",\"rows\":[{\"label\":\"Carrier\",\"value\":\"{{carrier}}\"},{\"label\":\"ETA\",\"value\":\"{{eta}}\"}]}"
}

Templates use {{path.to.value}} against the parsed JSON response, including array indexes like {{items[0].name}}.

Testing #

Every action has a Test button in the dashboard that runs it with sample parameters and shows status, latency and the raw response. In the Playground, the inspector shows each tool call the agent made and what came back.

Failures #

Non-2xx responses and timeouts (10s) are returned to the model as errors so it can apologise or ask for different details. Each failure also emits an action.failed webhook.

Built-in tools #

Tool	What it does
`escalate_to_human`	Marks the conversation for a human, pauses the AI and notifies your inbox.
`capture_lead`	Stores a name/email when a visitor offers it and emits lead.created.
`show_widget`	Renders one of the rich widgets alongside the reply.