SWML (SignalWire Markup Language) 🔗 ↑ TOC

Introduction 🔗 ↑ TOC

SignalWire Markup Language (SWML) is a declarative markup language designed to orchestrate telecom channels, complex call flows, and teams of conversational agents using YAML or JSON documents.

SWML (pronounced "swimmel" or sometimes called S-W-M-L) is essentially a domain-specific programming language for telephony and conversational AI that maps agent development to familiar web app development paradigms.

Core Concepts 🔗 ↑ TOC

What SWML Enables 🔗 ↑ TOC

SWML as the DNA of Programmable Communication 🔗 ↑ TOC

SWML is tightly integrated with SignalWire's infrastructure and serves as the foundational layer that: - Exposes FreeSWITCH features in a simplified way - Adds multiple contexts and menus in a complete document - Enables async behaviors (start/stop recording mid-call, SMS integration during phone calls) - Provides a framework for quickly adding powerful verbs and applications

Basic Structure 🔗 ↑ TOC

Document Format 🔗 ↑ TOC

SWML documents are written in YAML or JSON. Every script must include:

version: 1.0.0
sections:
  main:
    # Your script logic here

Key Components 🔗 ↑ TOC

Version 🔗 ↑ TOC

Sections 🔗 ↑ TOC

Variable Substitution 🔗 ↑ TOC

Key Features 🔗 ↑ TOC

1. Conversation Structuring and Routing 🔗 ↑ TOC

2. User Interaction and Data Collection 🔗 ↑ TOC

3. Theming & Personalization 🔗 ↑ TOC

4. Reusable Logic and Components 🔗 ↑ TOC

5. Security, Deployment, and Observability 🔗 ↑ TOC

SWML and Call Fabric Integration 🔗 ↑ TOC

Resource Addresses 🔗 ↑ TOC

SWML works with Call Fabric's resource model using standardized addresses:

space_name.signalwire.com/context/address

Components: - Context: Identifier indicating resource location - Name: Unique identifier for the resource

Example: /public/Alice for a Subscribers resource named "Alice" in the public context

Resource Types 🔗 ↑ TOC

Serving SWML 🔗 ↑ TOC

From the Dashboard 🔗 ↑ TOC

  1. Navigate to "Relay/SWML" section
  2. Switch to "SWML Scripts" tab
  3. Create and save new scripts
  4. Configure phone numbers to use saved scripts

From External Web Server 🔗 ↑ TOC

  1. Enable "Use External URL for SWML Script handler"
  2. Set web URL to serve SWML scripts
  3. Receive HTTP POST requests with call parameters
  4. Return dynamically generated SWML responses

HTTP Request Parameters 🔗 ↑ TOC

When serving from external URL, receive:

Parameter Type Description
call Call object Properties describing the call
vars Object Variables set in calling SWML
params Object Parameters from execute/transfer methods

Call Object Properties 🔗 ↑ TOC

Basic Example 🔗 ↑ TOC

version: 1.0.0
sections:
  main:
    - answer: {}
    - execute:
        dest: play_music
        params:
          to_play: 'https://cdn.signalwire.com/swml/April_Kisses.mp3'
  play_music:
    - play:
        url: '%{params.to_play}'

This script: 1. Answers the incoming call 2. Executes the play_music section with parameters 3. Plays the specified audio file 4. Uses variable substitution to access the parameter

AI Integration in SWML 🔗 ↑ TOC

Basic AI Agent 🔗 ↑ TOC

version: 1.0.0
sections:
  main:
    - ai:
        post_prompt_url: https://example.com/my-api
        prompt:
          text: |
            You are Franklin's assistant collecting messages.
            Collect the user's name and number if not known from caller ID.
            After collecting the message, say goodbye and hang up.
        post_prompt:
          text: |
            Summarize as JSON: { "contact_info": { "name": "NAME", "number": "PHONE" }, "message": "MESSAGE" }

Advanced AI Features 🔗 ↑ TOC

Method Categories 🔗 ↑ TOC

Core Methods 🔗 ↑ TOC

AI Methods 🔗 ↑ TOC

Control Flow 🔗 ↑ TOC

Best Practices 🔗 ↑ TOC

Script Organization 🔗 ↑ TOC

Performance Optimization 🔗 ↑ TOC

Security Considerations 🔗 ↑ TOC

Testing and Debugging 🔗 ↑ TOC

Integration Capabilities 🔗 ↑ TOC

External APIs 🔗 ↑ TOC

Communication Channels 🔗 ↑ TOC

Development Tools 🔗 ↑ TOC