SignalWire Markup Language (SWML) lets you define AI voice agents and call behavior as JSON or YAML, either as a static script or dynamically from your own web server. This guide shows how to run SWML from a Node.js server using Express and body-parser, exposing endpoints that return SWML instructions for an AI agent, then using SignalWire AI Gateway (SWAIG) to trigger actions like transferring calls and sending Short Message Service (SMS) messages. You will see the core pattern, a /start endpoint that defines the agent behavior, and a /transfer endpoint that returns action-focused SWML when the agent needs to escalate or follow up.

Build an AI Voice Agent with SignalWire Markup Language (SWML) and Node.js

SignalWire’s Programmable Unified Communications (PUC) represents a transformative approach to customization, rapid deployment, and interoperability. AI Agents integrate seamlessly into our PUC ecosystem, leveraging programmable actions to improve customer satisfaction and operational efficiency across communication channels​​​​.

Unlike rigid interactive voice response (IVR) systems, building an AI Agent from code allows you to define more personalized autonomous workflows that adapt in real-time to customer needs and preferences. Through functions, webhooks, and plain text instructions written with SignalWire Markup Language (SWML), PUC creates a versatile and powerful toolset for more effective customer interactions.

This brief tutorial will walk you through using SWML, in combination with a simple web server built in your preferred programming language, to create an AI Agent capable of sending SMS and transferring calls.

If you prefer a video format, you can follow along in the video below.

Setting up the environment

How you set up your web server is mostly specific to the language and framework of your choosing. The code snippets in this tutorial will be written in Node.js, using Express in conjunction with Body-Parser, to create a minimal and flexible web application framework. Node.js is a runtime environment that allows you to maneuver JavaScript server-side.

To get started, you'll need to install the necessary components. The express package is required for spinning up the web server that will host the SWML instructions defining your AI Agent’s behavior. The body-parser package is required for parsing incoming request bodies from SignalWire. Install them by running:

npm install express body-parser

Building the server

Handling calls from code allows for greater customization. Instead of creating your AI agent from a static SWML script, you can use a custom web server to execute specific functions based on the context of incoming or outgoing calls.

Your server will handle incoming POST requests to two endpoints: /start, which will define the AI agent's conversational flow, and /transfer, which will handle the sending of SMS and transferring of calls.

Import packages and initialize Express app

Begin by importing the installed packages, initializing the express app, and specifying which port your app should listen for requests on. We recommend using Ngrok as a tunnel for local testing. This example server will listen for incoming POST requests on port 3000.

The /start endpoint

The /start endpoint will initialize your AI agent. These instructions will define your agent’s personality, skills, and how they should manage the conversation. Between the boundaries of instructions, you can build SWML scripts the same as you would from your SignalWire dashboard.

The /transfer endpoint

This endpoint provides instructions for transferring calls and sending SMS messages, showcasing one pathway to handling specific user requests that require additional information or live assistance.

Understanding SWML instructions

SWML can be expressed in YAML or JSON. The SWML examples shown here will be authored in the JSON format.

SWAIG

The SignalWire AI Gateway (SWAIG) allows specific functions to call upon SWML scripts situated externally from the AI's core model. The primary advantage of SWAIG lies in the nuanced control over actions following function activation. For this example, the AI agent will be able to send SMS messages and transfer calls.

The AI parameter swaig_allow_swml will act as a conduit between your transfer function and the same endpoint that you’ll define soon. Executing SWML from a SWAIG function can be accomplished using a webhook, or when utilizing the Data Map. This example hinges on the use of webhooks.

The web_hook_url will be a designated endpoint for a response containing the intended action. This action contains the specified SWML script next in line to be executed.

Point web_hook_url to your /transfer endpoint. Your endpoint may respond with the following SWML methods to send_sms and connect calls:

SWML provides call object parameters, such as call.to and call.from, to be referenced within ${} JavaScript expressions.

Full example

Running your server

To run your server, use the following command in the terminal:

node <filename>.js

Replace <filename> with the name of your main server file.

You've now set up a basic SignalWire AI agent using SWML and Node.js. This agent can guide users through transferring calls to their desired destination while simultaneously sending an SMS.

For more advanced features and customization options, explore the developer documentation and experiment with different SWML components to enhance your AI agent's interactivity and intelligence.

By customizing the SWML instructions, you can expand your agent’s capabilities to handle a wide range of conversational scenarios, making them an invaluable asset to your team. If you have questions as you build, bring them to our team of experts on Discord!

Frequently asked questions

What is SignalWire Markup Language (SWML)?

SignalWire Markup Language (SWML) is a markup and scripting format for defining voice and AI applications as JSON or YAML, including agent instructions and call behaviors that can be executed from the SignalWire platform.

When should you serve SWML from your own web server instead of using a static script?

Serve SWML from your own server when you need dynamic behavior, such as branching logic based on request context, generating different instructions for different callers, or running actions only when certain conditions are met, instead of using a fixed, static SWML file.

What is SignalWire AI Gateway (SWAIG), and what does it enable?

SignalWire AI Gateway (SWAIG) enables function-style actions that can call out to externally hosted SWML, which lets an AI agent trigger specific operations and then execute the next SWML step returned by your webhook.

How do you transfer a call from an AI agent using SWML?

A common pattern is using SWAIG to invoke a transfer-related function, then returning SWML from your webhook that executes the transfer step inside the call flow, for example by responding from a dedicated endpoint such as /transfer.

How do you send an SMS message from an AI agent during a call?

You can expose an action endpoint that returns SWML instructions for sending a text message, then let the agent trigger that action through SWAIG when it needs to confirm details, share a link, or provide follow-up information.

What are the minimum endpoints you need for a dynamic SWML AI agent?

This tutorial’s baseline pattern uses two POST endpoints, one to return the agent’s starting instructions (/start) and one to return action instructions (/transfer) for transfers and SMS.