Skip to navigation

Pick the right SignalWire product

What each product does, when to use it, and how they work together
View as MarkdownOpen in Claude

A SignalWire app can make and receive phone calls with an AI agent, put calls and chat in a web page, and text your customers. You build it from four products (SWML, the REST APIs, the Browser SDK, and Relay), and most apps combine more than one. This page explains what each product does, which one fits your use case, and how they fit together. For the setup steps that come first, see Get started.

Calls are where the products differ most, so most of this page is about calls. Text conversations with an AI agent covers AI chat, and Messaging and fax covers texting and faxing. If you’re moving an existing Twilio application, start with the Compatibility API instead. It replaces Twilio’s REST API and TwiML with few code changes, but it doesn’t support AI, so this page covers SignalWire’s native products.

How most SignalWire apps are built

Write your AI agents and call flows as SWML with the Agents namespace of the Server SDKs, and use its REST namespace to send commands to live calls and manage your Resources.

A SWML script is a JSON or YAML document that defines the dialplan: a set of rules for how the call proceeds and how it responds to the caller, such as forwarding the call, recording a voicemail, or running a full IVR system. The Agents namespace generates, validates, and serves that document, and can change it for each call based on the request. SWML’s ai method runs a conversation with an AI agent on the call, and SWML methods can send status callbacks to your server as the call progresses.

A caller on a phone, SIP, or a browser reaches a phone number or Address, which points at a SWML Script Resource set to an external URL. Your server application uses the Server SDKs. The Resource fetches SWML from the agent, built with the Agents namespace, and SignalWire runs the live call. During the call, the live call calls SWAIG tools on the agent, which looks up data in your business logic. The REST client, built with the REST namespace of the same Server SDKs, sends call commands over HTTP to the live call and provisions numbers, Resources, and Subscribers in your Space.
  1. A phone number or Address points at a Resource. For a call you build in code, that Resource is a SWML Script set to an external URL that points at the agent running on your server.
  2. When a call arrives, SignalWire sends your server a POST request with the call context, and runs the SWML document your server returns: answering, speaking, listening, recording, and running the AI conversation.
  3. When the AI needs data or needs to act, such as looking up a booking, it calls a tool on your server through SWAIG (the SignalWire AI Gateway). The reply can steer the conversation and trigger actions on the call.
  4. At any point, your backend can send the call a command through the REST APIs: inject a message into the conversation, start a recording, play audio, or transfer the call.

For example, this dialplan for Bayview Taxi asks the caller to press 1 for Ada, the AI dispatcher, or 2 for a person, then routes the call. When Ada’s conversation ends, her post_prompt asks the AI for a summary, and SignalWire posts it to the post_prompt_url on your server. The Server SDK tabs each generate the SWML in the YAML tab.

from signalwire import SWMLService
bayview = SWMLService(name="bayview-taxi", route="/bayview")
bayview.answer()
bayview.prompt(
play=["say:Thanks for calling Bayview Taxi. Press 1 to book with Ada, our AI dispatcher, or 2 to speak with a person."],
max_digits=1,
)
bayview.switch(
variable="prompt_value",
case={
"1": [{"execute": {"dest": "ada"}}],
"2": [{"execute": {"dest": "person"}}],
},
default=[{"play": {"url": "say:Sorry, I didn't get that. Goodbye."}}, {"hangup": {}}],
)
bayview.add_section("ada")
bayview.add_verb_to_section("ada", "ai", {
"prompt": {"text": "You are Ada, the dispatcher for Bayview Taxi. Help the caller book a ride."},
"post_prompt": {"text": "Summarize the call in two sentences, including the pickup address."},
"post_prompt_url": "https://example.com/call-summary",
})
bayview.add_section("person")
bayview.add_verb_to_section("person", "connect", {"to": "<YOUR_DESTINATION>"})
bayview.serve()

The Server SDKs protect your server with basic auth. Set SWML_BASIC_AUTH_USER and SWML_BASIC_AUTH_PASSWORD environment variables, and put the same credentials in the SWML Script Resource’s URL, as in https://user:pass@your-server.com/bayview.

To steer a live call, like the one the dialplan above answered, send it a Calling API command from anywhere, at any time. This one ends a call with a message:

from signalwire.rest import RestClient
client = RestClient(project="<YOUR_PROJECT_ID>", token="<YOUR_API_TOKEN>", host="<YOUR_SPACE>.signalwire.com")
client.calling.transfer(
"<YOUR_CALL_ID>",
dest={
"version": "1.0.0",
"sections": {
"main": [
{"play": {"url": "say:Sorry, we need to end this call for server maintenance. Please call back in 20 minutes."}},
{"hangup": {}},
]
},
},
)

