> For a complete index of all SignalWire documentation pages, fetch https://signalwire.com/docs/llms.txt

# functions

> Functions that can be executed during the interaction with the AI.

[reserved-functions]: #reserved-functions

[post-prompt]: /docs/swml/reference/ai#post_prompt

An array of JSON objects to define functions that can be executed during the interaction with the AI.

## **Properties**

<ParamField path="SWAIG.functions" type="object[]" toc={true}>
  An array of JSON objects that accept the following properties.
</ParamField>

<Indent>
  <ParamField path="functions[].description" type="string" required={true} toc={true}>
    A description of the context and purpose of the function, to explain to the agent when to use it.
  </ParamField>

  <ParamField path="functions[].function" type="string" required={true} toc={true}>
    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].
  </ParamField>

  <ParamField path="functions[].active" type="boolean" default="true" toc={true}>
    Whether the function is active.
  </ParamField>

  <ParamField path="functions[].data_map" type="object" toc={true}>
    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/ai/swaig/functions/data-map) for additional details.
  </ParamField>

  <ParamField path="functions[].parameters" type="object" toc={true}>
    A JSON object that defines the expected user input parameters and their validation rules for the function.

    See [`parameters`](/docs/swml/reference/ai/swaig/functions/parameters) for additional details.
  </ParamField>

  <ParamField path="functions[].fillers" type="object" toc={true}>
    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/ai/swaig#filler-language-codes) and each value is an array of filler phrases selected from randomly.
  </ParamField>

  <ParamField path="functions[].skip_fillers" type="boolean" default="false" toc={true}>
    Skips the top-level fillers specified in [`ai.languages`](/docs/swml/reference/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/ai/swaig/functions) will play.
  </ParamField>

  <ParamField path="functions[].meta_data" type="object" toc={true}>
    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/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.
  </ParamField>

  <ParamField path="functions[].meta_data_token" type="string" default="Set by SignalWire" toc={true}>
    Scoping token for `meta_data`. If not supplied, metadata will be scoped to function's `web_hook_url`.
  </ParamField>

  <ParamField path="functions[].wait_file" type="string" toc={true}>
    A file to play while the function is running. `wait_file_loops` can specify the amount of times that files should continously play.
  </ParamField>

  <ParamField path="functions[].wait_file_loops" type="string | integer" toc={true}>
    The amount of times that `wait_file` should continuously play/loop.
  </ParamField>

  <ParamField path="functions[].wait_for_fillers" type="boolean" default="false" toc={true}>
    Whether to wait for fillers to finish playing before continuing with the function.
  </ParamField>

  <ParamField path="functions[].web_hook_url" type="string" toc={true}>
    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`.
  </ParamField>

  <ParamField path="functions[].purpose" type="string" deprecated={true} toc={true}>
    Deprecated. Use `description` instead.
  </ParamField>

  <ParamField path="functions[].argument" type="object" deprecated={true} toc={true}>
    Deprecated. Use `parameters` instead.
  </ParamField>

  [SWML Function properties]: /docs/swml/reference/ai/swaig/functions#properties

  ## Webhook response

  When a SWAIG function is executed, the function expects the user to respond with a JSON object that contains a `response` key and an optional `action` key.
  This request response is used to provide the LLM with a new prompt response via the `response` key and to execute SWML-compatible objects that will perform
  new dialplan actions via the `action` key.

  <ParamField path="response" type="string" required={true} toc={true}>
    Static text that will be added to the AI agent's context.
  </ParamField>

  <ParamField path="action" type="object[]" toc={true}>
    A list of SWML-compatible objects that are executed upon the execution of a SWAIG function.
  </ParamField>

  <Indent>
    [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

    <ParamField path="action[].SWML" type="object" toc={true}>
      A SWML object to be executed.
    </ParamField>

    <ParamField path="action[].say" type="string" toc={true}>
      A message to be spoken by the AI agent.
    </ParamField>

    <ParamField path="action[].stop" type="boolean" toc={true}>
      Whether to stop the conversation.
    </ParamField>

    <ParamField path="action[].hangup" type="boolean" toc={true}>
      Whether to hang up the call. When set to `true`, the call will be terminated after the AI agent finishes speaking.
    </ParamField>

    <ParamField path="action[].hold" type="integer | object" toc={true}>
      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).

      <Note title="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.
      </Note>
    </ParamField>

    <Indent>
      <ParamField path="hold.timeout" type="integer" default="300" toc={true}>
        The duration to hold the caller in seconds. Maximum is `900` seconds (15 minutes).
      </ParamField>
    </Indent>

    <ParamField path="action[].change_context" type="string" toc={true}>
      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.
    </ParamField>

    <ParamField path="action[].change_step" type="string" toc={true}>
      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.
    </ParamField>

    <ParamField path="action[].toggle_functions" type="object[]" toc={true}>
      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.
    </ParamField>

    <Indent>
      <ParamField path="toggle_functions[].function" type="string" required={true} toc={true}>
        The name of the SWAIG function to toggle.
      </ParamField>

      <ParamField path="toggle_functions[].active" type="boolean" default="true" toc={true}>
        Whether to activate or deactivate the function.
      </ParamField>
    </Indent>

    <ParamField path="action[].set_global_data" type="object" toc={true}>
      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.
    </ParamField>

    <ParamField path="action[].set_meta_data" type="object" toc={true}>
      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.
    </ParamField>

    <ParamField path="action[].unset_global_data" type="string | object" toc={true}>
      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.
    </ParamField>

    <ParamField path="action[].unset_meta_data" type="string | object" toc={true}>
      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.
    </ParamField>

    <ParamField path="action[].playback_bg" type="object" toc={true}>
      A JSON object containing the audio file to play.
    </ParamField>

    <Indent>
      <ParamField path="playback_bg.file" type="string" toc={true}>
        URL or filepath of the audio file to play. Authentication can also be set in the url in the format of `username:password@url`.
      </ParamField>

      <ParamField path="playback_bg.wait" type="boolean" default="false" toc={true}>
        Whether to wait for the audio file to finish playing before continuing.
      </ParamField>
    </Indent>

    <ParamField path="action[].stop_playback_bg" type="boolean" toc={true}>
      Whether to stop the background audio file.
    </ParamField>

    <ParamField path="action[].user_input" type="string" toc={true}>
      Used to inject text into the users queue as if they input the data themselves.
    </ParamField>

    <ParamField path="action[].context_switch" type="object" toc={true}>
      A JSON object containing the context to switch to.

      See [`context_switch`][context_switch] for additional details.
    </ParamField>

    <Indent>
      <ParamField path="context_switch.system_prompt" type="string" toc={true}>
        The instructions to send to the agent.
      </ParamField>

      <ParamField path="context_switch.consolidate" type="boolean" default="false" toc={true}>
        Whether to consolidate the context.
      </ParamField>

      <ParamField path="context_switch.user_prompt" type="string" toc={true}>
        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.
      </ParamField>
    </Indent>

    <ParamField path="action[].transfer" type="object" toc={true}>
      Transfer the call to a new destination.
    </ParamField>

    <Indent>
      <ParamField path="transfer.dest" type="string" toc={true}>
        The destination to transfer to (phone number, SIP URI, or SWML URL).
      </ParamField>

      <ParamField path="transfer.summarize" type="boolean" default="false" toc={true}>
        Whether to include a conversation summary when transferring.
      </ParamField>
    </Indent>
  </Indent>

  ### Webhook response example

  ```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"
                }
              }
            ]
          }
        }
      }
    ]
  }
  ```

  ## Callback Request for web\_hook\_url

  SignalWire will make a request to the `web_hook_url` of a SWAIG function with the following parameters:

  <ParamField path="call_id" type="string" toc={true}>
    The unique identifier for the current call.
  </ParamField>

  <ParamField path="ai_session_id" type="string" toc={true}>
    The unique identifier for the AI session.
  </ParamField>

  <ParamField path="project_id" type="string" toc={true}>
    The project ID associated with the call.
  </ParamField>

  <ParamField path="space_id" type="string" toc={true}>
    The Space ID associated with the call.
  </ParamField>

  <ParamField path="caller_id_name" type="string" toc={true}>
    Name of the caller.
  </ParamField>

  <ParamField path="caller_id_num" type="string" toc={true}>
    Number of the caller.
  </ParamField>

  <ParamField path="global_data" type="object" toc={true}>
    Global data set via the `set_global_data` action, as a key-value map.
  </ParamField>

  <ParamField path="content_disposition" type="string" toc={true}>
    Content disposition identifier (e.g., `"SWAIG Function"`).
  </ParamField>

  <ParamField path="channel_active" type="boolean" toc={true}>
    Whether the channel is currently active.
  </ParamField>

  <ParamField path="channel_offhook" type="boolean" toc={true}>
    Whether the channel is off-hook.
  </ParamField>

  <ParamField path="channel_ready" type="boolean" toc={true}>
    Whether the channel is ready.
  </ParamField>

  <ParamField path="content_type" type="string" toc={true}>
    Type of content. The value will be `text/swaig`.
  </ParamField>

  <ParamField path="app_name" type="string" toc={true}>
    Name of the application that originated the request.
  </ParamField>

  <ParamField path="function" type="string" toc={true}>
    Name of the function that was invoked.
  </ParamField>

  <ParamField path="meta_data" type="object" toc={true}>
    A JSON object containing any user metadata, as a key-value map.
  </ParamField>

  <ParamField path="SWMLVars" type="object" toc={true}>
    A collection of variables related to SWML.
  </ParamField>

  <ParamField path="purpose" type="string" toc={true}>
    The purpose of the function being invoked. The value will be the `functions.purpose` value you provided in the [SWML Function properties].
  </ParamField>

  <ParamField path="argument_desc" type="string | object" toc={true}>
    The description of the argument being passed. This value comes from the argument you provided in the [SWML Function properties].
  </ParamField>

  <ParamField path="argument" type="object" toc={true}>
    The argument the AI agent is providing to the function. The object contains the three following fields.
  </ParamField>

  <Indent>
    <ParamField path="argument.parsed" type="object" toc={true}>
      If a JSON object is detected within the argument, it is parsed and provided here.
    </ParamField>

    <ParamField path="argument.raw" type="string" toc={true}>
      The raw argument provided by the AI agent.
    </ParamField>

    <ParamField path="argument.substituted" type="string" toc={true}>
      The argument provided by the AI agent, excluding any JSON.
    </ParamField>
  </Indent>

  <ParamField path="version" type="string" toc={true}>
    Version number.
  </ParamField>

  ### Webhook request example

  Below is a json example of the callback request that is sent to the `web_hook_url`:

  ```json
  {
    "app_name": "swml app",
    "global_data": {
      "caller_id_name": "",
      "caller_id_number": "sip:guest-246dd851-ba60-4762-b0c8-edfe22bc5344@46e10b6d-e5d6-421f-b6b3-e2e22b8934ed.call.signalwire.com;context=guest"
    },
    "project_id": "46e10b6d-e5d6-421f-b6b3-e2e22b8934ed",
    "space_id": "5bb2200d-3662-4f4d-8a8b-d7806946711c",
    "caller_id_name": "",
    "caller_id_num": "sip:guest-246dd851-ba60-4762-b0c8-edfe22bc5344@46e10b6d-e5d6-421f-b6b3-e2e22b8934ed.call.signalwire.com;context=guest",
    "channel_active": true,
    "channel_offhook": true,
    "channel_ready": true,
    "content_type": "text/swaig",
    "version": "2.0",
    "content_disposition": "SWAIG Function",
    "function": "get_weather",
    "argument": {
      "parsed": [
        {
          "city": "Tulsa",
          "state": "Oklahoma"
        }
      ],
      "raw": "{\"city\":\"Tulsa\",\"state\":\"Oklahoma\"}"
    },
    "call_id": "6e0f2f68-f600-4228-ab27-3dfba2b75da7",
    "ai_session_id": "9af20f15-7051-4496-a48a-6e712f22daa5",
    "argument_desc": {
      "properties": {
        "city": {
          "description": "Name of the city",
          "type": "string"
        },
        "country": {
          "description": "Name of the country",
          "type": "string"
        },
        "state": {
          "description": "Name of the state",
          "type": "string"
        }
      },
      "required": [],
      "type": "object"
    },
    "purpose": "Get weather with sarcasm"
  }
  ```

  ## Variables

  * **ai\_result:** (out) `success` | `failed`
  * **return\_value:** (out) `success` | `failed`
</Indent>

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

<Warning title="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.
</Warning>

### List of Reserved Functions

<ParamField path="start_hook" type="function" toc={true}>
  Triggered when the call is answered. Sends the set properties of the function to the defined `web_hook_url`.
</ParamField>

<ParamField path="stop_hook" type="function" toc={true}>
  Triggered when the call is ended. Sends the set properties of the function to the defined `web_hook_url`.
</ParamField>

<ParamField path="summarize_conversation" type="function" toc={true}>
  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`.
</ParamField>

<Warning title="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.
</Warning>

## 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:<br />{ "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

<CodeBlocks>
  <CodeBlock title="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
                  user: me
                  pass: secret
              defaults:
                web_hook_url: https://example.com/my-webhook
                web_hook_auth_user: me
                web_hook_auth_pass: 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.
    ```
  </CodeBlock>

  <CodeBlock title="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",
                    "user": "me",
                    "pass": "secret"
                  }
                ],
                "defaults": {
                  "web_hook_url": "https://example.com/my-webhook",
                  "web_hook_auth_user": "me",
                  "web_hook_auth_pass": "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."
                        }
                      }
                    }
                  }
                ]
              }
            }
          }
        ]
      }
    }
    ```
  </CodeBlock>
</CodeBlocks>