Skip to main content

SWML

Build powerful communication applications with the SignalWire Markup Language

SWML is a markup and scripting language for quickly writing powerful communication applications in YAML or JSON documents. SWML is easy to use, and enables you to create powerful voice and messaging applications using a descriptive format.

SWML scripts can be deployed serverlessly via the SignalWire Dashboard, via your own server, or using the Agents SDK. For a comprehensive breakdown, see our SWML deployment guide.

  • Server or serverless: Serve SWML from your own server or via the SignalWire platform
  • Powerful: Handle voice calls, messaging, AI agents, and more
  • Simple: Declarative, composable format that's easy to learn, maintain, and scale
  • Extensible: Integrate native AI, functions, and external APIs

Whether you're building simple call forwarding systems or complex AI-powered customer service agents, SWML provides the tools you need to deploy sophisticated communication workflows.

Core concepts​

Document structure​

Every SWML script follows this basic structure in either YAML or JSON format:

version: 1.0.0
sections:
  main:
    - method1: {}
    - method2:
        parameter: value
PropertiesDescription
versionAlways use 1.0.0 (the only supported version)
sectionsContains all script sections
mainRequired starting section where execution begins

Sections​

Sections are named blocks of code that organize your script. Each section is an array of methods to execute.

All SWML scripts start with the main section, but you can create additional sections for different tasks (like sales, support, menu). Use the following methods to move between sections:

  • execute: Calls a section like a function and returns to the current section
  • transfer: Transfers control permanently to another section

Methods​

Methods are the commands that tell SWML what to do during a call - like answering, playing audio, collecting input, or instantiating an AI Agent. Think of them as the instructions in your script.

Basic SWML examples​

Here are some basic SWML examples utilizing these core concepts for Text to Speech and Call Forwarding:

Create a simple text-to-speech greeting:

version: 1.0.0
sections:
  main:
    - play:
        url: "say:Hello from Signal Wire! Have a great day!"
    - hangup

This script will answer the incoming call, play a greeting message using text-to-speech, and then hang up.

Basic IVR​

An Interactive Voice Response (IVR) system routes callers to different departments based on their input. This example demonstrates a complete IVR that answers the call, plays a welcome message, records the conversation, collects user input (via keypress or speech), and routes callers to sales or support.

This pattern is one of the most common use cases for SWML and demonstrates how multiple methods work together to create a professional phone system. For an extensive breakdown of this example, see our IVR Creation Guide.

version: 1.0.0
sections:
  main:
    - answer: {}
    - play:
        url: "say:Welcome to Acme Corporation. This call may be recorded."
    - record_call:
        stereo: true
        format: wav
    - prompt:
        play: "say:Press 1 for sales, Press 2 for support"
        max_digits: 1
        speech_hints:
          - one
          - two
    - switch:
        variable: prompt_value
        case:
          '1':
            - execute:
                dest: sales
          '2':
            - execute:
                dest: support
          one:
            - execute:
                dest: sales
          two:
            - execute:
                dest: support
        default:
          - execute:
              dest: sales
  sales:
    - play:
        url: "say:You have reached sales"
    - connect:
        to: "+15551234567"
  support:
    - play:
        url: "say:You have reached support"
    - connect:
        to: "+15551234568"

Variable substitution: Notice how prompt_value in the switch statement automatically contains the user's input from the prompt. SWML supports dynamic values using the %{variable_name} format. For example, you can reference call information with %{call.from} or parameters with %{params.audio_file}.

Next steps​

Quickstart

Quickly create and deploy SWML through the SignalWire Dashboard

Methods reference

Explore all available SWML methods

AI guides

Learn how AI methods are used in SWML