> 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 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`.

Reference: https://signalwire.com/docs/apis/rest/webhooks/ai-swaig-tool-webhook

## Request

### Payload

- `function` (string, required) — The name of the function the AI is calling.
- `argument` (object, required) — The arguments the AI passed to your function.
  - `parsed` (list of 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, optional) — Any text that surrounded the JSON, with the JSON itself removed. Omitted when the whole argument was JSON, which is the usual case.
- `argument_desc` (object, required) — The function's parameter definition, as you declared it in `parameters`.
- `description` (string, required) — The description you gave the function in [`SWAIG.functions`](/docs/swml/reference/calling/ai/swaig/functions#properties).
- `call_id` (string, required) — The ID of the call.
- `ai_session_id` (string, required) — The ID of the AI session on the call.
- `app_name` (string, required) — The name of your AI application.
- `meta_data_token` (string, 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_data` (object, required) — Metadata scoped to `meta_data_token`. An empty object when the function has none yet.
- `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`.
- `conversation_id` (string, optional) — The conversation ID, when the AI session has one.
- `global_data` (object, optional) — The AI session's current `global_data`, when it has any.
- `caller_id_name` (string, optional) — The caller's name, when available.
- `caller_id_num` (string, optional) — The caller's number, when available.
- `project_id` (string, optional) — Your project ID, when available.
- `space_id` (string, optional) — Your Space ID, when available.
- `fatal_error` (boolean, optional) — `true` when the AI session has hit an unrecoverable error. Included only in that case.
- `error_reason` (string, optional) — A description of the error. Included only when `fatal_error` is set.
- `SWMLVars` (object, optional) — SWML variables for the call. Included when you enable `swaig_post_swml_vars`.
- `SWMLCall` (object, optional) — SWML call state. Included when you enable `swaig_post_swml_vars`.
- `call_log` (list of object, optional) — The conversation so far, with sensitive values redacted. Included when you enable `swaig_post_conversation`.
  - `role` (string, required) — Who produced the entry: `system`, `user`, `assistant`, or `tool`.
  - `content` (string, required) — The text of the entry.
  - `timestamp` (long, optional) — When the entry was added, as a Unix timestamp in microseconds. Omitted on entries without one.
  - `tool_calls` (list of object, optional) — The tool calls the agent made on this turn. Present only on a turn that made any.
- `raw_call_log` (list of object, optional) — The full, unredacted conversation so far. Included when you enable `swaig_post_conversation`.
  - `role` (string, required) — Who produced the entry: `system`, `user`, `assistant`, or `tool`.
  - `content` (string, required) — The text of the entry.
  - `timestamp` (long, optional) — When the entry was added, as a Unix timestamp in microseconds. Omitted on entries without one.
  - `tool_calls` (list of object, optional) — The tool calls the agent made on this turn. Present only on a turn that made any.