Replace the placeholders with the values from your API credentials page and <YOUR_CALL_ID> with the ID of the call to end.

The products

ProductDescriptionWhere your code runsUse cases
SWMLJSON or YAML call flow, generated by the Server SDKsYour web server, or nowhere when SignalWire hosts the documentCall flows and AI agents (the recommended starting point)
REST APIsHTTP endpoints for resources, messaging, and call commandsAny server or scriptProvisioning, outbound calls and messages, and controlling calls in progress
Browser SDKJavaScript client for voice, video, and chatThe user’s browserCalling and chat from a web page
RelayPersistent connection that streams call events to your codeA long-running process you hostEvent-driven, step-by-step call control

SWML

SWML (SignalWire Markup Language) describes how a call should go: answer, play a greeting, run an AI agent, record, transfer. With the Agents namespace of the Server SDKs, you create an agent, give it a prompt and tools, and run it as a web server.

Use it for any call your code handles, with or without AI. For a fixed flow with no server of your own, you can paste the document into a SWML Script in your Dashboard, and SignalWire hosts it.

The call runs on SignalWire, so your server only answers short HTTP requests: one for the document and one for each tool call. Nothing holds a connection open, so your server stays stateless and deploys anywhere that serves HTTPS. The Server SDKs quickstart builds your first agent. This one gives Ada a tool that looks up a ride:

from signalwire import AgentBase, FunctionResult
def lookup_ride(booking_id):
"""Stands in for your booking system."""
return {"booking_id": booking_id, "eta": 7}
agent = AgentBase(name="ada", route="/agent")
agent.prompt_add_section("Role", body="You are Ada, the dispatcher for Bayview Taxi. Help callers check on their ride.")
def check_ride(args, raw_data):
ride = lookup_ride(args["booking_id"])
return FunctionResult(f"The driver arrives in {ride['eta']} minutes.")
agent.define_tool(
name="check_ride",
description="Look up a ride by its booking ID",
parameters={
"type": "object",
"properties": {"booking_id": {"type": "string", "description": "The booking ID"}},
"required": ["booking_id"],
},
handler=check_ride,
)
agent.run()

Replace the ride lookup with a call to your booking system.

REST APIs

The REST APIs cover everything that isn’t the call flow itself. You buy phone numbers, create Resources and Subscribers, issue client tokens, send messages, fetch recordings and logs, and upload documents to Datasphere. From code, the REST namespace of the Server SDKs wraps each endpoint in a method.

The Calling API controls live calls. Its dial command starts a new call, and its call commands act on a call in progress: calling.play, calling.record, calling.transfer, calling.ai_message, calling.ai_hold, calling.end, and more than thirty others. Relay offers the same kind of call control over its WebSocket.

from signalwire.rest import RestClient
client = RestClient(project="<YOUR_PROJECT_ID>", token="<YOUR_API_TOKEN>", host="<YOUR_SPACE>.signalwire.com")
client.phone_numbers.set_swml_webhook("<YOUR_PHONE_NUMBER_ID>", url="https://example.com/bayview")
client.calling.dial(from_="<YOUR_CALLER_ID>", to="<YOUR_DESTINATION>", url="https://example.com/bayview")
client.calling.ai_message("<YOUR_CALL_ID>", role="system", message_text="Driver Sam has arrived.")
client.messages.create(from_="<YOUR_CALLER_ID>", to="<YOUR_DESTINATION>", body="Your Bayview Taxi driver is outside.")

Browser SDK

The Browser SDK (@signalwire/js) puts voice, video, and chat in a web page. A signed-in user can dial an Address, such as the one your agent answers, and receive calls addressed to them. Your backend creates each user a short-lived Subscriber token with the REST APIs, since an API token never belongs in a browser. For a public “call us” button, the click-to-call widget needs no sign-in at all.

The Browser SDK is a participant in the call, not its controller. When a browser user calls your agent, the flow they hear still comes from SWML, and your backend still steers it with REST commands.

JavaScript — Browser SDK
import { SignalWire, StaticCredentialProvider } from "@signalwire/js";
const client = new SignalWire(
new StaticCredentialProvider({ token: "<SUBSCRIBER_TOKEN_FROM_YOUR_BACKEND>" })
);
client.ready$.subscribe(async (ready) => {
if (!ready) return;
const call = await client.dial("/public/bayview-dispatch", { audio: true });
call.status$.subscribe((status) => console.log("status:", status));
});

Relay

The Relay namespace of the Server SDKs holds a persistent WebSocket connection to SignalWire. Your process subscribes to contexts, receives each inbound call as it arrives, and drives it with procedural code: answer, play, collect digits, bridge. Your code receives every call event as it happens and reacts to it directly, without the webhook layer.

