> 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/amazon-bedrock/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/amazon-bedrock/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/amazon-bedrock/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 [set_meta_data]: /docs/swml/guides/set-meta-data [properties]: /docs/swml/reference/calling/amazon-bedrock#properties **`action[].SWML`** `object | string` A SWML object to be executed. By default it runs inline and the agent resumes the conversation afterward. Pair it with a sibling `action[].transfer` set to `true` to hand the call off to that SWML instead and end the agent. --- **`action[].transfer`** `boolean` Use alongside a sibling `action[].SWML` payload in the same action object. When `true`, ends the agent and hard-transfers the call to that SWML. When omitted or `false`, the SWML executes inline and the agent continues afterward. Bedrock agents accept only this boolean form. The object form that transfers to a named destination is specific to [`ai`](/docs/swml/reference/calling/ai) agents. --- **`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 | string[]` The key of the global data to unset from the [`global_data`][properties], or an array of keys to unset several at once. --- **`action[].unset_meta_data`** `string | string[]` The key of the metadata to unset from the [`meta_data`][properties], or an array of keys to unset several at once. --- ## **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/amazon-bedrock/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: - amazon_bedrock: 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": [ { "amazon_bedrock": { "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." } } ] } } } ] } } } ] } } } ] } } ``` > Defines how a SWAIG function should process and respond to the user's input data.