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 Slack, Discord, or our community forum!