***

id: 2d963120-5a98-491e-9779-fdab58cc675d
slug: /reference/ai/swaig/functions/data-map
title: data\_map
description: >-
Defines how a SWAIG function should process and respond to the user's input
data.
max-toc-depth: 3
----------------

`functions[].data_map` defines how a [`SWAIG function`](/docs/swml/reference/ai/swaig/functions) should process and respond to the user's input data.

<ParamField path="functions[].data_map" type="object" toc={true}>
  An object that processes function inputs and executes operations through expressions, webhooks, or direct output.
</ParamField>

<Warning title="Processing order">
  The components are processed in the following sequence:

  1. `expressions` - Processes data using pattern matching (includes its own `output`)
  2. `webhooks` - Makes external API calls (includes its own `output` and `expressions`)
  3. `output` - Returns a direct response and actions to perform
</Warning>

Similar to a `return` statement in conventional programming languages,
when a valid [`output`](#output) is encountered within any component,
it immediately terminates function execution.
The `output` provides:

1. A `response` object: Contains static text for the AI agent's context
2. An optional `action` object: Defines executable actions to be triggered

If no component produces a valid `output`, the system continues processing in sequence:

* First attempts `expressions`
* If unsuccessful, tries `webhooks`
* If still unsuccessful, attempts top-level `output`
* If all fail, returns a generic fallback error message

## **Properties**

<ParamField path="data_map.expressions" type="object[]" toc={true}>
  An array of objects that define plain string or regex patterns to match against the user's input. When a match is found, the `output` object is returned.
</ParamField>

<Indent>
  <ParamField path="expressions[].string" type="string" required={true} toc={true}>
    The actual input or value from the user or system.
  </ParamField>

  <ParamField path="expressions[].pattern" type="string" required={true} toc={true}>
    A regular expression pattern to validate or match the string.
  </ParamField>

  <ParamField path="expressions[].output" type="object" required={true} toc={true}>
    Defines the response or action to be taken when the pattern matches.
    See [`output`](#output) for details.
  </ParamField>
</Indent>

<ParamField path="data_map.webhooks" type="object[]" toc={true}>
  An array of objects that define external API calls. If a webhook defines `foreach`, `expressions`, and `output`, they are evaluated in that order.
</ParamField>

<Indent>
  <ParamField path="webhooks[].url" type="string" required={true} toc={true}>
    The endpoint for the external service or API. Authentication can also be set in the url in the format of `username:password@url`. See [webhook runtime request](#webhook-runtime-request) for details on template variable substitution and request behavior.
  </ParamField>

  <ParamField path="webhooks[].method" type="string" required={true} toc={true}>
    The HTTP method (GET, POST, etc.) for the API call.
  </ParamField>

  <ParamField path="webhooks[].headers" type="object" toc={true}>
    Any necessary headers for the API call.
  </ParamField>

  <ParamField path="webhooks[].params" type="object" toc={true}>
    An object of any necessary parameters for the API call. The key is the parameter name and the value is the parameter value.
  </ParamField>

  <ParamField path="webhooks[].input_args_as_params" type="boolean" default="false" toc={true}>
    A boolean to determine if the input [parameters](/docs/swml/reference/ai/swaig/functions/parameters) should be passed as parameters.
  </ParamField>

  <ParamField path="webhooks[].required_args" type="string | string[]" toc={true}>
    A string or array of strings that represent the [parameters](/docs/swml/reference/ai/swaig/functions/parameters) that are required to make the webhook request.
  </ParamField>

  <ParamField path="webhooks[].error_keys" type="string | string[]" toc={true}>
    A string or array of strings that represent the keys to be used for error handling.
  </ParamField>

  <ParamField path="webhooks[].expressions" type="object" toc={true}>
    A list of expressions to be evaluated upon matching.
    See [`expressions`](#expressions) for details.
  </ParamField>

  <ParamField path="webhooks[].foreach" type="object" toc={true}>
    Iterates over an array of objects and processes an output based on each element in the array. Works similarly to JavaScript's [forEach](https://www.w3schools.com/jsref/jsref_foreach.asp) method.
  </ParamField>

  <Indent>
    <ParamField path="foreach.input_key" type="string" required={true} toc={true}>
      The key to be used to access the current element in the array.
    </ParamField>

    <ParamField path="foreach.output_key" type="string" required={true} toc={true}>
      The key that can be referenced in the output of the `foreach` iteration. The values that are stored from `append` will be stored in this key.
    </ParamField>

    <ParamField path="foreach.append" type="string" required={true} toc={true}>
      The values to append to the `output_key`.
      Properties from the object can be referenced and added to the `output_key` by using the following syntax: `${this.property_name}`.
      The `this` keyword is used to reference the current object in the array.
    </ParamField>

    <ParamField path="foreach.max" type="number" toc={true}>
      The max amount of elements that are iterated over in the array. This will start at the beginning of the array.
    </ParamField>
  </Indent>

  <ParamField path="webhooks[].output" type="object" required={true} toc={true}>
    Defines the response or action to be taken when the webhook is successfully triggered.
    See [`output`](#output) for details.
  </ParamField>
</Indent>

<ParamField path="data_map.output" type="object" toc={true}>
  Similar to a `return` statement in conventional programming languages, the `data_map.output` object immediately
  terminates function execution and returns control to the caller.
</ParamField>

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

  <ParamField path="output.action" type="object[]" toc={true}>
    A list of SWML-compatible objects that are executed upon the execution of a SWAIG function.
    See [list of valid actions](#actions) for details.
  </ParamField>
</Indent>

### List of valid actions

[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">
  A SWML object to be executed.
</ParamField>

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

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

<ParamField path="action[].hangup" type="boolean">
  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">
  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/calling/calls/call-commands) to programmatically unhold the call with a custom prompt.
  </Note>
</ParamField>

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

<ParamField path="action[].change_context" type="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.
</ParamField>

<ParamField path="action[].change_step" type="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.
</ParamField>

<ParamField path="action[].toggle_functions" type="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.
</ParamField>

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

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

<ParamField path="action[].set_global_data" type="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.
</ParamField>

<ParamField path="action[].set_meta_data" type="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.
</ParamField>

<ParamField path="action[].unset_global_data" type="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.
</ParamField>

<ParamField path="action[].unset_meta_data" type="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.
</ParamField>

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

<Indent>
  <ParamField path="playback_bg.file" type="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`.
  </ParamField>

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

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

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

<ParamField path="action[].context_switch" type="object">
  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">
    The instructions to send to the agent.
  </ParamField>

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

  <ParamField path="context_switch.user_prompt" type="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.
  </ParamField>
</Indent>

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

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

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

## **Webhook runtime request**

When the AI triggers a function that uses `data_map.webhooks`, SignalWire sends a request to each configured `url`.

### Template variables

The `url` and `params` fields support `%{variable}` substitution.
Nested properties use dot notation — for example,
`https://api.example.com/weather?city=%{args.location}` substitutes the value the AI extracted for `location`.
For more on [variables](/docs/swml/reference/variables) and scopes, see the [Variables reference](/docs/swml/reference/variables).

<ParamField path="args" type="object" toc={true}>
  Function argument values extracted by the AI, keyed by argument name.
</ParamField>

<Indent>
  <ParamField path="args.*" type="any" toc={true}>
    Individual argument value. The key matches an argument name from the function's [`parameters`](/docs/swml/reference/ai/swaig/functions/parameters) schema.
  </ParamField>
</Indent>

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

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

<ParamField path="conversation_id" type="string" toc={true}>
  Conversation identifier.
</ParamField>

<ParamField path="function" type="string" toc={true}>
  Name of the function being executed.
</ParamField>

<ParamField path="caller_id_name" type="string" toc={true}>
  Caller's display name.
</ParamField>

<ParamField path="caller_id_num" type="string" toc={true}>
  Caller's phone number.
</ParamField>

<ParamField path="project_id" type="string" toc={true}>
  SignalWire project ID.
</ParamField>

<ParamField path="space_id" type="string" toc={true}>
  SignalWire space ID.
</ParamField>

<ParamField path="app_name" type="string" toc={true}>
  AI application name.
</ParamField>

<ParamField path="global_data" type="object" toc={true}>
  The application's global data.
</ParamField>

<Indent>
  <ParamField path="global_data.*" type="any" toc={true}>
    User-defined property.
  </ParamField>
</Indent>

<ParamField path="meta_data" type="object" toc={true}>
  Function metadata (when `meta_data_token` is set).
</ParamField>

<Indent>
  <ParamField path="meta_data.*" type="any" toc={true}>
    User-defined property.
  </ParamField>
</Indent>

### Request body

When `params` is defined (or `method` is `POST`), SignalWire sends the `params` object as the JSON request body.
Template variables in `params` values are expanded before sending.

If no `params` are defined and `method` is not `POST`, the request is sent without a body.

If [`input_args_as_params`](#properties) is `true`, the function arguments extracted by the AI
are merged into `params`. If no `params` are defined, the arguments become the entire request body.

### Response processing

The JSON response from the webhook is processed through the [`output`](#output) template.
Fields from the response can be referenced using `%{key}` syntax in the output's `response` string.
For example, if the webhook returns `{"temp": 72, "conditions": "sunny"}`, an output of
`"The weather is %{temp}°F with %{conditions}"` will produce `"The weather is 72°F with sunny"`.

## **Examples**

### expressions

<CodeBlocks>
  <CodeBlock title="YAML">
    ```yaml
    data_map:
      expressions:
        - string: "starwars"
          pattern: "(?i)star\\s*wars"
          output:
            response: "May the Force be with you!"
        - string: "startrek"
          pattern: "(?i)star\\s*trek"
          output:
            response: "Live long and prosper!"
    ```
  </CodeBlock>

  <CodeBlock title="JSON">
    ```json
    {
      "data_map": {
        "expressions": [
          {
            "string": "starwars",
            "pattern": "(?i)star\\s*wars",
            "output": {
              "response": "May the Force be with you!"
            }
          },
          {
            "string": "startrek",
            "pattern": "(?i)star\\s*trek",
            "output": {
              "response": "Live long and prosper!"
            }
          }
        ]
      }
    }
    ```
  </CodeBlock>
</CodeBlocks>

### webhooks with explicit params

<CodeBlocks>
  <CodeBlock title="YAML">
    ```yaml
    data_map:
      webhooks:
        - url: https://api.example.com/weather
          method: POST
          params:
            call_id: "%{call_id}"
            city: "%{args.location}"
          output:
            response: "The weather in %{city} is %{temp}°F and %{conditions}."
    ```
  </CodeBlock>

  <CodeBlock title="JSON">
    ```json
    {
      "data_map": {
        "webhooks": [
          {
            "url": "https://api.example.com/weather",
            "method": "POST",
            "params": {
              "call_id": "%{call_id}",
              "city": "%{args.location}"
            },
            "output": {
              "response": "The weather in %{city} is %{temp}°F and %{conditions}."
            }
          }
        ]
      }
    }
    ```
  </CodeBlock>
</CodeBlocks>

Sends the following request body to `https://api.example.com/weather`:

```json
{
  "call_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "city": "New York"
}
```

### webhooks with input\_args\_as\_params

<CodeBlocks>
  <CodeBlock title="YAML">
    ```yaml
    data_map:
      webhooks:
        - url: https://api.example.com/weather
          method: POST
          input_args_as_params: true
          output:
            response: "The weather is %{temp}°F and %{conditions}."
    ```
  </CodeBlock>

  <CodeBlock title="JSON">
    ```json
    {
      "data_map": {
        "webhooks": [
          {
            "url": "https://api.example.com/weather",
            "method": "POST",
            "input_args_as_params": true,
            "output": {
              "response": "The weather is %{temp}°F and %{conditions}."
            }
          }
        ]
      }
    }
    ```
  </CodeBlock>
</CodeBlocks>

Sends the AI-extracted arguments directly as the request body:

```json
{
  "location": "New York"
}
```

### output with action

<CodeBlocks>
  <CodeBlock title="YAML">
    ```yaml
    sections:
      main:
        - ai:
            prompt:
              text: You are a helpful SignalWire assistant.
            SWAIG:
              functions:
                - function: test_function
                  description: This is a test function.
                  parameters:
                    type: object
                    properties:
                      name:
                        type: string
                        description: The name of the person.
                    required:
                      - name
                  data_map:
                    output:
                      response: We are testing the function.
                      action:
                        - SWML:
                            sections:
                              main:
                                - play:
                                    url: 'say:We are testing the function.'
    ```
  </CodeBlock>

  <CodeBlock title="JSON">
    ```json
    {
      "sections": {
        "main": [
          {
            "ai": {
              "prompt": {
                "text": "You are a helpful SignalWire assistant."
              },
              "SWAIG": {
                "functions": [
                  {
                    "function": "test_function",
                    "description": "This is a test function.",
                    "parameters": {
                      "type": "object",
                      "properties": {
                        "name": {
                          "type": "string",
                          "description": "The name of the person."
                        }
                      },
                      "required": [
                        "name"
                      ]
                    },
                    "data_map": {
                      "output": {
                        "response": "We are testing the function.",
                        "action": [
                          {
                            "SWML": {
                              "sections": {
                                "main": [
                                  {
                                    "play": {
                                      "url": "say:We are testing the function."
                                    }
                                  }
                                ]
                              }
                            }
                          }
                        ]
                      }
                    }
                  }
                ]
              }
            }
          }
        ]
      }
    }
    ```
  </CodeBlock>
</CodeBlocks>

### Related guides

* [Executing SWML from a SWAIG function](/docs/swml/guides/executing-swml)