Callingai
SignalWire DocsThe SignalWire AI Gateway Interface. Allows you to create user-defined functions that can be executed during the dialogue.
An object that accepts the following properties.
Default settings for all SWAIG functions. If defaults is not set, settings may be set in each function object. Default is not set.
The default URL to send status callbacks and reports to for all SWAIG functions. If defaults is not set, web_hook_url may be set in each SWAIG function object. Authentication can also be set in the url in the format of username:password@url.
An array of JSON objects to define functions that can be executed during the interaction with the AI. Default is not set. The fields of this object are the six following.
See functions for additional details.
An array of objects to include remote function signatures. This allows you to include functions that are defined in a remote location.
See includes for additional details.
An object that defines language-specific filler phrases for internal SWAIG functions. These fillers help break silence between responses and are played asynchronously during function execution. Each key is a function name, and each value is an object mapping language codes to arrays of filler phrases.
Filler phrases played when the AI Agent is hanging up the call.
Filler phrases played when the AI Agent is checking the time.
Filler phrases played when the AI Agent is waiting for user input.
Filler phrases played during deliberate pauses or wait periods.
Filler phrases played when the AI Agent is adjusting response timing.
Filler phrases played when transitioning between conversation steps when utilizing prompt.contexts.
Filler phrases played when switching between conversation contexts when utilizing prompt.contexts.
Filler phrases played when the AI Agent is processing visual input. Enabled when enable_vision is set to true in ai.params.
Filler phrases played when the AI Agent is thinking or considering options. Enabled when enable_thinking is set to true in ai.params.
Prebuilt functions the AI agent is able to call.
The agent is already aware of these functions and can use them creatively based on prompting.
For example, a prompt like “tell the user what time it is” will automatically use check_time.
Accepted values:
adjust_response_latency - Adjust how long the agent will wait for the user to stop talking.check_time - Returns the current time for the time zone set in ai.local_tz.wait_for_user - Causes the AI to wait until the user speaks again. Use when the user asks to wait or hold on.wait_seconds - Waits for the given amount of time.An array of MCP (Model Context Protocol) servers whose tools and resources are made available to the AI. Each server’s tools are discovered at startup and registered as callable functions, so they can be invoked like any other SWAIG function.
The MCP server URL.
HTTP headers sent to the MCP server. Authorization tokens go here — there is no separate auth field. Header values support variable expansion (e.g. Bearer ${global_data.token}).
Whether to fetch the server’s resources into global_data, when the server advertises resource support.
Template variables passed to the MCP server when fetching resources. Used only when resources is enabled.
Several SWAIG properties accept filler phrases keyed by language code, including internal_fillers and per-function fillers. The following language codes are supported across all filler configurations.
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.
Static text that will be added to the AI agent’s context.
A list of SWML-compatible objects that are executed upon the execution of a SWAIG function.
A SWML object to be executed.
A message to be spoken by the AI agent.
Whether to stop the conversation.
Whether to hang up the call. When set to true, the call will be terminated after the AI agent finishes speaking.
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:
120 for 120 seconds)timeout propertyDefault timeout is 300 seconds (5 minutes). Maximum timeout is 900 seconds (15 minutes).
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:
ai_unhold command to programmatically unhold the call with a custom prompt.The duration to hold the caller in seconds. Maximum is 900 seconds (15 minutes).
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.
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.
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.
The name of the SWAIG function to toggle.
Whether to activate or deactivate the function.
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.
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.
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.
The key of the metadata to unset from the meta_data. You can also reset the meta_data by passing in a new object.
A JSON object containing the audio file to play.
URL or filepath of the audio file to play. Authentication can also be set in the url in the format of username:password@url.
Whether to wait for the audio file to finish playing before continuing.
Whether to stop the background audio file.
Used to inject text into the users queue as if they input the data themselves.
A JSON object containing the context to switch to.
See context_switch for additional details.
The instructions to send to the agent.
Whether to consolidate the context.
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.
Transfer the call to a new destination.
The destination to transfer to (phone number, SIP URI, or SWML URL).
Whether to include a conversation summary when transferring.
SignalWire will make a request to the web_hook_url of a SWAIG function with the following parameters:
The unique identifier for the current call.
The unique identifier for the AI session.
The project ID associated with the call.
The Space ID associated with the call.
Name of the caller.
Number of the caller.
Global data set via the set_global_data action, as a key-value map.
Content disposition identifier (e.g., "SWAIG Function").
Whether the channel is currently active.
Whether the channel is off-hook.
Whether the channel is ready.
Type of content. The value will be text/swaig.
Name of the application that originated the request.
Name of the function that was invoked.
A JSON object containing any user metadata, as a key-value map.
A collection of variables related to SWML.
The purpose of the function being invoked. The value will be the functions.purpose value you provided in the SWML Function properties.
The description of the argument being passed. This value comes from the argument you provided in the SWML Function properties.
The argument the AI agent is providing to the function. The object contains the three following fields.
If a JSON object is detected within the argument, it is parsed and provided here.
The raw argument provided by the AI agent.
The argument provided by the AI agent, excluding any JSON.
Version number.
Below is a json example of the callback request that is sent to the web_hook_url:
success | failedsuccess | failed