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 comes in two distinct document types — Calling for voice calls and Messaging for inbound SMS and MMS. Each type has its own method set, document modes, variable expansion rules, and webhook payload. See the per-type overview pages for the specifics.

SWML scripts can be deployed serverlessly via the SignalWire Dashboard, via your own server, or using the Agents SDK. For a comprehensive breakdown, see the 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.

SWML at a glance

A minimal working document for each flavor:

Calling SWML — answer the call, play a greeting, then hang up:

1
version: 1.0.0
2
sections:
3
  main:
4
    - answer: {}
5
    - play:
6
        url: "say:Hello, thanks for calling SignalWire."
7
    - hangup: {}

Messaging SWML — reply to an inbound SMS with a canned response:

1
version: 1.0.0
2
sections:
3
  main:
4
    - reply: "Thanks for your message! We'll get back to you soon."

Document structure

Both Calling and Messaging SWML documents share the same top-level shape: a sections map of named sections, where execution starts at sections.main and each section is an ordered array of methods. Additional sections handle reusable sub-flows that can be invoked from main via control-flow methods like execute, transfer, and goto. Only the set of available methods inside each section differs between Calling and Messaging — see the Calling overview and Messaging overview for the per-flavor method sets.

Core concepts

Methods

Methods are the commands that tell SWML what to do — answering a call, playing audio, or instantiating an AI agent on a Calling document; sending a reply or routing on a keyword in a Messaging document. Each type has its own method set; think of them as the instructions in your script.

Variables and substitution

SWML supports placeholder substitution in string values so methods can incorporate dynamic data like call state, inbound message body, or prior step results.

• Calling documents support both ${...} JavaScript expressions and path-based %{...} substitution.
• Messaging documents support %{...} only — pure path substitution with no JavaScript.

See the Variables reference for the full list of available paths in each context.

Document-fetching webhook

When SignalWire fetches a SWML script from an external URL, it sends a POST request whose payload shape depends on the document type:

• Calling — see Calling SWML → Document-fetching webhook.
• Messaging — see Messaging SWML → Document-fetching webhook.

Your server must respond with a valid SWML document using one of these content types: application/json, application/yaml, or text/x-yaml. For server setup instructions, see the Deployment guide.

Next steps