AI SWAIG tool webhook

{
  "function": "get_weather",
  "argument": {
    "parsed": [
      {
        "city": "San Francisco"
      }
    ],
    "raw": "{\"city\":\"San Francisco\"}"
  },
  "argument_desc": {
    "properties": {
      "city": {
        "description": "Name of the city",
        "type": "string"
      }
    },
    "required": [
      "city"
    ],
    "type": "object"
  },
  "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",
  "meta_data_token": "my-token",
  "meta_data": {
    "order_number": "12345"
  },
  "channel_active": true,
  "channel_offhook": true,
  "channel_ready": true,
  "content_type": "text/swaig",
  "version": "2.0",
  "content_disposition": "SWAIG Function"
}

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.

Sent to a tool's `web_hook_url` (or the SWAIG `defaults.web_hook_url`) when an [`ai`](/docs/swml/reference/calling/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`.

Payload

The payload of this webhook request is an object.

functionstringRequired

The name of the function the AI is calling.

argumentobjectRequired

The arguments the AI passed to your function.

argument_descobjectRequired

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

descriptionstringRequired

The description you gave the function in SWAIG.functions.

call_idstringRequired

The ID of the call.

ai_session_idstringRequired

The ID of the AI session on the call.

app_namestringRequired

The name of your AI application.

meta_data_tokenstringRequired

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_dataobjectRequired

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

channel_activebooleanRequired

Whether the call is still up.

channel_offhookbooleanRequired

Whether the call is answered.

channel_readybooleanRequired

Whether the AI session is ready to take actions.

content_typestringRequired

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

versionstringRequired

The SWAIG protocol version.

content_dispositionstringRequired

How the body is delivered. Always SWAIG Function.

conversation_idstringOptional

The conversation ID, when the AI session has one.

global_dataobjectOptional

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

caller_id_namestringOptional

The caller's name, when available.

caller_id_numstringOptional

The caller's number, when available.

project_idstringOptional

Your project ID, when available.

space_idstringOptional

Your Space ID, when available.

fatal_errorbooleanOptional

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

error_reasonstringOptional

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

SWMLVarsobjectOptional

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

SWMLCallobjectOptional

SWML call state. Included when you enable swaig_post_swml_vars.

call_loglist of objectsOptional

The conversation so far, with sensitive values redacted. Included when you enable swaig_post_conversation.

raw_call_loglist of objectsOptional

The full, unredacted conversation so far. Included when you enable swaig_post_conversation.

Response

200

Webhook received

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

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.