---
title: "AI SWAIG tool webhook"
method: POST
path: "aiSwaigToolWebhook"
tags: ["Calls"]
---

# AI SWAIG tool webhook

`POST aiSwaigToolWebhook` (webhook)

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.

## Payload

- object — 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.
  - `function` string, required — The name of the function the AI is calling.
  - `argument` object, required — The arguments the AI passed to your function.
    - `parsed` object[], required — The arguments parsed into objects. Usually a single-element array.
    - `raw` string, required — The raw argument string, exactly as the AI produced it.
    - `substituted` string, required — The raw argument string after any variable substitution.
  - `argument_desc` object, required — The function's parameter definition, as you declared it in `parameters`.
  - `description` string, required — The description you gave the function.
  - `call_id` string, required — The ID of the call.
  - `ai_session_id` string, required — The ID of the AI session on the call.
  - `conversation_id` string — The conversation ID, when the AI session has one.
  - `app_name` string, required — The name of your AI application.
  - `global_data` object — The AI session's current `global_data`, when it has any.
  - `meta_data_token` string — The token that scopes `meta_data`, when the function defines one.
  - `meta_data` object — Metadata scoped to `meta_data_token`, when the function defines a token.
  - `caller_id_name` string — The caller's name, when available.
  - `caller_id_num` string — The caller's number, when available.
  - `channel_active` boolean, required — Whether the call is still up.
  - `channel_offhook` boolean, required — Whether the call is answered.
  - `channel_ready` boolean, required — Whether the AI session is ready to take actions.
  - `content_type` string, required — The content type of the request body. Always `text/swaig`.
  - `version` string, required — The SWAIG protocol version.
  - `content_disposition` string, required — How the body is delivered. Always `SWAIG Function`.
  - `project_id` string — Your project ID, when available.
  - `space_id` string — Your Space ID, when available.
  - `fatal_error` boolean — `true` when the AI session has hit an unrecoverable error. Included only in that case.
  - `error_reason` string — A description of the error. Included only when `fatal_error` is set.
  - `SWMLVars` object — SWML variables for the call. Included when you enable `swaig_post_swml_vars`.
  - `SWMLCall` object — SWML call state. Included when you enable `swaig_post_swml_vars`.
  - `call_log` object[] — The conversation so far, with sensitive values redacted. Included when you enable `swaig_post_conversation`.
  - `raw_call_log` object[] — The full, unredacted conversation so far. Included when you enable `swaig_post_conversation`.

## Acknowledgement `200`

Webhook received

---

[API](https://skmtc.net/signalwire/apis/signalwire-rest-api.md) · [All operations](https://skmtc.net/signalwire/apis/signalwire-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/signalwire/signalwire-rest-api/versions/05c5164b85c7/schema)