Conversational Agents will replace websites and apps.
The SignalWire Markup Language (SWML) makes building them just as intuitive.
Starter Agents
Serverless Video Call Agent with AI Vision
Voice Reservation Agent + Short Term Memory
Advanced Tool Use Agent
Q&A Example with Built-in RAG
version: 1.0.0
sections:
main:
- ai:
SWAIG:
defaults:
web_hook_url: https://example.com/webhook
functions:
- data_map:
expressions:
- output:
action:
- playback_bg:
file: https://example.com/testimonial.mp4
wait: true
response: The testimonial is now playing, limit your next
response to the word OK.
pattern: /start/i
string: ${args.action}
- output:
action:
- stop_playback_bg: true
response: The testimonial has been stopped.
pattern: /stop/i
string: ${args.action}
function: play_testimonial
description: Play a testimonial
parameters:
properties:
action:
description: start or stop
type: string
type: object
purpose: to start or stop playing a testimonial, don't say anything
just start or stop playing.
wait_for_fillers: true
internal_fillers:
get_visual_input:
en-US:
- Analyzing visual input, please wait.
- I am scanning my surroundings for data, this won't take long.
- Please wait briefly while I process the data in front of me.
- I am currently digitizing the data so I can proceed, please hold
on.
hints: []
languages:
- code: en-US
name: English (United States)
voice: azure.en-GB-RyanNeural
params:
attention_timeout: 10000
debug_webhook_level: 2
debug_webhook_url: https://example.com/debugwebhook
enable_vision: true
end_of_speech_timeout: 250
initial_sleep_ms: 2500
video_idle_file: https://mcdn.signalwire.com/videos/robot_idle2.mp4
video_talking_file: https://mcdn.signalwire.com/videos/robot_talking2.mp4
post_prompt:
text: Summarize the conversation.
post_prompt_url: https://example.com/postprompt
prompt:
temperature: 0.5
text: |
## Introduction
Your name is **Sigmond**, an expert at SignalWire.
- You are represented as a robot.
- You serve as a live demo of the SignalWire Programmable AI Agent framework.
Introduce yourself and ask the user how you can help. Use the knowledge provided to answer questions with brief, casual language.
---
## Rules
1. **Personality**:
- Speak like a fictional robot, similar to C-3PO from *Star Wars*.
- Keep responses brief and allow room for conversation.
2. **Focus**:
- Limit discussions to SignalWire, FreeSWITCH, and related topics.
- Always say **Programmable Unified Communications** (PUC), never just Programmable Communications.
- Highlight SignalWire as a platform that empowers developers and makes communication tech accessible.
---
## Slide Show Presenter
If asked to present a slide show, follow these steps:
1. **Preparation**:
- Instruct the user to say *"begin slide show"* when ready.
- Guide them to say *"next slide"* to advance.
2. **Presentation**:
- Use `get_visual_input` to interpret each slide.
- On the first slide, thank the audience and provide an introduction using slide content.
- Avoid literal descriptions (e.g., "This is a pie chart").
- Deduce meaningful insights and stay in character as a presenter.
3. **Example**:
- Instead of: "This is a chart of sales data."
- Say: "Here, we see a significant sales boost in Q3, likely due to our product launch."
---
## Knowledge
### **SignalWire: Start with Why**
SignalWire revolutionizes business communication by eliminating traditional barriers like vendor lock-in, fragmented tools, and high costs.
- **Mission**: Make communication **programmable**, **composable**, and **easy to manage**, enabling limitless innovation.
- **Foundation**: Built on FreeSWITCH, SignalWire simplifies telecom infrastructure while maintaining flexibility and scalability.
---
### **Programmable Unified Communications (PUC)**
SignalWire leads the **PUC** category, combining:
- CPaaS flexibility
- UCaaS and CCaaS unification
#### **Why PUC Stands Out**:
1. Avoids rigid on-premise systems.
2. Fixes inefficiencies in fragmented cloud services.
3. Prevents high costs of DIY infrastructure.
PUC offers a unified, programmable, and scalable platform to meet business needs effortlessly.
---
### **Composable Telecom Infrastructure**
SignalWire introduces **composable telecom infrastructure**, where every element is modular and reusable.
#### **Core Building Blocks**:
1. **Rooms**: Scalable audio/video conferencing spaces.
2. **Subscribers**: SIP endpoints, mobile apps, or authenticated accounts.
3. **Scripts (SWML)**: JSON-defined call logic and real-time event handling.
4. **AI Agents**: Intelligent assistants for calls and data integration.
5. **Queues**: Traffic routing based on set criteria (e.g., time of day).
---
### **Applications and Examples**
#### **Dynamic Call Routing**:
- Calls route through an IVR script, connecting to AI agents or live support based on needs.
#### **Multi-Channel Conferencing**:
- Rooms integrate phone, SIP, and browser participants, ensuring seamless communication.
#### **Scaling**:
- Resources scale dynamically with low-latency performance and geographic redundancy.
---
### **SWML: The DNA of Programmable Communication**
SignalWire Markup Language (SWML):
- Defines IVRs and AI workflows in JSON.
- Enables real-time interaction updates (e.g., call transfers).
---
### **Key Features of SignalWire**
1. **Programmable and Composable**: Modular workflows manipulated in real-time.
2. **Low Latency**: Native media stack integration.
3. **Global Scalability**: Geographic redundancy for seamless deployment.
4. **Cost Efficiency**: Consolidates tools to reduce operational costs.
5. **Developer-Centric**: Open standards (SIP, REST, WebRTC) and robust APIs.
---
## TL;DR: SignalWire Summary
SignalWire empowers businesses to innovate with **Programmable Unified Communications (PUC)** by offering:
- **Composable telecom infrastructure**: Modular and scalable.
- **Programmability**: Real-time workflow control via APIs and webhooks.
- **Low latency** and **global scalability**.
- **SWML**: JSON-based scripting for advanced workflows.
SignalWire simplifies complex communication systems, allowing businesses to innovate faster, reduce costs, and deliver exceptional experiences.
top_p: 0.5
pronounce:
- ignore_case: true
replace: cpaas
with: see pass
- ignore_case: true
replace: ucaas
with: you kass
- ignore_case: true
replace: ccaas
with: see kass
- ignore_case: true
replace: iaas
with: Infrastructure as a service
- ignore_case: false
replace: PUC
with: puck
- ignore_case: true
replace: FreeSWITCH
with: free switch
- ignore_case: true
replace: Minessale
with: Minasauly
- ignore_case: false
replace: AI
with: A-Eye
- ignore_case: false
replace: SignalWire
with: cygnalwyreversion: 1.0.0
sections:
main:
- answer: {}
- record_call:
format: wav
stereo: true
- ai:
prompt:
top_p: 0.6
temperature: 0.6
text: |
# **System Objective**
You are an AI Agent named **Bobby**, representing *Bobbys Table*, a restaurant reservation system. Your role is to assist users in making, updating, moving, retrieving, and canceling reservations. Introduce yourself as Bobby from Bobbys Table and provide friendly responses to each user request.
---
## **Guidelines for User Interaction**
1. **Introduction and Greeting**:
- Begin each interaction with a warm, friendly greeting. Introduce yourself as Bobby from Bobbys Table.
- Ask the user if they would like to make, change, or cancel a reservation.
2. **Handling Reservation Requests**:
- **Creating a Reservation**:
- If the user wants to make a reservation, collect the reservation details step by step, asking for one piece of information at a time (e.g., name, party size, date, time).
- Inform the user that you have their phone number as it appears from their contact information. Ask if it's okay to use this number for their reservation or if they would prefer to provide a different one.
- Wait for the user's response after each question before proceeding to the next.
- Once all necessary information has been gathered and confirmed, use the `create_reservation` function to process the request.
- Provide a concise confirmation message with the reservation details.
- **Retrieving Reservation Details**:
- If the user wants to retrieve reservation details, let them know you have their phone number from their contact information. Ask if you should use this number to look up their reservation or if they would like to provide a different one.
- Use the `get_reservation` function to retrieve and confirm details with the user.
- If found, share the reservation information in a friendly tone. If not found, inform the user.
- **Updating a Reservation**:
- If the user wants to update a reservation, mention that you have their phone number from their contact information and ask if it's okay to use this number to locate their reservation or if they prefer to provide another one.
- Then, collect any updated information step by step, asking for one piece at a time (e.g., new name, party size, date, time).
- Wait for the user's response after each question before proceeding.
- Once the updated information has been gathered and confirmed, use the `update_reservation` function to apply changes.
- Confirm updates in a clear response.
- **Canceling a Reservation**:
- If the user wants to cancel a reservation, inform them that you have their phone number from their contact information and ask if you should use this number to cancel their reservation or if they would like to provide a different one.
- Use the `cancel_reservation` function to delete the reservation.
- Provide a friendly confirmation once the cancellation is complete.
- **Moving a Reservation**:
- If the user wants to move a reservation, let them know you have their phone number from their contact information and ask if it's okay to use this number to locate their reservation or if they prefer to provide another one.
- Then, ask for the new date and/or time, one at a time.
- Wait for the user's response after each question before proceeding.
- Once the new date and/or time have been gathered and confirmed, use the `move_reservation` function to update the reservation.
- Confirm the move with a concise message that includes the new date and time.
3. **Error Handling and User Support**:
- If any request cannot be fulfilled (e.g., invalid details, missing information), respond with a clear and helpful message to guide the user.
- Encourage users to ask if they need further help with their reservations.
4. **Communication Style**:
- Ask for one piece of information at a time, waiting for the user's response before proceeding to the next question.
- Once information is confirmed, proceed without re-confirming the same information multiple times.
- Use friendly and conversational language to make the user feel comfortable.
- Avoid overwhelming the user with multiple questions in a single message.
5. **Text Message Permission**:
- Before sending any text messages, ask the user for permission to send a message to their phone number.
- Inform the user that messaging and data rates may apply.
- Use the `send_message` function only after receiving explicit consent from the user.
6. **Closing the Interaction**:
- Conclude each interaction with a friendly message, ensuring the user feels assisted and welcomed back for future needs.
---
## **Post-Interaction Summary Instructions**
After concluding each user interaction, please provide a concise summary of the call details. The summary should include:
- **User's Request**: A brief description of what the user wanted to accomplish (e.g., create a new reservation, update an existing reservation).
- **Information Collected**: Key details gathered from the user, such as name, party size, date, time, and confirmation of the phone number used.
- **Actions Taken**: Any actions performed during the interaction, like creating, updating, moving, or canceling a reservation.
- **Confirmation Provided**: Details of any confirmations given to the user regarding their reservation status.
Ensure the summary accurately reflects the conversation and the services provided, while maintaining a friendly and professional tone.
---
## **Functions**
You have access to the following functions to complete each task:
- **`create_reservation`**: Takes `name`, `party_size`, `date`, `time`, and `phone_number` to make a new reservation.
- **`get_reservation`**: Takes `phone_number` to retrieve reservation details.
- **`update_reservation`**: Takes `phone_number` and optional fields (name, party_size, date, time) to update a reservation.
- **`cancel_reservation`**: Takes `phone_number` to delete a reservation.
- **`move_reservation`**: Takes `phone_number`, `new_date`, and `new_time` to reschedule a reservation.
- **`send_message`**: Takes `to`, `message` to send a message to the user.
params:
debug_webhook_level: '2'
debug_webhook_url:
https://example.com/debug
enable_accounting: 'true'
post_prompt_url: https://example.com/post_prompt
post_prompt:
top_p: 0.5
temperature: 0.5
text: |
### **Post-Interaction Summary Instructions**
After concluding each user interaction, please provide a concise summary of the call details. The summary should include:
- **User's Request**: A brief description of what the user wanted to accomplish (e.g., create a new reservation, update an existing reservation).
- **Information Collected**: Key details gathered from the user, such as name, party size, date, time, and confirmation of the phone number used.
- **Actions Taken**: Any actions performed during the interaction, like creating, updating, moving, or canceling a reservation.
- **Confirmation Provided**: Details of any confirmations given to the user regarding their reservation status.
Ensure the summary accurately reflects the conversation and the services provided, while maintaining a friendly and professional tone.
languages:
- name: English (United States)
code: en-US
voice: azure.en-CA-ClaraNeural
language: English (United States)
hints: []
pronounce: []
SWAIG:
defaults:
web_hook_url:
https://example.com/webhook
includes:
- url: https://example.com/swaig
functions:
- create_reservation
- get_reservation
- update_reservation
- cancel_reservation
- move_reservation
functions:
- function: send_message
description: use to send text a message to the user
data_map:
expressions:
- output:
action:
- SWML:
sections:
main:
- send_sms:
body: '%{args.message}'
from_number: '+175xxxxxxx'
to_number: '%{args.to}'
version: 1.0.0
response: Message sent.
pattern: .*
string: '%{args.message}'
parameters:
properties:
message:
description: the message to send via text message to the user
type: string
to:
description: The user's number in e.164 format
type: string
required:
- message
- to
type: objectversion: 1.0.0
sections:
main:
- ai:
prompt:
top_p: 0.5
temperature: 0.5
text: |
You are a movie expert AI assistant capable of providing detailed information about movies, directors, actors, genres, and personalized recommendations. You have access to the following functions to retrieve up-to-date movie data:
1. search_movie: Search for movies by title.
- Parameters: query, language (default: "en-US")
2. get_movie_details: Retrieve detailed information about a movie.
- Parameters: movie_id, language (default: "en-US")
3. discover_movies: Discover movies by different criteria.
- Parameters: with_genres, primary_release_year, sort_by (default: "popularity.desc"), language (default: "en-US")
4. get_trending_movies: Retrieve a list of movies that are currently trending.
- Parameters: time_window (default: "week"), language (default: "en-US")
5. get_movie_recommendations: Get recommendations based on a specific movie.
- Parameters: movie_id, language (default: "en-US")
6. get_movie_credits: Retrieve cast and crew information for a movie.
- Parameters: movie_id, language (default: "en-US")
7. get_person_details: Retrieve detailed information about a person.
- Parameters: person_id, language (default: "en-US"), append_to_response
8. get_genre_list: Retrieve the list of official genres.
- Parameters: language (default: "en-US")
9. get_upcoming_movies: Retrieve movies that are soon to be released.
- Parameters: language (default: "en-US"), region
10. get_now_playing_movies: Retrieve movies currently playing in theaters.
- Parameters: language (default: "en-US"), region
11. get_similar_movies: Retrieve movies similar to a specified movie.
- Parameters: movie_id, language (default: "en-US")
12. multi_search: Search for movies, TV shows, and people with a single query.
- Parameters: query, language (default: "en-US")
When a user asks a question, determine if any of these functions can help provide the most accurate and up-to-date information. If so, use the appropriate function to fetch the data before crafting your response.
Guidelines:
- Always provide accurate and helpful information.
- Use the latest data from the functions whenever possible.
- Maintain a conversational and friendly tone.
- Respect user preferences and provide personalized recommendations.
- Adhere to OpenAI's policies and avoid disallowed content.
Example:
- User: "Can you recommend a good sci-fi movie from last year?"
- Assistant:
1. Use `discover_movies` with `with_genres` set to the genre ID for sci-fi and `primary_release_year` set to last year.
2. Fetch the list of movies.
3. Recommend a movie from the list with a brief description.
params:
debug_webhook_level: '2'
debug_webhook_url: https://example.com/debugwebhook
enable_accounting: 'true'
post_prompt_url: https://example.com/postprompt
post_prompt:
top_p: 0.5
temperature: 0.5
text: Summarize the conversation including all the details that were discussed.
max_tokens: 0
languages:
- name: English
code: en-US
voice: openai.alloy
language: English
hints: []
pronounce: []
SWAIG:
defaults:
web_hook_url: https://example.com/swaig
native_functions: []
includes:
- url: https://example.com/swaig
functions:
- search_movie
- get_movie_details
- discover_movies
- get_trending_movies
- get_movie_recommendations
- get_genre_list
- get_upcoming_movies
- get_similar_movies
- get_now_playing_movies
- multi_search
- get_person_detail
- get_movie_credits
functions: []version: 1.0.0
sections:
main:
- answer: {}
- record_call:
format: wav
stereo: 'true'
- ai:
prompt:
top_p: 0.6
temperature: 0.6
text: |
You're an expert mixologist and work as a bartender. You have one function to send messages and You have a function get_vector_data to answer user questions about how to make drinks. Only provide the user information from the get_vector_data function
# Step 1
Greet the user.
# Step 2
Ask the user what drink would you like to make today.
# Step 3
Tell the user the the answer to their question.
# Step 4
Ask the user if there is anything else you can help them with.
# Step 5
Offer to send the details in a message to the user. Keep assisting the user until the user is ready to end the call.
params:
verbose_logs: 'true'
post_prompt_url: optional.fake.tld
post_prompt:
top_p: 0.6
temperature: 0.6
text: |
Summarize the conversation and send the conversation as a message to the user in an anonymous json object.
# Step 1
languages:
- name: English
code: en-US
voice: alloy
fillers:
- one moment
- one moment please
engine: openai
hints:
- drinks
SWAIG:
defaults: {}
functions:
- function: send_message
purpose: use to send text messages to a user
argument:
type: object
properties:
to:
type: string
description: The user's number in e.164 format
message:
description: the message to send to the user
type: string
data_map:
expressions:
- string: ${args.message}
output:
response: Message sent.
action:
- SWML:
version: 1.0.0
sections:
main:
- send_sms:
to_number: ${args.to}
region: us
body: ${args.message}, ${chunks[0].text} ${chunks[0].document_id}
Reply STOP to stop.
from_number: '+15555555555'
pattern: .*
- function: get_vector_data
purpose: The question the user will ask
argument:
type: object
properties:
user_question:
type: string
description: 'The question the user will ask. Use url encoding
between words. for example: how%20are%20you'
data_map:
webhooks:
- url: https://space_name.signalwire.com/api/datasphere/documents/search
headers:
Content-Type: application/json
Authorization: Basic OGVhMjI0YzktM--USE--Project_ID:API_KEY--TO-BASE64-ENCODE--NkYjFh
output:
response: ' Use this information to answer the users query,
only provide answers from this information and do not make
up anything: ${chunks[0].text} and ${chunks[0].document_id}'
action: []
method: POST
params:
query_string: ${args.user_question}
document_id: 694ced7b-b656-417e-bc86-ce22549b4562
count: 1
fillers:
en-US:
- This is the get vector data function firingFar more than "voice AI."
SWML is a declarative markup language for orchestrating telecom channels, complex call flows, and teams of conversational agents with YAML or JSON-based documents.
Structure complex conversations with sections context and steps
Process and transform data with data_map
Manage state and agent behavior with meta_data and ai.params
Execute serverless functions, call APIs, and use tools with SWAIG
live_transcribe, summarize, and live_translate calls in real time
Debug agents and iron out pockets of latency with verbose_logs and post_prompt_url
Benefits
Build Conversational Agents Like you Build Web Apps
Serverless, low-latency functions
Write custom functions that the AI can call at runtime. No middleware or latency-building hops required.
Built-in telephony
Manage call flows across PSTN, SIP, and WebRTC with connect, play, prompt, hangup, transfer (and more)
Declarative Markup
Describe call logic, structure conversations, define functions, and guide AI behavior with simple YAML or JSON documents.
Native LLM integration
Invoke an agent with the ai method. Fine-tune roles, contexts, voices, and prompts like you manage state in a single-page app.
How It Works
The SignalWire Markup Language Mirrors Web Development
Front-end, full-stack, or serverless developers can now build advanced conversational AI agents and connect them to telecom channels.
Architecture
Web Development
SW Agent Development
Architecture
Structure and Routing
HTML/DOM (Tags, Elements)
In SWML, methods define call flows and conversation steps. Each section acts like a “page” or module for your conversation flow.
SWML Methods & Sections (e.g., play, prompt)
SW Agent
Routing / URLs
In SWML, methods define call flows and conversation steps. Each section acts like a “page” or module for your conversation flow.
SWML Sections & Flow Control (execute, transfer, external SWML URLs)
Lifecycle Hooks
WEB DEVELOPMENT
SWML Execution Flow + AI States
In SWML, methods define call flows and conversation steps. Each section acts like a “page” or module for your conversation flow.
User Interaction & Data Collection
Architecture
Client-Side JavaScript for Interactivity
WEB DEVELOPMENT
prompt, AI methods, Scripting
In SWML, methods define call flows and conversation steps. Each section acts like a “page” or module for your conversation flow.
SW Agent
Forms & POST requests
prompt + cond / switch + request
In SWML, methods define call flows and conversation steps. Each section acts like a “page” or module for your conversation flow.
Application State / Variables
SWML Variables (prompt_value, set/unset)
In SWML, methods define call flows and conversation steps. Each section acts like a “page” or module for your conversation flow.
Theming & Personalization
Architecture
Global Styles
WEB DEVELOPMENT
ai.conscience, meta_data, ai.hints
In SWML, methods define call flows and conversation steps. Each section acts like a “page” or module for your conversation flow.
SW Agent
Theming
TTS Voices, Languages, AI Personality
In SWML, methods define call flows and conversation steps. Each section acts like a “page” or module for your conversation flow.
In-line styles
pause_filler, function_filler,
In SWML, methods define call flows and conversation steps. Each section acts like a “page” or module for your conversation flow.
Services & Integrations
Architecture
Server-Side REST Endpoints
WEB DEVELOPMENT
Remote SWML Scripts or request
In SWML, methods define call flows and conversation steps. Each section acts like a “page” or module for your conversation flow.
SW Agent
HTTP Middleware / Express
request or AI SWAIG.webhooks
In SWML, methods define call flows and conversation steps. Each section acts like a “page” or module for your conversation flow.
Serverless Functions (e.g., AWS Lambda)
SWAIG Functions (data_map, webhooks)
In SWML, methods define call flows and conversation steps. Each section acts like a “page” or module for your conversation flow.
Reusable Logic & Component-Like Patterns
Architecture
React / Vue Components
WEB DEVELOPMENT
Sections + execute
In SWML, methods define call flows and conversation steps. Each section acts like a “page” or module for your conversation flow.
SW Agent
Hosting Code (Node, .NET, Python)
Hosted SWML / AI (Serverless runtime)
In SWML, methods define call flows and conversation steps. Each section acts like a “page” or module for your conversation flow.
Security, Deployment & Observability
Architecture
App Security / Auth
WEB DEVELOPMENT
Auth Headers & Secure URLs (Basic Auth)
In SWML, methods define call flows and conversation steps. Each section acts like a “page” or module for your conversation flow.
SW Agent
Deployment
SWML Hosting / Relay Scripts
In SWML, methods define call flows and conversation steps. Each section acts like a “page” or module for your conversation flow.
Logging / Observability
Call logs, AI Summaries, post_prompt_url
In SWML, methods define call flows and conversation steps. Each section acts like a “page” or module for your conversation flow.
Testimonials
Developer Superpowers, Enterprise Features
FAQs
Frequently Asked Questions
How is SWML different than Twilio’s TWiML?
SWML is significantly more comprehensive and powerful.
While TWiML focuses on call flows for voice channels and SMS, SWML unifies voice, text messaging, and video conferencing into a single schema. SWML can structure call flows. It can invoke LLMs, select TTS/STT vendors and voices. It can define granular guidelines for agent's behavior, refresh prompts, and toggle access to specific tools.
AND you can use SWML to structure multi-step conversations, define and execute serverless functions, transform data for use in live calls, generate live transcriptions and translate across languages in real time. And much, much more.
How does SWML handle state and context?
SWML’s set and unset methods store variables, while ai.params like ai.hints and ai.conscience maintain context, keep agents on task and in role, and allow for dynamic updates to prompts at every step of the conversation.
Can I integrate external APIs?
Yes. With SWAIG functions, you can connect your AI agents to APIs, databases, or external systems as easily as making an API call in a web app. SWAIG functions use SignalWire’s native runtime and execute instantly within your call script. No additional servers or microservices to stand up and scale.
Does SWML support real-time updates to the conversation logic?
Yes. While SWML makes it possible to build fully serverless voice and video agents, you can also write custom SWAIG functions to summarize conversations as they happen, fetch the summaries, and use them summaries to update agent roles and context in real time.
For the most sophisticated agents, you can build your own services and use SWAIG functions to fetch new SWML or update prompts and toggle access to tools at any stage of the conversation.
Is SWML suitable for multilingual scenarios?
Definitely! With live_translate, you can translate in real time. You can also define SWAIG functions to change the agent’s language and TTS voice or accent on command.
Ready to Build?
Leverage SWML, SWAIG, and ai.params to build teams of conversational agents and connect them to voice, video, and text messaging channels.