Sign in
OpenAPI 3.1.0MITraw.githubusercontent.com2026-08-172539131.9 MB

9bdd0e2bdf22

AI Webhooks

AI SWAIG tool webhook

Sent to a tool's web_hook_url (or the SWAIG defaults.web_hook_url) when an ai agent calls one of your functions.

Your endpoint runs the function and replies with a JSON object — the same shape a data_map output produces, because the platform reads both the same way. Every field is optional, so {} is a valid reply and a handler that only steers the call can return action alone:

  • response — the result the agent reads next, written to the AI rather than spoken to the caller. A plain string becomes the tool message as-is; the object form {tool_result, tool_prompt} splits the data half from the steering half. Omit it and the agent reads a default result.
  • action — a single action object or an array of them, executed on the live call.
  • post_process — hold the actions until after the agent has spoken. Default: false.
postWebhookaiSwaigToolWebhook

Payload

functionstring required

The name of the function the AI is calling.

argument_descobject required

The function's parameter definition, as you declared it in parameters.

descriptionstring required

The description you gave the function in SWAIG.functions.

call_idstring required

The ID of the call. On a chat conversation this carries the conversation id instead.

ai_session_idstring required

The ID of the AI session on the call.

conversation_idstring

The conversation ID, when the AI session has one. A text conversation held over the AI chat endpoint always has one, and it matches call_id.

app_namestring required

The name of your AI application.

global_dataobject

The AI session's current global_data, when it has any.

meta_data_tokenstring required

The token that scopes meta_data. This is the meta_data_token you set on the function, or a value derived from the function's web_hook_url and credentials when you did not set one.

meta_dataobject required

Metadata scoped to meta_data_token. An empty object when the function has none yet.

caller_id_namestring

The caller's name, when available.

caller_id_numstring

The caller's number, when available.

channel_activeboolean required

Whether the call is still up.

channel_offhookboolean required

Whether the call is answered.

channel_readyboolean required

Whether the AI session is ready to take actions.

content_typestring required

The content type of the request body. Always text/swaig.

versionstring required

The SWAIG protocol version.

content_dispositionstring required

How the body is delivered. Always SWAIG Function.

conversation_type'voice' | 'chat' required

The kind of conversation the agent is running: a call, or a text conversation held over the AI chat endpoint.

project_idstring

Your project ID, when available.

space_idstring

Your Space ID, when available.

fatal_errorboolean

true when the AI session has hit an unrecoverable error. Included only in that case.

error_reasonstring

A description of the error. Included only when fatal_error is set.

SWMLVarsobject

SWML variables for the call. Included when you enable swaig_post_swml_vars.

SWMLCallobject

SWML call state. Included when you enable swaig_post_swml_vars.

Example payload

{
  "function": "get_weather",
  "argument": {
    "parsed": [
      {
        "city": "San Francisco"
      }
    ],
    "raw": "{\"city\":\"San Francisco\"}"
  },
  "argument_desc": {
    "type": "object",
    "properties": {
      "city": {
        "type": "string",
        "description": "Name of the city"
      }
    },
    "required": [
      "city"
    ]
  },
  "description": "Look up the current weather for a city.",
  "call_id": "2e1e66e5-5d07-413d-9668-55542992eec0",
  "ai_session_id": "a0d4e6e5-5d07-413d-9668-55542992eec0",
  "app_name": "ai",
  "global_data": {
    "customer_tier": "premium",
    "pickup_address": "123 Main St, Springfield"
  },
  "meta_data_token": "my-token",
  "meta_data": {
    "order_number": "12345"
  },
  "caller_id_name": "Jane Doe",
  "caller_id_num": "+15555550100",
  "channel_active": true,
  "channel_offhook": true,
  "channel_ready": true,
  "content_type": "text/swaig",
  "version": "2.0",
  "content_disposition": "SWAIG Function",
  "conversation_type": "voice",
  "project_id": "4d0d6f16-5881-4fcc-92a4-02c51a91954d",
  "space_id": "451ed9ff-e568-4222-8af9-4f9ab7428d09",
  "call_log": [
    {
      "role": "assistant",
      "content": "Your ride is booked for 6pm.",
      "timestamp": 1694541297950440
    }
  ],
  "raw_call_log": [
    {
      "role": "assistant",
      "content": "Your ride is booked for 6pm.",
      "timestamp": 1694541297950440
    }
  ]
}

Response

Webhook received