data_map | SignalWire

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:

expressions - Processes data using pattern matching (includes its own output)
webhooks - Makes external API calls (includes its own output and expressions)
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:

An optional response: the result the AI agent reads next, as a string or an object
An optional action: an action, or a list of 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. Expressions are tried in order; the first one that matches returns its output. Each expression sets either string with pattern, or expr.

expressions[].string

string

The value to test, after variable expansion, such as %{args.reason}. Matched against pattern. Required unless expr is set.

expressions[].pattern

string

A regular expression to match against string. It matches case-insensitively unless written in /pattern/flags form. Required with string.

expressions[].expr

string

An expression evaluated after variable expansion, used instead of string. The expression matches when it evaluates to a nonzero value. When it doesn’t match and pattern is set, pattern is tried against the same text.

expressions[].output

objectRequired

Defines the response or action to be taken when the expression matches. See output for details.

expressions[].nomatch-output

object

The result to return when the expression doesn’t match, in the same shape as output. When omitted, the next expression is tried.

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. Each webhook needs output, expressions, or both. See webhook runtime request for how the webhooks are tried.

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. A request with a body, which it has when params is set or input_args_as_params is true, is always sent as a POST, 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; variables in them are not expanded.

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

booleanDefaults to false

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

webhooks[].require_args

string | string[]

The names of function arguments that must be present for this webhook to be used. With an array, any one of the listed arguments is enough. An argument counts as present when the AI supplied it, whatever its value. An empty array means the webhook is never used. When the condition isn’t met, the next webhook is tried.

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. Required unless output is set. 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 to be used to access the current element in the array.

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

integer

The max amount of elements that are iterated over in the array. This will start at the beginning of the array.

webhooks[].output

object

Defines the response or action to be taken when the webhook is successfully triggered. Required unless expressions is set. 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 | object

The result the agent reads next. A string becomes the tool message as written. An object splits it into tool_result, the data the agent reads, and tool_prompt, an instruction added right after it. When omitted, the agent gets a default result.

output.action

object | object[]

An action, or a list of actions, for the platform to perform on the call. See list of valid actions for details.

output.post_process

booleanDefaults to false

If true, the actions run after the agent has spoken its reply rather than immediately.

List of valid actions

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 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 timeout, and optionally step and timeout_step

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 to programmatically unhold the call with a custom prompt.

hold.timeout

integerDefaults to 300

The duration to hold the caller in seconds. Maximum is 900 seconds (15 minutes).

hold.step

string

The step to move to when the caller is taken off hold. When omitted, the conversation stays on the current step. Applies only if the hold starts.

hold.timeout_step

string

The step to move to when the hold times out without the caller being taken off hold. When omitted, the conversation stays on the current step. Applies only if the hold starts.

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 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 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. A function can only toggle functions that have the same meta_data_token as itself.

See toggle_functions for additional details.

toggle_functions[].function

stringRequired

The name of the SWAIG function to toggle. One name per object; to toggle several functions, add an object for each.

toggle_functions[].active

booleanDefaults to 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 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 to remove from global_data, or an array of keys to remove.

action[].unset_meta_data

string | string[]

The key to remove from the function’s meta_data, or an array of keys to remove.

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

booleanDefaults to false

Whether to wait for the audio file to finish playing before continuing.

action[].stop_playback_bg

boolean

Stops the background audio file. The action runs whenever the key is present, whatever its value, so false also stops playback. Leave the key out to keep playing.

action[].user_input

string

Used to inject text into the users queue as if they input the data themselves.

action[].context_switch

object

Replaces the agent’s instructions mid-conversation. You can use variables in system_prompt, user_prompt, system_pom, and user_pom. In a data_map function they’re expanded along with the rest of the output; in a reply from your web_hook_url, they’re expanded when the action runs. Either way they’re expanded only once, so a value that itself contains ${...} is left as it is.

See context_switch for additional details.

context_switch.system_prompt

string

The new instructions for the agent. Set this or system_pom.

context_switch.system_pom

object

The new instructions as an object with text or pom, the same shape as a prompt. Used instead of system_prompt when both are set.

context_switch.consolidate

booleanDefaults to false

If true, the conversation so far is summarized and the summary is carried into the new context. When the caller hasn’t spoken yet there’s nothing to summarize, so full_reset is ignored.

context_switch.full_reset

booleanDefaults to false

If true, the new instructions replace the agent’s original prompt. Otherwise the conversation is cleared and the new instructions are added.

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.

context_switch.user_pom

object

The simulated user input as an object with text or pom. Used instead of user_prompt when both are set.

action[].settings

object

Changes the AI model’s settings for the rest of the conversation, as a key-value map. Only settings the selected model supports are applied. Requires params.swaig_allow_settings, which is on by default. The new map replaces the current settings: any setting you leave out, including one set on prompt, returns to the model’s default.

action[].user_event

object

Sends a custom event to the client connected to the call, with this object as its payload, like the user_event method.

action[].transfer

boolean | string | 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 or string — use on its own, without SWML, to end the AI session and transfer the call to the destination configured with the fields below. A string is shorthand for transfer.dest.

transfer.dest

stringRequired

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

booleanDefaults to false

Whether to include a conversation summary when transferring.

Webhook runtime request

When the AI triggers a function that uses data_map.webhooks, SignalWire tries the webhooks in order. A webhook whose require_args aren’t met is skipped. The first webhook that is called is the only one used: later webhooks aren’t called, even when the request fails or error_keys marks the response as failed. In that case the function falls back to data_map.output.

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

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, SignalWire sends the params object as the JSON request body (or as a single URL-encoded form field when form_param is set), as a POST. 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 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 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

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: "%{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:

{
  "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:
    - 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.'

Executing SWML from a SWAIG function