MethodsaiSWAIGfunctions

data_map

View as Markdown

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

The actual input or value from the user or system.

expressions[].pattern
stringRequired

A regular expression pattern to validate or match the string.

expressions[].output
objectRequired

Defines the response or action to be taken when the pattern matches. See 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
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
stringRequired

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
booleanDefaults to false

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

webhooks[].required_args
string | string[]

A string or array of strings that represent the 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 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
number

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

webhooks[].output
objectRequired

Defines the response or action to be taken when the webhook is successfully triggered. 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
stringRequired

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

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

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.

See toggle_functions for additional details.

toggle_functions[].function
stringRequired

The name of the SWAIG function to toggle.

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

The key of the global data to unset from the global_data. 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. 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
booleanDefaults to 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 for additional details.

context_switch.system_prompt
string

The instructions to send to the agent.

context_switch.consolidate
booleanDefaults to 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
object

Transfer the call to a new destination.

transfer.dest
string

The destination to transfer to (phone number, SIP URI, or SWML URL).

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

1data_map:

2  expressions:

3    - string: "starwars"

4      pattern: "(?i)star\\s*wars"

5      output:

6        response: "May the Force be with you!"

7    - string: "startrek"

8      pattern: "(?i)star\\s*trek"

9      output:

10        response: "Live long and prosper!"

webhooks with explicit params

1data_map:

2  webhooks:

3    - url: https://api.example.com/weather

4      method: POST

5      params:

6        call_id: "%{call_id}"

7        city: "%{args.location}"

8      output:

9        response: "The weather in %{city} is %{temp}°F and %{conditions}."

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

1{

2  "call_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",

3  "city": "New York"

4}

webhooks with input_args_as_params

1data_map:

2  webhooks:

3    - url: https://api.example.com/weather

4      method: POST

5      input_args_as_params: true

6      output:

7        response: "The weather is %{temp}°F and %{conditions}."

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

1{

2  "location": "New York"

3}

output with action

1sections:

2  main:

3    - ai:

4        prompt:

5          text: You are a helpful SignalWire assistant.

6        SWAIG:

7          functions:

8            - function: test_function

9              description: This is a test function.

10              parameters:

11                type: object

12                properties:

13                  name:

14                    type: string

15                    description: The name of the person.

16                required:

17                  - name

18              data_map:

19                output:

20                  response: We are testing the function.

21                  action:

22                    - SWML:

23                        sections:

24                          main:

25                            - play:

26                                url: 'say:We are testing the function.'