Introduction to SWML

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:

1
version: 1.0.0
2
sections:
3
  main:
4
    - method1: {}
5
    - method2:
6
        parameter: value

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.

Document-fetching webhook

When a SWML script is hosted on an external URL (set in phone number settings, or invoked via execute or transfer), SignalWire sends a POST request to that URL to fetch the SWML document. The request body contains the current call state and any variables or parameters set by the calling script.

Several SWML methods also use this same request format when fetching SWML from a URL (e.g., join_conference.wait_url, enter_queue.wait_url, connect.confirm).

Request body

Raw JSON example

1
{
2
  "call": {
3
    "call_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
4
    "node_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
5
    "segment_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
6
    "call_state": "created",
7
    "direction": "inbound",
8
    "type": "phone",
9
    "from": "+15551231234",
10
    "to": "+15553214321",
11
    "headers": [],
12
    "project_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
13
    "space_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
14
  },
15
  "vars": {},
16
  "params": {},
17
  "envs": {}
18
}

Expected response

Your server must respond with a valid SWML document using one of these content types: application/json, application/yaml, or text/x-yaml.

For the full variable reference and a detailed JSON example, see Variables. For server setup instructions, see the Deployment guide.

Basic SWML examples

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

1
version: 1.0.0
2
sections:
3
  main:
4
    - play:
5
        url: "say:Hello from Signal Wire! Have a great day!"
6
    - hangup

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.

1
version: 1.0.0
2
sections:
3
  main:
4
    - answer: {}
5
    - play:
6
        url: "say:Welcome to Acme Corporation. This call may be recorded."
7
    - record_call:
8
        stereo: true
9
        format: wav
10
    - prompt:
11
        play: "say:Press 1 for sales, Press 2 for support"
12
        max_digits: 1
13
        speech_hints:
14
          - one
15
          - two
16
    - switch:
17
        variable: prompt_value
18
        case:
19
          '1':
20
            - execute:
21
                dest: sales
22
          '2':
23
            - execute:
24
                dest: support
25
          one:
26
            - execute:
27
                dest: sales
28
          two:
29
            - execute:
30
                dest: support
31
        default:
32
          - execute:
33
              dest: sales
34
  sales:
35
    - play:
36
        url: "say:You have reached sales"
37
    - connect:
38
        to: "+15551234567"
39
  support:
40
    - play:
41
        url: "say:You have reached support"
42
    - connect:
43
        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