> Fetch clean Markdown by appending `.md` to any page URL under https://signalwire.com/docs or requesting it with the HTTP header `Accept: text/markdown`. The root index at https://signalwire.com/docs/llms.txt lists the available documentation indexes. # functions > Functions that can be executed during the interaction with the AI. [reserved-functions]: #reserved-functions [post-prompt]: /docs/swml/reference/calling/ai#post_prompt An array of JSON objects to define functions that can be executed during the interaction with the AI. ## **Properties** **`SWAIG.functions`** `object[]` An array of JSON objects that accept the following properties. --- **`functions[].description`** `string` — required A description of the context and purpose of the function, to explain to the agent when to use it. --- **`functions[].function`** `string` — required A unique name for the function. This can be any user-defined string or can reference a reserved function. Reserved functions are SignalWire functions that will be executed at certain points in the conversation. To learn more about reserved functions, see [Reserved Functions][reserved-functions]. --- **`functions[].active`** `boolean` — default: true Whether the function is active. --- **`functions[].data_map`** `object` An object that processes function inputs and executes operations through expressions, webhooks, or direct output. Properties are evaluated in strict priority order: (1) expressions, (2) webhooks, (3) output. Evaluation stops at the first property that returns a valid output result, similar to a return statement in a function. See [`data_map`](/docs/swml/reference/calling/ai/swaig/functions/data-map) for additional details. --- **`functions[].parameters`** `object` A JSON object that defines the expected user input parameters and their validation rules for the function. See [`parameters`](/docs/swml/reference/calling/ai/swaig/functions/parameters) for additional details. --- **`functions[].fillers`** `object` An object containing language-specific arrays of filler phrases that are played when calling a SWAIG function. These fillers help break silence between responses and are played asynchronously during the function call. Each key is a [language code](/docs/swml/reference/calling/ai/swaig#filler-language-codes) and each value is an array of filler phrases selected from randomly. --- **`functions[].skip_fillers`** `boolean` — default: false Skips the top-level fillers specified in [`ai.languages`](/docs/swml/reference/calling/ai/languages) (which includes `speech_fillers` and `function_fillers`). When set to `true`, only function-specific fillers defined directly on [`SWAIG.functions.fillers`](/docs/swml/reference/calling/ai/swaig/functions) will play. --- **`functions[].meta_data`** `object` A powerful and flexible environmental variable which can accept arbitrary data that is set initially in the SWML script or from the SWML [`set_meta_data` action](/docs/swml/reference/calling/ai/swaig/functions/data-map#actions). This data can be referenced **locally** to the function. All contained information can be accessed and expanded within the prompt - for example, by using a template string. --- **`functions[].meta_data_token`** `string` — default: Set by SignalWire Scoping token for `meta_data`. If not supplied, metadata will be scoped to function's `web_hook_url`. --- **`functions[].wait_file`** `string` A file to play while the function is running. `wait_file_loops` can specify the amount of times that files should continously play. --- **`functions[].wait_file_loops`** `string | integer` The amount of times that `wait_file` should continuously play/loop. --- **`functions[].wait_for_fillers`** `boolean` — default: false Whether to wait for fillers to finish playing before continuing with the function. --- **`functions[].web_hook_url`** `string` Function-specific URL to send status callbacks and reports to. Takes precedence over a default setting. Authentication can also be set in the url in the format of `username:password@url`. Credentials embedded in the URL take precedence over `web_hook_auth_user` and `web_hook_auth_password`. --- **`functions[].web_hook_auth_user`** `string` Username for basic auth on this function's webhook. Falls back to `defaults.web_hook_auth_user`. --- **`functions[].web_hook_auth_password`** `string` Password for basic auth on this function's webhook. Falls back to `defaults.web_hook_auth_password`. --- **`functions[].purpose`** `string` — deprecated Deprecated. Use `description` instead. --- **`functions[].argument`** `object` — deprecated Deprecated. Use `parameters` instead. --- **`functions[].web_hook_auth_pass`** `string` — deprecated Password for basic auth on this function's webhook. Deprecated — use `web_hook_auth_password` instead. This alias is read on individual functions only. The `ai` SWAIG `defaults` object does not accept it. --- ## Tool webhook When the agent calls one of your SWAIG functions, the platform sends an HTTP `POST` to that function's `web_hook_url` (or the SWAIG `defaults.web_hook_url`). 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. ### Request ### Schema (`Webhooks.AI.AiSwaigToolWebhookPayload`) ```yaml components: schemas: WebhooksAiAiSwaigToolWebhookPayloadArgumentParsedItems: type: object properties: {} title: WebhooksAiAiSwaigToolWebhookPayloadArgumentParsedItems WebhooksAiAiSwaigToolWebhookPayloadArgument: type: object properties: parsed: type: array items: $ref: >- #/components/schemas/WebhooksAiAiSwaigToolWebhookPayloadArgumentParsedItems 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: >- Any text that surrounded the JSON, with the JSON itself removed. Omitted when the whole argument was JSON, which is the usual case. required: - parsed - raw description: The arguments the AI passed to your function. title: WebhooksAiAiSwaigToolWebhookPayloadArgument WebhooksAiAiSwaigToolWebhookPayloadArgumentDesc: type: object properties: {} description: The function's parameter definition, as you declared it in `parameters`. title: WebhooksAiAiSwaigToolWebhookPayloadArgumentDesc WebhooksAiAiSwaigToolWebhookPayloadGlobalData: type: object properties: {} description: The AI session's current `global_data`, when it has any. title: WebhooksAiAiSwaigToolWebhookPayloadGlobalData WebhooksAiAiSwaigToolWebhookPayloadMetaData: type: object properties: {} description: >- Metadata scoped to `meta_data_token`. An empty object when the function has none yet. title: WebhooksAiAiSwaigToolWebhookPayloadMetaData WebhooksAiAiSwaigToolWebhookPayloadConversationType: type: string enum: - voice - chat description: >- The kind of conversation the agent is running: a call, or a text conversation held over the [AI chat endpoint](/docs/apis/rest/ai-chat/chat-methods). title: WebhooksAiAiSwaigToolWebhookPayloadConversationType WebhooksAiAiSwaigToolWebhookPayloadSwmlVars: type: object properties: {} description: >- SWML variables for the call. Included when you enable `swaig_post_swml_vars`. title: WebhooksAiAiSwaigToolWebhookPayloadSwmlVars WebhooksAiAiSwaigToolWebhookPayloadSwmlCall: type: object properties: {} description: SWML call state. Included when you enable `swaig_post_swml_vars`. title: WebhooksAiAiSwaigToolWebhookPayloadSwmlCall WebhooksAiAiCallLogEntryToolCallsItems: type: object properties: {} title: WebhooksAiAiCallLogEntryToolCallsItems Webhooks.AI.AICallLogEntry: type: object properties: role: type: string description: >- Who produced the entry. Common roles include `system`, `user`, `assistant`, and `tool`. Other roles may appear, so filter to the roles your application uses rather than assuming a fixed set. content: type: string description: The text of the entry. timestamp: type: integer format: int64 description: >- When the entry was added, as a Unix timestamp in microseconds. Omitted on entries without one. tool_calls: type: array items: $ref: '#/components/schemas/WebhooksAiAiCallLogEntryToolCallsItems' description: >- The tool calls the agent made on this turn. Present only on a turn that made any. required: - role - content description: >- One entry in the conversation. Beyond `role` and `content`, an entry carries whatever per-turn detail applies to it, such as recognition confidence on a caller turn or timings on a reply. title: Webhooks.AI.AICallLogEntry Webhooks.AI.AiSwaigToolWebhookPayload: type: object properties: function: type: string description: The name of the function the AI is calling. argument: $ref: '#/components/schemas/WebhooksAiAiSwaigToolWebhookPayloadArgument' description: The arguments the AI passed to your function. argument_desc: $ref: '#/components/schemas/WebhooksAiAiSwaigToolWebhookPayloadArgumentDesc' description: >- The function's parameter definition, as you declared it in `parameters`. description: type: string description: >- The description you gave the function in [`SWAIG.functions`](/docs/swml/reference/calling/ai/swaig/functions#properties). call_id: type: string description: >- The ID of the call. On a chat conversation this carries the conversation id instead. 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. A text conversation held over the [AI chat endpoint](/docs/apis/rest/ai-chat/chat-methods) always has one, and it matches `call_id`. app_name: type: string description: The name of your AI application. global_data: $ref: '#/components/schemas/WebhooksAiAiSwaigToolWebhookPayloadGlobalData' description: The AI session's current `global_data`, when it has any. meta_data_token: type: string description: >- 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: $ref: '#/components/schemas/WebhooksAiAiSwaigToolWebhookPayloadMetaData' description: >- Metadata scoped to `meta_data_token`. An empty object when the function has none yet. 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`. conversation_type: $ref: >- #/components/schemas/WebhooksAiAiSwaigToolWebhookPayloadConversationType description: >- The kind of conversation the agent is running: a call, or a text conversation held over the [AI chat endpoint](/docs/apis/rest/ai-chat/chat-methods). 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/WebhooksAiAiSwaigToolWebhookPayloadSwmlVars' description: >- SWML variables for the call. Included when you enable `swaig_post_swml_vars`. SWMLCall: $ref: '#/components/schemas/WebhooksAiAiSwaigToolWebhookPayloadSwmlCall' description: SWML call state. Included when you enable `swaig_post_swml_vars`. call_log: type: array items: $ref: '#/components/schemas/Webhooks.AI.AICallLogEntry' 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/Webhooks.AI.AICallLogEntry' 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 - meta_data_token - meta_data - channel_active - channel_offhook - channel_ready - content_type - version - content_disposition - conversation_type title: Webhooks.AI.AiSwaigToolWebhookPayload ``` See the [AI SWAIG tool webhook](/docs/apis/rest/webhooks/ai-swaig-tool-webhook) webhook page for the full field reference. ### Reply Return a JSON object with a `response` key and an optional `action` key. The `response` is the text the AI reads next, and `action` carries SWML-compatible objects that change what the call does next. **`response`** `string` — required Static text that will be added to the AI agent's context. --- **`action`** `object[]` A list of SWML-compatible objects that are executed upon the execution of a SWAIG function. --- [toggle\_functions]: /docs/swml/guides/toggle-functions[set\_meta\_data]: /docs/swml/guides/set-meta-data[context\_switch]: /docs/swml/guides/context-switch[properties]: /docs/swml/reference/ai#properties[contexts]: /docs/swml/reference/ai/prompt[steps]: /docs/swml/reference/ai/prompt **`action[].SWML`** `object` A SWML object to be executed. --- **`action[].say`** `string` A message to be spoken by the AI agent. --- **`action[].stop`** `boolean` Whether to stop the conversation. --- **`action[].hangup`** `boolean` Whether to hang up the call. When set to `true`, the call will be terminated after the AI agent finishes speaking. --- **`action[].hold`** `integer | object` Places the caller on hold while playing hold music (configured via the [`params.hold_music`](/docs/swml/reference/ai/params) parameter). During hold, speech detection is paused and the AI agent will not respond to the caller. The value specifies the hold timeout in seconds. Can be: * An integer (e.g., `120` for 120 seconds) * An object with a `timeout` property Default timeout is `300` seconds (5 minutes). Maximum timeout is `900` seconds (15 minutes). > **Unholding a call** > > There is no `unhold` SWAIG action because the AI agent is inactive during hold and cannot process actions. > To take a caller off hold, either: > > * Let the hold timeout expire (the AI will automatically resume with a default message), or > * Use the [Calling API `ai_unhold` command](/docs/apis/rest/calls/call-commands) to programmatically unhold the call with a custom prompt. --- **`hold.timeout`** `integer` — default: 300 The duration to hold the caller in seconds. Maximum is `900` seconds (15 minutes). --- **`action[].change_context`** `string` The name of the context to switch to. The context must be defined in the AI's `prompt.contexts` configuration. This action triggers an immediate context switch during the execution of a SWAIG function. Visit the [`contexts`][contexts] documentation for details on defining contexts. --- **`action[].change_step`** `string` The name of the step to switch to. The step must be defined in `prompt.contexts.{context_name}.steps` for the current context. This action triggers an immediate step transition during the execution of a SWAIG function. Visit the [`steps`][steps] documentation for details on defining steps. --- **`action[].toggle_functions`** `object[]` An array of objects to toggle SWAIG functions on or off during the conversation. Each object identifies a function by name and sets its active state. See [`toggle_functions`][toggle_functions] for additional details. --- **`toggle_functions[].function`** `string` — required The name of the SWAIG function to toggle. --- **`toggle_functions[].active`** `boolean` — default: true Whether to activate or deactivate the function. --- **`action[].set_global_data`** `object` A JSON object containing any global data, as a key-value map. This action sets the data in the [`global_data`][properties] to be globally referenced. --- **`action[].set_meta_data`** `object` A JSON object containing any metadata, as a key-value map. This action sets the data in the [`meta_data`][properties] to be referenced locally in the function. See [`set_meta_data`][set_meta_data] for additional details. --- **`action[].unset_global_data`** `string | object` The key of the global data to unset from the [`global_data`][properties]. You can also reset the `global_data` by passing in a new object. --- **`action[].unset_meta_data`** `string | object` The key of the metadata to unset from the [`meta_data`][properties]. You can also reset the `meta_data` by passing in a new object. --- **`action[].playback_bg`** `object` A JSON object containing the audio file to play. --- **`playback_bg.file`** `string` URL or filepath of the audio file to play. Authentication can also be set in the url in the format of `username:password@url`. --- **`playback_bg.wait`** `boolean` — default: false Whether to wait for the audio file to finish playing before continuing. --- **`action[].stop_playback_bg`** `boolean` Whether to stop the background audio file. --- **`action[].user_input`** `string` Used to inject text into the users queue as if they input the data themselves. --- **`action[].context_switch`** `object` A JSON object containing the context to switch to. See [`context_switch`][context_switch] for additional details. --- **`context_switch.system_prompt`** `string` The instructions to send to the agent. --- **`context_switch.consolidate`** `boolean` — default: false Whether to consolidate the context. --- **`context_switch.user_prompt`** `string` A string serving as simulated user input for the AI Agent. During a `context_switch` in the AI's prompt, the `user_prompt` offers the AI pre-established context or guidance. --- **`action[].transfer`** `boolean | object` Transfer the call to a new destination. Accepts two forms depending on whether it accompanies a sibling `action[].SWML` payload: * **Boolean** — use alongside a sibling `action[].SWML` payload in the same action object. When `true`, ends the AI session and hard-transfers the call to that SWML. When omitted or `false`, the SWML executes inline and the AI session continues afterward. * **Object** — use on its own, without `SWML`, to transfer the call to a specific destination configured with the fields below. A bare string is also accepted as shorthand for `transfer.dest`. --- **`transfer.dest`** `string` The destination to transfer to: the name of a section in the current SWML document, or a URL that returns SWML to execute. --- **`transfer.summarize`** `boolean` — default: false Whether to include a conversation summary when transferring. --- ```json { "response": "Oh wow, it's 82.0°F in Tulsa. Bet you didn't see that coming! Humidity at 38%. Your hair is going to love this! Wind speed is 2.2 mph. Hold onto your hats, or don't, I'm not your mother! Looks like Sunny. Guess you'll survive another day.", "action": [ { "set_meta_data": { "temperature": 82.0, "humidity": 38, "wind_speed": 2.2, "weather": "Sunny" } }, { "SWML": { "version": "1.0.0", "sections": { "main": [ { "play": { "url": "https://example.com/twister.mp3" } } ] } } } ] } ``` ## **Variables** * **ai\_result:** (out) `success` | `failed` * **return\_value:** (out) `success` | `failed` ## **Reserved Functions** Reserved functions are special SignalWire functions that are automatically triggered at specific points during a conversation. You define them just like any other SWAIG function, but their names correspond to built-in logic on the SignalWire platform, allowing them to perform specific actions at the appropriate time. > **Function name conflicts** > > Do not use reserved function names for your own SWAIG functions unless you want to use the reserved function's built-in behavior. > Otherwise, your function may not work as expected. ### List of Reserved Functions **`start_hook`** `function` Triggered when the call is answered. Sends the set properties of the function to the defined `web_hook_url`. --- **`stop_hook`** `function` Triggered when the call is ended. Sends the set properties of the function to the defined `web_hook_url`. --- **`summarize_conversation`** `function` Triggered when the call is ended. The [`post_prompt`][post-prompt] must be defined for this function to be triggered. Provides a summary of the conversation and any set properties to the defined `web_hook_url`. --- > **Where are my function properties?** > > If the AI is not returning the properties you set in your SWAIG function, it may be because a reserved function was triggered before > those properties were available. To ensure your function receives all necessary information, make sure the AI has access to the > required property values before the reserved function is called. Any property missing at the time the reserved function runs will > not be included in the data sent back. ## Diagram examples ```mermaid sequenceDiagram participant SW System participant User participant AI participant SWAIG %% Call starts SW System->>AI: Event: Call answered AI->>SWAIG: Trigger reserved function start_hook SWAIG->>AI: start_hook response %% User asks a simple question (no function needed) User->>AI: "Hello, who am I speaking with?" Note right of AI: Intent does NOT match a function AI->>User: "You are speaking with the SignalWire assistant." %% User asks for weather (triggers function) User->>AI: "What's the weather in Paris?" Note right of AI: Intent matches get_weather function AI->>SWAIG: Call get_weather with location=Paris SWAIG->>AI: Response payload:
{ "location": "Paris", "temp": "75°F", "condition": "Sunny" } AI->>User: "It's sunny and 75°F in Paris." %% Call ends SW System->>AI: Event: Call ended AI->>SWAIG: Trigger reserved function stop_hook SWAIG->>AI: stop_hook response %% Conversation ends (post_prompt defined) SW System->>AI: Event: Conversation ended AI->>SWAIG: Trigger reserved function summarize_conversation ``` ## SWML **Examples** ### Using SWAIG Functions #### YAML ```yaml version: 1.0.0 sections: main: - ai: post_prompt_url: "https://example.com/my-api" prompt: text: | You are a helpful assistant that can provide information to users about a destination. At the start of the conversation, always ask the user for their name. You can use the appropriate function to get the phone number, address, or weather information. post_prompt: text: "Summarize the conversation." SWAIG: includes: - functions: - get_phone_number - get_address url: https://example.com/functions auth_user: me auth_password: secret defaults: web_hook_url: https://example.com/my-webhook web_hook_auth_user: me web_hook_auth_password: secret functions: - function: get_weather description: To determine what the current weather is in a provided location. parameters: properties: location: type: string description: The name of the city to find the weather from. type: object - function: summarize_conversation description: Summarize the conversation. parameters: type: object properties: name: type: string description: The name of the user. ``` #### JSON ```json { "version": "1.0.0", "sections": { "main": [ { "ai": { "post_prompt_url": "https://example.com/my-api", "prompt": { "text": "You are a helpful assistant that can provide information to users about a destination.\nAt the start of the conversation, always ask the user for their name.\nYou can use the appropriate function to get the phone number, address,\nor weather information.\n" }, "post_prompt": { "text": "Summarize the conversation." }, "SWAIG": { "includes": [ { "functions": [ "get_phone_number", "get_address" ], "url": "https://example.com/functions", "auth_user": "me", "auth_password": "secret" } ], "defaults": { "web_hook_url": "https://example.com/my-webhook", "web_hook_auth_user": "me", "web_hook_auth_password": "secret" }, "functions": [ { "function": "get_weather", "description": "To determine what the current weather is in a provided location.", "parameters": { "properties": { "location": { "type": "string", "description": "The name of the city to find the weather from." } }, "type": "object" } }, { "function": "summarize_conversation", "description": "Summarize the conversation.", "parameters": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the user." } } } } ] } } } ] } } ``` > Functions that can be executed during the interaction with the AI. ## Docs - [data_map](https://signalwire.com/docs/swml/reference/calling/ai/swaig/functions/data-map.md): Defines how a SWAIG function should process and respond to the user's input data. - [parameters](https://signalwire.com/docs/swml/reference/calling/ai/swaig/functions/parameters.md): The parameters object for the SWAIG function.