> For a complete index of all SignalWire documentation pages, fetch https://signalwire.com/docs/llms.txt # AI SWAIG tool webhook POST 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 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. Reference: https://signalwire.com/docs/apis/rest/calls/webhooks/ai-swaig-tool-webhook ## OpenAPI 3.1 Webhook Specification ```yaml openapi: 3.1.0 info: title: signalwire-rest version: 1.0.0 paths: {} webhooks: ai-swaig-tool-webhook: post: operationId: ai-swaig-tool-webhook summary: AI SWAIG tool webhook description: >- 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 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. responses: '200': description: Webhook received successfully requestBody: content: application/json: schema: type: object properties: function: type: string description: The name of the function the AI is calling. argument: $ref: >- #/components/schemas/WebhooksAiSwaigToolWebhookPayloadContentApplicationJsonSchemaArgument description: The arguments the AI passed to your function. argument_desc: $ref: >- #/components/schemas/WebhooksAiSwaigToolWebhookPayloadContentApplicationJsonSchemaArgumentDesc description: >- The function's parameter definition, as you declared it in `parameters`. description: type: string description: The description you gave the function. call_id: type: string description: The ID of the call. ai_session_id: type: string description: The ID of the AI session on the call. conversation_id: type: string description: The conversation ID, when the AI session has one. app_name: type: string description: The name of your AI application. global_data: $ref: >- #/components/schemas/WebhooksAiSwaigToolWebhookPayloadContentApplicationJsonSchemaGlobalData description: The AI session's current `global_data`, when it has any. meta_data_token: type: string description: >- The token that scopes `meta_data`, when the function defines one. meta_data: $ref: >- #/components/schemas/WebhooksAiSwaigToolWebhookPayloadContentApplicationJsonSchemaMetaData description: >- Metadata scoped to `meta_data_token`, when the function defines a token. caller_id_name: type: string description: The caller's name, when available. caller_id_num: type: string description: The caller's number, when available. channel_active: type: boolean description: Whether the call is still up. channel_offhook: type: boolean description: Whether the call is answered. channel_ready: type: boolean description: Whether the AI session is ready to take actions. content_type: type: string description: The content type of the request body. Always `text/swaig`. version: type: string description: The SWAIG protocol version. content_disposition: type: string description: How the body is delivered. Always `SWAIG Function`. project_id: type: string description: Your project ID, when available. space_id: type: string description: Your Space ID, when available. fatal_error: type: boolean description: >- `true` when the AI session has hit an unrecoverable error. Included only in that case. error_reason: type: string description: >- A description of the error. Included only when `fatal_error` is set. SWMLVars: $ref: >- #/components/schemas/WebhooksAiSwaigToolWebhookPayloadContentApplicationJsonSchemaSwmlVars description: >- SWML variables for the call. Included when you enable `swaig_post_swml_vars`. SWMLCall: $ref: >- #/components/schemas/WebhooksAiSwaigToolWebhookPayloadContentApplicationJsonSchemaSwmlCall description: >- SWML call state. Included when you enable `swaig_post_swml_vars`. call_log: type: array items: $ref: >- #/components/schemas/WebhooksAiSwaigToolWebhookPayloadContentApplicationJsonSchemaCallLogItems description: >- The conversation so far, with sensitive values redacted. Included when you enable `swaig_post_conversation`. raw_call_log: type: array items: $ref: >- #/components/schemas/WebhooksAiSwaigToolWebhookPayloadContentApplicationJsonSchemaRawCallLogItems description: >- The full, unredacted conversation so far. Included when you enable `swaig_post_conversation`. required: - function - argument - argument_desc - description - call_id - ai_session_id - app_name - channel_active - channel_offhook - channel_ready - content_type - version - content_disposition components: schemas: WebhooksAiSwaigToolWebhookPayloadContentApplicationJsonSchemaArgumentParsedItems: type: object properties: {} title: >- WebhooksAiSwaigToolWebhookPayloadContentApplicationJsonSchemaArgumentParsedItems WebhooksAiSwaigToolWebhookPayloadContentApplicationJsonSchemaArgument: type: object properties: parsed: type: array items: $ref: >- #/components/schemas/WebhooksAiSwaigToolWebhookPayloadContentApplicationJsonSchemaArgumentParsedItems description: The arguments parsed into objects. Usually a single-element array. raw: type: string description: The raw argument string, exactly as the AI produced it. substituted: type: string description: The raw argument string after any variable substitution. required: - parsed - raw - substituted description: The arguments the AI passed to your function. title: WebhooksAiSwaigToolWebhookPayloadContentApplicationJsonSchemaArgument WebhooksAiSwaigToolWebhookPayloadContentApplicationJsonSchemaArgumentDesc: type: object properties: {} description: The function's parameter definition, as you declared it in `parameters`. title: >- WebhooksAiSwaigToolWebhookPayloadContentApplicationJsonSchemaArgumentDesc WebhooksAiSwaigToolWebhookPayloadContentApplicationJsonSchemaGlobalData: type: object properties: {} description: The AI session's current `global_data`, when it has any. title: WebhooksAiSwaigToolWebhookPayloadContentApplicationJsonSchemaGlobalData WebhooksAiSwaigToolWebhookPayloadContentApplicationJsonSchemaMetaData: type: object properties: {} description: Metadata scoped to `meta_data_token`, when the function defines a token. title: WebhooksAiSwaigToolWebhookPayloadContentApplicationJsonSchemaMetaData WebhooksAiSwaigToolWebhookPayloadContentApplicationJsonSchemaSwmlVars: type: object properties: {} description: >- SWML variables for the call. Included when you enable `swaig_post_swml_vars`. title: WebhooksAiSwaigToolWebhookPayloadContentApplicationJsonSchemaSwmlVars WebhooksAiSwaigToolWebhookPayloadContentApplicationJsonSchemaSwmlCall: type: object properties: {} description: SWML call state. Included when you enable `swaig_post_swml_vars`. title: WebhooksAiSwaigToolWebhookPayloadContentApplicationJsonSchemaSwmlCall WebhooksAiSwaigToolWebhookPayloadContentApplicationJsonSchemaCallLogItems: type: object properties: {} title: >- WebhooksAiSwaigToolWebhookPayloadContentApplicationJsonSchemaCallLogItems WebhooksAiSwaigToolWebhookPayloadContentApplicationJsonSchemaRawCallLogItems: type: object properties: {} title: >- WebhooksAiSwaigToolWebhookPayloadContentApplicationJsonSchemaRawCallLogItems ```