functions | SignalWire

An array of JSON objects to define functions that can be executed during the interaction with the AI.

Properties

SWAIG.functions

object[]

An array of JSON objects that accept the following properties.

functions[].description

stringRequired

A description of the context and purpose of the function, to explain to the agent when to use it.

functions[].function

stringRequired

A unique name for the function. This can be any user-defined string or can reference a reserved function. Reserved functions are SignalWire functions that will be executed at certain points in the conversation. To learn more about reserved functions, see Reserved Functions.

functions[].active

booleanDefaults to true

Whether the function is active.

functions[].data_map

object

An object that processes function inputs and executes operations through expressions, webhooks, or direct output. Properties are evaluated in strict priority order: (1) expressions, (2) webhooks, (3) output. Evaluation stops at the first property that returns a valid output result, similar to a return statement in a function.

See data_map for additional details.

functions[].parameters

object

A JSON object that defines the expected user input parameters and their validation rules for the function.

See parameters for additional details.

functions[].fillers

object

An object containing language-specific arrays of filler phrases that are played when calling a SWAIG function. These fillers help break silence between responses and are played asynchronously during the function call. Each key is a language code and each value is an array of filler phrases selected from randomly.

functions[].skip_fillers

booleanDefaults to false

Skips the top-level fillers specified in ai.languages (which includes speech_fillers and function_fillers). When set to true, only function-specific fillers defined directly on SWAIG.functions.fillers will play.

functions[].meta_data

object

A powerful and flexible environmental variable which can accept arbitrary data that is set initially in the SWML script or from the SWML set_meta_data action. This data can be referenced locally to the function. All contained information can be accessed and expanded within the prompt - for example, by using a template string.

functions[].meta_data_token

stringDefaults to Set by SignalWire

Scoping token for meta_data. If not supplied, metadata will be scoped to function’s web_hook_url.

functions[].wait_file

string

A file to play while the function is running. wait_file_loops can specify the amount of times that files should continously play.

functions[].wait_file_loops

string | integer

The amount of times that wait_file should continuously play/loop.

functions[].wait_for_fillers

booleanDefaults to false

Whether to wait for fillers to finish playing before continuing with the function.

functions[].web_hook_url

string

Function-specific URL to send status callbacks and reports to. Takes precedence over a default setting. Authentication can also be set in the url in the format of username:password@url.

functions[].purpose

stringDeprecated

Deprecated. Use description instead.

functions[].argument

objectDeprecated

Deprecated. Use parameters instead.

Webhook response

When a SWAIG function is executed, the function expects the user to respond with a JSON object that contains a response key and an optional action key. This request response is used to provide the LLM with a new prompt response via the response key and to execute SWML-compatible objects that will perform new dialplan actions via the action key.

response

stringRequired

Static text that will be added to the AI agent’s context.

action

object[]

A list of SWML-compatible objects that are executed upon the execution of a SWAIG function.

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 response example

1 {
2   "response": "Oh wow, it's 82.0°F in Tulsa. Bet you didn't see that coming! Humidity at 38%. Your hair is going to love this! Wind speed is 2.2 mph. Hold onto your hats, or don't, I'm not your mother! Looks like Sunny. Guess you'll survive another day.",
3   "action": [
4     {
5       "set_meta_data": {
6         "temperature": 82.0,
7         "humidity": 38,
8         "wind_speed": 2.2,
9         "weather": "Sunny"
10       }
11     },
12     {
13       "SWML": {
14         "version": "1.0.0",
15         "sections": {
16           "main": [
17             {
18               "play": {
19                 "url": "https://example.com/twister.mp3"
20               }
21             }
22           ]
23         }
24       }
25     }
26   ]
27 }

Callback Request for web_hook_url

SignalWire will make a request to the web_hook_url of a SWAIG function with the following parameters:

call_id

string

The unique identifier for the current call.

ai_session_id

string

The unique identifier for the AI session.

project_id

string

The project ID associated with the call.

space_id

string

The Space ID associated with the call.

caller_id_name

string

Name of the caller.

caller_id_num

string

Number of the caller.

global_data

object

Global data set via the set_global_data action, as a key-value map.

content_disposition

string

Content disposition identifier (e.g., "SWAIG Function").

channel_active

boolean

Whether the channel is currently active.

channel_offhook

boolean

Whether the channel is off-hook.

channel_ready

boolean

Whether the channel is ready.

content_type

string

Type of content. The value will be text/swaig.

app_name

string

Name of the application that originated the request.

function

string

Name of the function that was invoked.

meta_data

object

A JSON object containing any user metadata, as a key-value map.

SWMLVars

object

A collection of variables related to SWML.

purpose

string

The purpose of the function being invoked. The value will be the functions.purpose value you provided in the SWML Function properties.

