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

ad46a79d07e4

Calls

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 returns a JSON object with a response string (the result the AI reads next) and, optionally, an action — a single object or an array — telling the agent what to do.

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.

ai_session_idstring required

The ID of the AI session on the call.

conversation_idstring

The conversation ID, when the AI session has one.

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.

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.

call_logobject[]

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

raw_call_logobject[]

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

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",
  "project_id": "4d0d6f16-5881-4fcc-92a4-02c51a91954d",
  "space_id": "451ed9ff-e568-4222-8af9-4f9ab7428d09"
}

Response

Webhook received