SignalWire Markup Language (SWML) lets you define call control and AI behavior in JSON or YAML, and SignalWire AI Gateway (SWAIG) lets your AI agent trigger backend functions during a live call. This tutorial shows how to let a SWAIG function execute SWML outside the model, so the agent can do real telephony actions reliably, such as sending Short Message Service (SMS) messages, recording a call, and transferring the caller, while keeping the conversational layer focused on intent and data collection.
Understanding SWML and SWAIG
SignalWire Markup Language (SWML) is a powerful markup language expressed in YAML or JSON for managing call flows and AI Agents. SignalWire AI Gateway (SWAIG) enables functions that allow an AI voice agent to perform actions or connect with backend systems.
SWAIG allows you to execute SWML blocks that exist outside of the AI language model. This capability enhances control over AI conversational flows, enabling more precise actions and responses after a function is triggered, and allowing you to build a highly customizable AI assistant.
Incorporated into SignalWire's broader ecosystem, these underlying technologies support SignalWire’s Programmable Unified Communications (PUC) network. PUC brings together a programmable interface with a unified communications platform, providing easy-to-use, customizable communication solutions.
SWML is an essential tool within the network for customizing communication pathways, collecting data, or invoking AI agents, pushing the boundaries of what conversational AI can achieve. For building a custom AI agent beyond the capabilities of pre-made examples, you’ll have to learn to execute SWML from within a SWAIG function.
How to leverage SWML from within a function
In this post, we'll take a closer look at the requirements for successfully executing a SWML block from within a function. By crafting a SWML script, we’ll create an example AI agent that helps callers with information about the U.S. National Park Service.
In this scenario, the virtual agent not only answers questions, but also sends text messages with information, and transfers calls to specific departments. This demonstrates the seamless integration of SWAIG functions within AI interactions.
The video above guides you through setting up an AI agent using SWML, detailing the configuration of key functions that are designed to enhance user assistance.
Requirements
To get started, you’ll need a SignalWire account and a phone number. This example uses YAML, but you can use JSON if you prefer. To implement your script, navigate to Relay/SWML scripts.
In this example, we will be making a GET request to the National Park Service API in one of the functions, but this is only for demonstration purposes. You can create an AI agent that is an expert in anything you can imagine.
Breaking down the execution: Params and functions
To begin, set up the prompt instructions for the agent. It's essential to configure the AI assistant to support SWML execution in its functions. This is done by setting the swaig_allow_swml parameter to true within the AI's parameters section.
park_alert_lookup function:
The park_alert_lookup function allows the AI agent, Laura, to access real-time alerts from the National Park Service API based on the caller’s query. In this function we use the data_map parameter, enabling AI agents to process user inputs, perform actions based on these inputs, or interact with external APIs seamlessly.
Output in park_alert_lookup:
After fetching and processing alerts, the function generates a response for our agent to disclose the top alert's title and description. It then asks the caller if they wish to receive this information via SMS.
The action parameter within the output is where a list of actions can be performed upon matching. In this case, we are enabling the send_sms function, which allows the AI agent to send an SMS to the caller.
The send_sms function
The send_sms function is tasked with sending text messages to the caller containing park alerts. Unlike the park_alert_lookup function, which uses webhooks to retrieve data from an external source, send_sms leverages data_map.expressions for handling data internally and preparing it for action based on the AI's inputs.
Using data_map.expressions in send_sms:
Here, data_map.expressions processes the alerts_summary data to generate the SMS content. The configuration ensures any provided alert summary is processed, enabling a versatile approach to data handling within the AI's workflow.
Implementing the SWML block in the transfer function
The transfer function demonstrates the use of a SWML block to carry out a series of actions, such as notifying a department of an incoming call, playing a message, recording the call, and transferring the call.
This exploration into the advanced features of SWML and SWAIG functions highlights the potential for creating dynamic, responsive, and intelligent AI agents that can meet a wide array of user needs. Whether it's providing detailed information, facilitating communications, or executing specific actions based on user input, the power of SWML from functions is a game-changer in the realm of conversational AI.
Full example
Lastly, don’t forget to configure your chosen phone number to handle a call using your SWML script!
With SWML's flexibility, there's no limit to how you can innovate and enhance the user experience for communications applications. Whether you're building a customer service bot or an informational guide, these tools are here to make your AI assistant smarter, and your life easier.
Start building for free today by signing up for a SignalWire Space, exploring our developer documentation, and bringing your questions to our community on Discord.
Frequently asked questions
What is SignalWire Markup Language (SWML)?
SignalWire Markup Language (SWML) is a markup format expressed in JSON or YAML for defining call flows and AI agent behavior, including telephony actions like prompts, recording, and transfers.
What is SignalWire AI Gateway (SWAIG)?
SignalWire AI Gateway (SWAIG) enables functions that an AI voice agent can call to perform actions or connect with backend systems during a conversation.
Why execute SWML from a SWAIG function instead of handling everything in the model?
Executing SWML from a function keeps telephony actions deterministic and auditable, while letting the AI focus on collecting intent and parameters. It also makes it easier to run sequences like notify, play a message, record, then transfer, without trying to “prompt” the model into perfect call control.
What does swaig_allow_swml do?
swaig_allow_swml is a configuration flag that enables SWML execution from within SWAIG functions, which is required if your function output will include a SWML block to run call control steps.
What is data_map, and why is it used in SWAIG functions?
data_map is used to process inputs and map values for a function so the agent can transform caller data, pass arguments cleanly, and integrate with external APIs, such as retrieving data from a third-party service.
What is a practical pattern for SWML in functions?
Use one function to look up information from an external API, another function to send an SMS follow-up, and a transfer function that executes a SWML block to play a message, start recording, and transfer the call to the right destination.
