Sign in

v77

latestOpenAPI 3.1.0MITraw.githubusercontent.com2026-08-012528701.8 MB
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.

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

The token that scopes meta_data, when the function defines one.

meta_dataobject

Metadata scoped to meta_data_token, when the function defines a token.

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\"}",
    "substituted": "{\"city\":\"San Francisco\"}"
  },
  "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",
  "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"
}

Response

Webhook received