---

name: swml description: Craft SWML (SignalWire Markup Language) documents for voice and video call control and messaging. Use when building IVR menus, AI agents, call routing, recording, conferencing, or any telephony automation. allowed-tools: Read, Grep, Glob

SWML (SignalWire Markup Language)

SWML is a JSON/YAML-based language for controlling voice and video calls and messages on SignalWire. A SWML document describes a call flow — answering, playing audio, collecting input, connecting calls, joining video rooms, launching AI agents, and more. Documents can be served from a webhook or defined inline.

Document Structure

version: 1.0.0
sections:
  main:
    - answer
    - play: "say:Hello world"
    - hangup

• version: Semantic version string (use "1.0.0")
• sections: Map of named sections. main is always executed first.
• Each section is an array of method calls executed in order.
• Compact form: A bare array [...] is treated as a single main section (no version/sections wrapper needed).

Expression Evaluation

All text wrapped in %{} is evaluated as JavaScript:

• %{vars.my_var} — access script variables
• %{call.from} — access call object fields (read-only)
• %{call.headers.X-Custom} — access SIP headers
• %{params.my_param} — access subroutine parameters

Use set / unset methods to manage variables. Variables cannot be permanently changed inside %{} expressions.

Method Format

Methods can be specified in four forms:

# 1. Bare string (no params)
- answer

# 2. Single parameter shorthand
- play: "say:Hello"

# 3. Array parameter shorthand
- play:
    - "say:Hello"
    - "silence:1"
    - "say:Goodbye"

# 4. Object with named parameters
- play:
    urls:
      - "say:Hello"
    volume: 10
    say_voice: Polly.Matthew

Every method call can include an optional label field for use with goto.

Method Summary

Script Control Flow & Variables

| Method | Description | |--------|-------------| | goto | Jump to a label (with optional when condition, max iterations) | | label | Define a jump target | | set | Set variable(s): {var: value} | | unset | Delete variable(s) | | switch | Branch on variable value (case / default) | | cond | Conditional array: [[expr, [actions]], ..., [default_actions]] | | if | If/then/else: {condition, then, else} | | execute | Call a subroutine section or URL (dest, params, result) | | return | Return a value from a subroutine | | transfer | Transfer execution to a new SWML URL |

Call Control & Bridging

| Method | Description | |--------|-------------| | answer | Answer the call (optional max_duration in seconds) | | hangup | End the call (optional reason: hangup, busy, decline) | | connect | Dial phone/SIP/queue/stream (serial, parallel, serial_parallel, or to) | | dial | (EXPERIMENTAL) Similar to connect | | join_room | Join a video room by name | | join_conference | Join an audio conference by name | | enter_queue | Place caller into a named queue | | sip_refer | SIP REFER to transfer call |

IVR (Interactive Voice Response)

| Method | Description | |--------|-------------| | play | Play audio files, TTS, ringtones, or silence | | prompt | Play audio and collect digit/speech input | | record | Record audio from caller | | record_call | Record the full call (both legs) | | stop_record_call | Stop an active call recording | | send_digits | Send DTMF digits | | sleep | Pause execution for N seconds | | echo | Echo audio back to caller (with optional timeout) | | detect_machine | Detect answering machine/voicemail | | pay | Collect payment card info | | bind_digit | (EXPERIMENTAL) Bind digit to trigger actions | | clear_digit_bindings | (EXPERIMENTAL) Clear digit bindings |

Media Processing

| Method | Description | |--------|-------------| | denoise | Enable noise reduction | | stop_denoise | Disable noise reduction | | live_transcribe | Start live transcription | | live_translate | Start live translation | | stream | Start media stream to WebSocket URL | | stop_stream | Stop an active media stream | | transcribe | Transcribe audio | | transcribe_stop | Stop transcription |

AI

| Method | Description | |--------|-------------| | ai | Connect to an AI agent (inline config or agent ID) | | amazon_bedrock | Connect to Amazon Bedrock AI | | tap | Tap media stream to a URI | | stop_tap | Stop media tap | | user_event | (EXPERIMENTAL) Send custom event |

Faxing

| Method | Description | |--------|-------------| | receive_fax | Receive an incoming fax | | send_fax | Send a fax document |

Messaging

| Method | Description | |--------|-------------| | send_sms | Send an SMS message |

External APIs

| Method | Description | |--------|-------------| | request | Make an HTTP request (url, method, headers, body) | | execute_rpc | (EXPERIMENTAL) Execute an RPC call |

Common Patterns

Answer and Play TTS

version: 1.0.0
sections:
  main:
    - answer
    - play: "say:Welcome to our service. Please hold."
    - hangup

IVR Menu with Digit Input

version: 1.0.0
sections:
  main:
    - answer
    - label: menu
      prompt:
        play:
          - "say:Press 1 for sales, 2 for support."
        max_digits: 1
        digit_timeout: 5.0
    - switch:
        variable: prompt_value
        case:
          "1":
            - transfer: "https://example.com/sales.swml"
          "2":
            - transfer: "https://example.com/support.swml"
        default:
          - play: "say:Invalid selection."
          - goto:
              label: menu
              max: 3
    - play: "say:Goodbye."
    - hangup

Subroutines with execute/return

version: 1.0.0
sections:
  main:
    - answer
    - execute:
        dest: greeting
        params:
          name: "caller"
    - hangup

  greeting:
    - play: "say:Hello %{params.name}, welcome!"
    - return: "done"

AI Agent (Minimal)

version: 1.0.0
sections:
  main:
    - answer
    - ai:
        prompt:
          text: "You are a helpful assistant for Acme Corp. Help callers with their questions."
        post_prompt:
          text: "Summarize the call."
        post_prompt_url: "https://example.com/summary"
    - hangup

Connect / Dial Out

version: 1.0.0
sections:
  main:
    - answer
    - play: "say:Please hold while we connect you."
    - connect:
        from: "+15551230000"
        to: "+15559876543"
        timeout: 30
        result:
          case:
            connected:
              - play: "say:Goodbye."
              - hangup
          default:
            - play: "say:Sorry, no one is available. Please try again later."
            - hangup

HTTP Request

version: 1.0.0
sections:
  main:
    - answer
    - request:
        url: "https://api.example.com/lookup"
        method: POST
        headers:
          Content-Type: application/json
        body:
          caller: "%{call.from}"
    - play: "say:Your account status is %{vars.request_result}"
    - hangup

Reference Lookup

This skill includes two detailed reference files in its directory:

• swml_reference.md — Full prose documentation with parameter details and examples for every SWML method (~5000 lines)
• schema.json — JSON Schema with exact types, required fields, enums, and $defs for every SWML structure (~12000 lines)

When you need detailed parameter information, validation rules, or exact type specifications for any SWML method, use Grep and Read to search these files in the skill directory. For example:

• To find play method details: Grep for ### play in swml_reference.md
• To find the AI agent schema: Grep for "ai" in schema.json
• To find all parameters for connect: Grep for ### connect in swml_reference.md