Call Flow Builder lets you draw a dialplan, one node per step, and saves it as a Call Flow Resource that you point a phone number at, with no code at all. An AI Agent Resource in the Dashboard is different: it points at the public URL of an agent you build with the Server SDKs and host yourself, as described in Create and manage Resources.

Text conversations with an AI agent

The agent that answers your phone can also hold a text conversation through the AI Chat API. Each turn is one HTTP request: you send the user’s message, and the agent’s reply comes back in the response. The conversation uses the agent’s prompt, state, and SWAIG tools, as a call does, and SWAIG requests from a chat conversation carry conversation_type: chat.

From your server, the Server SDKs send each turn. A web page reaches the agent through a gateway in your web application, which keeps the API token on your server. To answer SMS with the agent, your inbound message webhook passes each text to AI chat and replies with Messaging SWML.

import asyncio
from signalwire.ai_chat import AIChatClient
CONFIG_URL = "https://<YOUR_SPACE>.signalwire.com/relay-bins/<YOUR_AGENT_ID>"
async def main():
async with AIChatClient(
project="<YOUR_PROJECT_ID>", token="<YOUR_API_TOKEN>", space="<YOUR_SPACE>"
) as client:
info = await client.create_conversation("rider-1", config_url=CONFIG_URL)
print("Ada:", info.initial_message)
reply = await client.chat("rider-1", "I need a ride to the airport.")
print("Ada:", reply.text)
await client.end("rider-1")
asyncio.run(main())

CONFIG_URL is the request URL of a SWML Script that holds your agent, and the API token needs the Chat permission.

Messaging and fax

Messaging and fax use the same products as calls.

To send an SMS or MMS, call the REST APIs’ Create message endpoint, which the REST namespace of the Server SDKs wraps in a method. A Relay process can send one over its WebSocket. During a call, the SWML send_sms method or the send_sms tool action texts the caller.

To handle inbound texts, point a phone number at a Messaging SWML document, or receive them in a Relay process. Messaging SWML is a separate flavor of SWML with methods such as reply. You can host the document in SignalWire or serve it from your own server, as in Reply to incoming messages via SWML.

Fax runs on a call. To send one, place a call with the REST dial command and have its SWML run send_fax. To receive faxes, point a phone number at SWML that runs receive_fax. The Agents namespace generates both methods, and Relay can send and receive faxes on a call. Send and receive faxes walks through both directions.

Match your use case to a product

You’re buildingUse
An AI agent that answers your phone numberServer SDKs (Agents namespace)
A phone menu or call forwardingServer SDKs (Agents namespace)
An agent that answers from your documentsServer SDKs (Agents namespace) with the datasphere skill
Outbound reminder or survey callsREST dial, running your Server SDKs (Agents namespace) flow
Buttons that record, transfer, or hold a live callREST call commands
Text notifications and confirmationsREST messages
Two-way texting or automatic repliesMessaging SWML or Relay
An AI agent customers chat with on your website or over SMSAI Chat API, from the Server SDKs or a web gateway
Sending or receiving faxesServer SDKs (Agents namespace) with send_fax and receive_fax
A “call us” button on a web pageClick-to-call widget
Voice or video calling between your usersBrowser SDK
An existing Twilio applicationCompatibility API

The building blocks every product shares

Building blockWhat it isWhere you work with it
Phone numbersNumbers on your Space that receive and place calls and messagesBuy and assign them in the Dashboard or with REST. Each one points at a Resource.
Resources and AddressesAnything that handles a call, such as a SWML Script, AI Agent, Subscriber, Video Room, or Call Flow, and the paths that reach it, such as /public/bayview-dispatchCreate them in the Dashboard or with REST. SWML, the Browser SDK, and Relay all dial Addresses.
Subscribers and tokensThe people who sign in to your app, and the short-lived tokens their browsers useCreate Subscribers and tokens with REST, then use them in the Browser SDK
SWAIG toolsFunctions on your server that an AI agent calls mid-conversationDeclare them on the agent. Their replies can carry actions on the call. See Tool calling.
DatasphereDocument storage with semantic search, for agents that answer from your contentUpload documents with REST, then give the agent the datasphere skill
Webhooks and status callbacksHTTP requests SignalWire sends your server when a call or message changes stateSet a status_url on REST commands, or a callback on a SWML method
RecordingsAudio files from recorded callsStart them from SWML, Relay, or a REST call command, then list, fetch, and delete them with REST

Steer a running agent from your backend

The products work together on a single call. Every SWAIG request your agent receives carries the call’s call_id, so your server can store it with the booking. When a driver accepts the ride, your dispatch system sends calling.ai_message to that call through the REST APIs. Ada receives it as a system instruction the caller doesn’t hear, and tells the caller their driver is on the way. The REST client guide shows how to send call commands from the Server SDKs.

Next steps