> For a complete index of all SignalWire documentation pages, fetch https://signalwire.com/docs/llms.txt

# Introduction to SWML

> Get started with SWML (SignalWire Markup Language), a markup and scripting language for quickly writing powerful communication applications in YAML or JSON documents.

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](/docs/swml/reference/calling) for voice
calls and [Messaging](/docs/swml/reference/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](/docs/server-sdks). For a comprehensive breakdown, see the
[SWML deployment guide](/docs/swml/guides/deployment).

* **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:

```yaml
version: 1.0.0
sections:
  main:
    - answer: {}
    - play:
        url: "say:Hello, thanks for calling SignalWire."
    - hangup: {}
```

```json
{
  "version": "1.0.0",
  "sections": {
    "main": [
      { "answer": {} },
      { "play": { "url": "say:Hello, thanks for calling SignalWire." } },
      { "hangup": {} }
    ]
  }
}
```

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

```yaml
version: 1.0.0
sections:
  main:
    - reply: "Thanks for your message! We'll get back to you soon."
```

```json
{
  "version": "1.0.0",
  "sections": {
    "main": [
      { "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](/docs/swml/reference/calling) and
[Messaging overview](/docs/swml/reference/messaging) for the per-flavor method sets.

The SWML schema version. Currently only `"1.0.0"` is accepted.

A map of named sections. Each value is an array of methods that run sequentially. Must
contain at least a `main` section.

The first section to run when SignalWire executes your script. An ordered list of
[method](#methods) objects — each object is one step, and SignalWire runs them in sequence.
Which methods you can use depends on whether you're writing a
[Calling](/docs/swml/reference/calling) or [Messaging](/docs/swml/reference/messaging)
script.

Optional named sections for reusable groups of steps. Call them from `main` (or any other
section) with `execute`, `transfer`, or `goto`. Same shape as `main` — an ordered list of
[method](#methods) objects, drawn from the same per-flavor method set.

## 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](/docs/swml/reference/calling); sending a reply
or routing on a keyword in a [Messaging document](/docs/swml/reference/messaging). 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](/docs/swml/reference/expressions)
  and path-based `%{...}` substitution.
* **Messaging** documents support `%{...}` only — pure path substitution with no JavaScript.

See the [Variables reference](/docs/swml/reference/variables) 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](/docs/swml/reference/calling#document-fetching-webhook).
* **Messaging** — see [Messaging SWML → Document-fetching webhook](/docs/swml/reference/messaging#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](/docs/swml/guides/deployment).

## Next steps

Quickly create and deploy SWML through the SignalWire Dashboard

Learn how AI methods are used in SWML

Methods for handling inbound and outbound calls

Methods for handling inbound SMS and MMS messages