Skip to navigation
WebhooksAI

AI SWAIG tool webhook

View as MarkdownOpen in Claude

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.

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. On a chat conversation this carries the conversation id instead.
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_typeenumRequired

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

Allowed values:
conversation_idstringOptional

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.

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