> 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. # data_map > Defines how a SWAIG function should process and respond to the user's input data. `functions[].data_map` defines how a [`SWAIG function`](/docs/swml/reference/calling/ai/swaig/functions) should process and respond to the user's input data. **`functions[].data_map`** `object` An object that processes function inputs and executes operations through expressions, webhooks, or direct output. --- > **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 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** **`data_map.expressions`** `object[]` 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. --- **`expressions[].string`** `string` — required The actual input or value from the user or system. --- **`expressions[].pattern`** `string` — required A regular expression pattern to validate or match the string. --- **`expressions[].output`** `object` — required Defines the response or action to be taken when the pattern matches. See [`output`](#output) for details. --- **`data_map.webhooks`** `object[]` An array of objects that define external API calls. If a webhook defines `foreach`, `expressions`, and `output`, they are evaluated in that order. --- **`webhooks[].url`** `string` — required 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. --- **`webhooks[].method`** `string` — required The HTTP method (GET, POST, etc.) for the API call. --- **`webhooks[].headers`** `object` Any necessary headers for the API call. --- **`webhooks[].params`** `object` An object of any necessary parameters for the API call. The key is the parameter name and the value is the parameter value. --- **`webhooks[].input_args_as_params`** `boolean` — default: false A boolean to determine if the input [parameters](/docs/swml/reference/calling/ai/swaig/functions/parameters) should be passed as parameters. --- **`webhooks[].required_args`** `string | string[]` A string or array of strings that represent the [parameters](/docs/swml/reference/calling/ai/swaig/functions/parameters) that are required to make the webhook request. --- **`webhooks[].error_keys`** `string | string[]` A string or array of strings that represent the keys to be used for error handling. --- **`webhooks[].expressions`** `object` A list of expressions to be evaluated upon matching. See [`expressions`](#expressions) for details. --- **`webhooks[].foreach`** `object` 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. --- **`foreach.input_key`** `string` — required The key to be used to access the current element in the array. --- **`foreach.output_key`** `string` — required 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. --- **`foreach.append`** `string` — required 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. --- **`foreach.max`** `number` The max amount of elements that are iterated over in the array. This will start at the beginning of the array. --- **`webhooks[].output`** `object` — required Defines the response or action to be taken when the webhook is successfully triggered. See [`output`](#output) for details. --- **`data_map.output`** `object` Similar to a `return` statement in conventional programming languages, the `data_map.output` object immediately terminates function execution and returns control to the caller. --- **`output.response`** `string` — required Static text that will be added to the AI agent's context. --- **`output.action`** `object[]` A list of SWML-compatible objects that are executed upon the execution of a SWAIG function. See [list of valid actions](#actions) for details. --- ### 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 **`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. --- ## **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). **`args`** `object` Function argument values extracted by the AI, keyed by argument name. --- **`args.*`** `any` Individual argument value. The key matches an argument name from the function's [`parameters`](/docs/swml/reference/calling/ai/swaig/functions/parameters) schema. --- **`call_id`** `string` Unique identifier for the current call. --- **`ai_session_id`** `string` AI session identifier. --- **`conversation_id`** `string` Conversation identifier. --- **`function`** `string` Name of the function being executed. --- **`caller_id_name`** `string` Caller's display name. --- **`caller_id_num`** `string` Caller's phone number. --- **`project_id`** `string` SignalWire project ID. --- **`space_id`** `string` SignalWire space ID. --- **`app_name`** `string` AI application name. --- **`global_data`** `object` The application's global data. --- **`global_data.*`** `any` User-defined property. --- **`meta_data`** `object` Function metadata (when `meta_data_token` is set). --- **`meta_data.*`** `any` User-defined property. --- ### 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 #### 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!" ``` #### 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!" } } ] } } ``` ### webhooks with explicit params #### 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}." ``` #### 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}." } } ] } } ``` 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 #### 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}." ``` #### 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}." } } ] } } ``` Sends the AI-extracted arguments directly as the request body: ```json { "location": "New York" } ``` ### output with action #### 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.' ``` #### 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." } } ] } } } ] } } } ] } } } ] } } ``` ### Related guides * [Executing SWML from a SWAIG function](/docs/swml/guides/executing-swml) > Defines how a SWAIG function should process and respond to the user's input data.