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

# 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 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

- WebhooksAIAiSwaigToolWebhookPayload
  - `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 — 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.
  - `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, 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.
  - `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` WebhooksAIAICallLogEntry[] — 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` integer — When the entry was added, as a Unix timestamp in microseconds. Omitted on entries without one.
    - `tool_calls` object[] — The tool calls the agent made on this turn. Present only on a turn that made any.
  - `raw_call_log` WebhooksAIAICallLogEntry[] — 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` integer — When the entry was added, as a Unix timestamp in microseconds. Omitted on entries without one.
    - `tool_calls` object[] — The tool calls the agent made on this turn. Present only on a turn that made any.

## 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/revisions/a884f7dcbfc3/schema)