argument_desc

string | object

The description of the argument being passed. This value comes from the argument you provided in the SWML Function properties.

argument

object

The argument the AI agent is providing to the function. The object contains the three following fields.

argument.parsed

object

If a JSON object is detected within the argument, it is parsed and provided here.

argument.raw

string

The raw argument provided by the AI agent.

argument.substituted

string

The argument provided by the AI agent, excluding any JSON.

version

string

Version number.

Webhook request example

Below is a json example of the callback request that is sent to the web_hook_url:

1 {
2   "app_name": "swml app",
3   "global_data": {
4     "caller_id_name": "",
5     "caller_id_number": "sip:guest-246dd851-ba60-4762-b0c8-edfe22bc5344@46e10b6d-e5d6-421f-b6b3-e2e22b8934ed.call.signalwire.com;context=guest"
6   },
7   "project_id": "46e10b6d-e5d6-421f-b6b3-e2e22b8934ed",
8   "space_id": "5bb2200d-3662-4f4d-8a8b-d7806946711c",
9   "caller_id_name": "",
10   "caller_id_num": "sip:guest-246dd851-ba60-4762-b0c8-edfe22bc5344@46e10b6d-e5d6-421f-b6b3-e2e22b8934ed.call.signalwire.com;context=guest",
11   "channel_active": true,
12   "channel_offhook": true,
13   "channel_ready": true,
14   "content_type": "text/swaig",
15   "version": "2.0",
16   "content_disposition": "SWAIG Function",
17   "function": "get_weather",
18   "argument": {
19     "parsed": [
20       {
21         "city": "Tulsa",
22         "state": "Oklahoma"
23       }
24     ],
25     "raw": "{\"city\":\"Tulsa\",\"state\":\"Oklahoma\"}"
26   },
27   "call_id": "6e0f2f68-f600-4228-ab27-3dfba2b75da7",
28   "ai_session_id": "9af20f15-7051-4496-a48a-6e712f22daa5",
29   "argument_desc": {
30     "properties": {
31       "city": {
32         "description": "Name of the city",
33         "type": "string"
34       },
35       "country": {
36         "description": "Name of the country",
37         "type": "string"
38       },
39       "state": {
40         "description": "Name of the state",
41         "type": "string"
42       }
43     },
44     "required": [],
45     "type": "object"
46   },
47   "purpose": "Get weather with sarcasm"
48 }

Variables

ai_result: (out) success | failed
return_value: (out) success | failed

Reserved Functions

Reserved functions are special SignalWire functions that are automatically triggered at specific points during a conversation. You define them just like any other SWAIG function, but their names correspond to built-in logic on the SignalWire platform, allowing them to perform specific actions at the appropriate time.

Function name conflicts

Do not use reserved function names for your own SWAIG functions unless you want to use the reserved function’s built-in behavior. Otherwise, your function may not work as expected.

List of Reserved Functions

start_hook

function

Triggered when the call is answered. Sends the set properties of the function to the defined web_hook_url.

stop_hook

function

Triggered when the call is ended. Sends the set properties of the function to the defined web_hook_url.

summarize_conversation

function

Triggered when the call is ended. The post_prompt must be defined for this function to be triggered. Provides a summary of the conversation and any set properties to the defined web_hook_url.

Where are my function properties?

If the AI is not returning the properties you set in your SWAIG function, it may be because a reserved function was triggered before those properties were available. To ensure your function receives all necessary information, make sure the AI has access to the required property values before the reserved function is called. Any property missing at the time the reserved function runs will not be included in the data sent back.

Diagram examples

SWML Examples

Using SWAIG Functions

1 version: 1.0.0
2 sections:
3   main:
4     - ai:
5         post_prompt_url: "https://example.com/my-api"
6         prompt:
7           text: |
8             You are a helpful assistant that can provide information to users about a destination.
9             At the start of the conversation, always ask the user for their name.
10             You can use the appropriate function to get the phone number, address,
11             or weather information.
12         post_prompt:
13           text: "Summarize the conversation."
14         SWAIG:
15           includes:
16             - functions:
17                 - get_phone_number
18                 - get_address
19               url: https://example.com/functions
20               user: me
21               pass: secret
22           defaults:
23             web_hook_url: https://example.com/my-webhook
24             web_hook_auth_user: me
25             web_hook_auth_pass: secret
26           functions:
27             - function: get_weather
28               description: To determine what the current weather is in a provided location.
29               parameters:
30                 properties:
31                   location:
32                     type: string
33                     description: The name of the city to find the weather from.
34                 type: object
35             - function: summarize_conversation
36               description: Summarize the conversation.
37               parameters:
38                 type: object
39                 properties:
40                   name:
41                     type: string
42                     description: The name of the user.