Skip to navigation

data_map

View as MarkdownOpen in Claude

functions[].data_map defines how a SWAIG function 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 is encountered within any component, it immediately terminates function execution. The output provides:

  1. A response string: the result the agent reads next
  2. An optional action: one or more actions to run once the agent has spoken its reply

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 test text against a regular expression. Expressions are tried in order, and the first one that returns a result ends the search.

expressions[].string
string

The text to test, after variable expansion. Set either string or expr, not both. If a document sets both at runtime, string is used.

expressions[].expr
string

Another name for string, used when string is not set: the text to test, after variable expansion. It is tested as text; it is not evaluated as an arithmetic or logical expression.

expressions[].pattern
string

A regular expression to match against the text. It matches case-insensitively unless written in /pattern/flags form. When omitted, the expression always matches.

expressions[].output
objectRequired

The result to return when the expression matches. See output for details.

expressions[].nomatch-output
object

The result to return when pattern doesn’t match. Returning it ends the search, as a match does. When omitted, the next expression is tried. See output for details.

data_map.webhooks
object[]

An array of objects that define external API calls. Webhooks are tried in order, and the first one whose response is used ends the search. If a webhook defines foreach, expressions, and output, they are evaluated in that order.

webhooks[].url
stringRequired

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 for details on template variable substitution and request behavior.

webhooks[].method
stringDefaults to GET

The HTTP method for the API call: GET or POST. The request is sent as a POST whenever it has a body, that is when params is set or input_args_as_params is true, whatever this is set to.

webhooks[].headers
object

Any necessary headers for the API call, as string values. Header values are sent exactly as written; a value that is not a string is skipped.

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[].form_param
string

Sends the request body as a single URL-encoded form field with this name, instead of as JSON. The whole JSON body becomes the value of that one field. Whenever this is set, the request’s Content-Type is application/x-www-form-urlencoded, even when the request has no body.

webhooks[].input_args_as_params
booleanDefaults to false

A boolean to determine if the input parameters should be passed as parameters.

webhooks[].error_keys
string[]

Keys that mark the API response as failed. When any of them is present at the top level of the response, whatever its value, the response is not used and the next webhook is tried.

webhooks[].expressions
object[]

An array of expressions evaluated against the API response, before output. See 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 method.

foreach.input_key
stringRequired

The key in the API response that holds the array to iterate over.

foreach.output_key
stringRequired

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
stringRequired

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
integerDefaults to 10

The maximum number of array elements to iterate over, starting at the beginning of the array.

webhooks[].output
object

The result to return when the API call succeeds and no expression returns a result. Each webhook needs output, expressions, or both; a webhook with neither is skipped. See 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

The result the agent reads next. When it is absent or not a string, the agent reads Function completed. and carries on.

output.action
object | object[]

An action, or a list of actions, to run once the agent has spoken its reply. See list of valid actions for details.

List of valid actions

One action object can set several of these keys, and each key that is set is applied. Other keys are ignored at runtime.

action[].SWML
object | string

A SWML document to run, as an object or as a JSON string. 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
booleanDefaults to false

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 true or false here; in a data_map output, a variable that expands to one of them also works. The object form that transfers to a named destination is specific to 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 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 to be referenced locally in the function.

See set_meta_data for additional details.

action[].unset_global_data
string | string[]

The key of the global data to unset from the global_data, 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, 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, and the string or expr of a top-level expression, 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 and scopes, see the Variables reference.

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 schema.

session_data
object

Details of the current session.

session_data.uuid
string

Unique identifier for the current call.

session_data.caller_id
string

The caller’s phone number.

session_data.global_data
object

The agent’s global_data.

session_data.meta_data
object

This function’s meta_data.

Request body

When params is set, SignalWire sends the params object as the JSON request body, as a POST. Template variables in params values are expanded before sending.

If no params are set and input_args_as_params is not true, the request is sent without a body.

If input_args_as_params 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 webhook’s foreach, expressions, and output templates. They can reference the response’s top-level fields with %{key} syntax, the agent’s global data as %{global_data.key}, and the template variables above under input, such as %{input.args.location}. 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".

A top-level data_map.output can reference the template variables above, and the agent’s global data as %{global_data.key}.

Examples

expressions

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

data_map:
webhooks:
- url: https://api.example.com/weather
method: POST
params:
call_id: "%{session_data.uuid}"
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:

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

webhooks with input_args_as_params

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:

{
"location": "New York"
}

output with action

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.'