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

# SWML

## Docs

- [Expressions](https://signalwire.com/docs/swml/reference/expressions.md): Complete technical reference for JavaScript expressions in SMWL
- [Template functions](https://signalwire.com/docs/swml/reference/template-functions.md): Reference for built-in template transformation functions in SWML
- [Variables](https://signalwire.com/docs/swml/reference/variables.md): Syntax, scopes, deployment modes, and how to access nested data with SWML variables.
- [Errors](https://signalwire.com/docs/swml/reference/errors.md): Error codes emitted by SWML during script execution, for both calling and messaging documents.
- [Calling SWML overview](https://signalwire.com/docs/swml/reference/calling.md): Reference for Calling SWML — document structure, webhook payload, variable expansion, and methods for handling inbound and outbound calls.
- [ai](https://signalwire.com/docs/swml/reference/calling/ai.md): Create an AI agent to interact with users.
- [languages](https://signalwire.com/docs/swml/reference/calling/ai/languages.md): Configure the spoken language of your AI Agent, as well as the TTS engine, voice, and fillers.
- [params](https://signalwire.com/docs/swml/reference/calling/ai/params.md): Parameters for AI that can customize the AI agent's behavior.
- [prompt](https://signalwire.com/docs/swml/reference/calling/ai/prompt.md): Establish the set of rules and instructions for the AI agent through a prompt.
- [SWAIG](https://signalwire.com/docs/swml/reference/calling/ai/swaig.md): The SignalWire AI Gateway Interface. Allows you to create user-defined functions that can be executed during the dialogue.
- [functions](https://signalwire.com/docs/swml/reference/calling/ai/swaig/functions.md): Functions that can be executed during the interaction with the AI.
- [data_map](https://signalwire.com/docs/swml/reference/calling/ai/swaig/functions/data-map.md): Defines how a SWAIG function should process and respond to the user's input data.
- [parameters](https://signalwire.com/docs/swml/reference/calling/ai/swaig/functions/parameters.md): The parameters object for the SWAIG function.
- [includes](https://signalwire.com/docs/swml/reference/calling/ai/swaig/includes.md): Remote function signatures to include in SWAIG functions.
- [ai_sidecar](https://signalwire.com/docs/swml/reference/calling/ai-sidecar.md): Attach a real-time AI observer that streams agent-facing advice events during a live call.
- [params](https://signalwire.com/docs/swml/reference/calling/ai-sidecar/params.md): Tuning knobs for the ai_sidecar method that control how it reacts, summarization, transcription, and debugging.
- [prompt](https://signalwire.com/docs/swml/reference/calling/ai-sidecar/prompt.md): The operator prompt that instructs the ai_sidecar observer how to coach the agent.
- [SWAIG](https://signalwire.com/docs/swml/reference/calling/ai-sidecar/swaig.md): Functions and MCP servers the ai_sidecar observer can call while watching a call.
- [amazon_bedrock](https://signalwire.com/docs/swml/reference/calling/amazon-bedrock.md): Create an Amazon Bedrock agent interaction.
- [params](https://signalwire.com/docs/swml/reference/calling/amazon-bedrock/params.md): Parameters for the Amazon Bedrock that can customize the agent's behavior.
- [prompt](https://signalwire.com/docs/swml/reference/calling/amazon-bedrock/prompt.md): Establish the set of rules and instructions for the Amazon Bedrock agent through a prompt.
- [SWAIG](https://signalwire.com/docs/swml/reference/calling/amazon-bedrock/swaig.md): The SignalWire AI Gateway Interface. Allows you to create user-defined functions that can be executed during the dialogue.
- [functions](https://signalwire.com/docs/swml/reference/calling/amazon-bedrock/swaig/functions.md): Functions that can be executed during the interaction with the Amazon Bedrock agent.
- [data_map](https://signalwire.com/docs/swml/reference/calling/amazon-bedrock/swaig/functions/data-map.md): Defines how a SWAIG function should process and respond to the user's input data.
- [parameters](https://signalwire.com/docs/swml/reference/calling/amazon-bedrock/swaig/functions/parameters.md): The parameters object for the SWAIG function.
- [answer](https://signalwire.com/docs/swml/reference/calling/answer.md): Answer incoming call and set an optional maximum duration.
- [cond](https://signalwire.com/docs/swml/reference/calling/cond.md): Execute a sequence of instructions depending on the value of a JavaScript condition.
- [connect](https://signalwire.com/docs/swml/reference/calling/connect.md): Connect to a phone number, SIP URI, Resource Address, queue, or WebSocket stream.
- [denoise](https://signalwire.com/docs/swml/reference/calling/denoise.md): Start noise reduction.
- [detect_machine](https://signalwire.com/docs/swml/reference/calling/detect-machine.md): Detect whether the other end of the call is a machine (fax, voicemail, etc.) or a human, using AMD and fax detection.
- [enter_queue](https://signalwire.com/docs/swml/reference/calling/enter-queue.md): Place the call in a queue.
- [execute](https://signalwire.com/docs/swml/reference/calling/execute.md): Execute a specified section or URL as a subroutine, and upon completion, return to the current document.
- [goto](https://signalwire.com/docs/swml/reference/calling/goto.md): Jumps to a defined label in the current SWML section.
- [hangup](https://signalwire.com/docs/swml/reference/calling/hangup.md): Ends the call.
- [join_conference](https://signalwire.com/docs/swml/reference/calling/join-conference.md): Join an ad-hoc audio conference with Relay and CXML calls.
- [join_room](https://signalwire.com/docs/swml/reference/calling/join-room.md): Join a Relay Room Session.
- [label](https://signalwire.com/docs/swml/reference/calling/label.md): Mark any point of the SWML section with a label.
- [live_transcribe](https://signalwire.com/docs/swml/reference/calling/live-transcribe.md): Transcribe a voice interaction in real-time.
- [live_translate](https://signalwire.com/docs/swml/reference/calling/live-translate.md): Translate a voice interaction in real-time.
- [pay](https://signalwire.com/docs/swml/reference/calling/pay.md): Enable secure payment processing during voice calls.
- [play](https://signalwire.com/docs/swml/reference/calling/play.md): Play file(s), ringtones, speech or silence.
- [prompt](https://signalwire.com/docs/swml/reference/calling/prompt.md): Play a prompt and wait for input.
- [receive_fax](https://signalwire.com/docs/swml/reference/calling/receive-fax.md): Receive a fax being delivered to this call.
- [record](https://signalwire.com/docs/swml/reference/calling/record.md): Record the call audio in the foreground pausing further SWML execution until recording ends.
- [record_call](https://signalwire.com/docs/swml/reference/calling/record-call.md): Record call in the background.
- [request](https://signalwire.com/docs/swml/reference/calling/request.md): Send a HTTP request to a remote URL.
- [return](https://signalwire.com/docs/swml/reference/calling/return.md): Return from a `execute` method or exit script.
- [send_digits](https://signalwire.com/docs/swml/reference/calling/send-digits.md): Send digit presses as DTMF tones.
- [send_fax](https://signalwire.com/docs/swml/reference/calling/send-fax.md): Send a fax.
- [send_sms](https://signalwire.com/docs/swml/reference/calling/send-sms.md): Send an outbound message to a PSTN phone number.
- [set](https://signalwire.com/docs/swml/reference/calling/set.md): Set script variables to the specified values.
- [sip_refer](https://signalwire.com/docs/swml/reference/calling/sip-refer.md): Send a SIP REFER to a SIP call.
- [sleep](https://signalwire.com/docs/swml/reference/calling/sleep.md): Set the amount of time for the current application to sleep for in milliseconds before continuing to the next action.
- [stop_denoise](https://signalwire.com/docs/swml/reference/calling/stop-denoise.md): Stop noise reduction.
- [stop_record_call](https://signalwire.com/docs/swml/reference/calling/stop-record-call.md): Stop an active background recording.
- [stop_stream](https://signalwire.com/docs/swml/reference/calling/stop-stream.md): Stop an active audio stream.
- [stop_tap](https://signalwire.com/docs/swml/reference/calling/stop-tap.md): Stop an active tap stream.
- [stream](https://signalwire.com/docs/swml/reference/calling/stream.md): Start a background audio stream from the call to a WebSocket endpoint.
- [switch](https://signalwire.com/docs/swml/reference/calling/switch.md): Execute different instructions based on a variable's value.
- [tap](https://signalwire.com/docs/swml/reference/calling/tap.md): Start background call tap. Media is streamed over Websocket or RTP to customer controlled URI.
- [transcribe](https://signalwire.com/docs/swml/reference/calling/transcribe.md): Transcribe the entire call in the background. Use live_transcribe for real-time transcription.
- [transcribe_stop](https://signalwire.com/docs/swml/reference/calling/transcribe-stop.md): Stop an active background transcription.
- [transfer](https://signalwire.com/docs/swml/reference/calling/transfer.md): Transfer the execution of the script to a different `SWML section`, `URL`, or `Relay application`.
- [unset](https://signalwire.com/docs/swml/reference/calling/unset.md): Unset specified variables.
- [user_event](https://signalwire.com/docs/swml/reference/calling/user-event.md): Send custom events to the connected client on the call.
- [Messaging SWML overview](https://signalwire.com/docs/swml/reference/messaging.md): Reference for Messaging SWML — document modes, webhook payload, variable expansion, and methods for handling inbound SMS and MMS.
- [execute](https://signalwire.com/docs/swml/reference/messaging/execute.md): Call a named section as a subroutine and return when it completes.
- [goto](https://signalwire.com/docs/swml/reference/messaging/goto.md): Jump to a labeled position in the current section.
- [label](https://signalwire.com/docs/swml/reference/messaging/label.md): Mark a position in the current section so that goto can jump to it.
- [receive](https://signalwire.com/docs/swml/reference/messaging/receive.md): Accept an inbound message without sending a reply.
- [reply](https://signalwire.com/docs/swml/reference/messaging/reply.md): Create and send an outbound message in response to an inbound message.
- [request](https://signalwire.com/docs/swml/reference/messaging/request.md): Make an HTTP request to an external URL during inbound message handling.
- [return](https://signalwire.com/docs/swml/reference/messaging/return.md): Return from the current section, optionally with a value.
- [switch](https://signalwire.com/docs/swml/reference/messaging/switch.md): Branch on a variable's value, with optional text transforms.
- [transfer](https://signalwire.com/docs/swml/reference/messaging/transfer.md): Tail-call to a new SWML document fetched from a URL.
- [Quickstart](https://signalwire.com/docs/swml/guides.md): Deploy your first SWML script in minutes with this step-by-step guide
- [Control program flow](https://signalwire.com/docs/swml/guides/goto-execute-transfer-disambiguation.md): Learn how to use the goto, execute, and transfer methods in SWML.
- [Deploy SWML from web servers](https://signalwire.com/docs/swml/guides/deployment.md): Learn how to serve SWML scripts from web servers and Relay applications.
- [Handle incoming calls from code](https://signalwire.com/docs/swml/guides/remote-server.md): Learn how to handle incoming calls from a remote server using SWML.
- [Send simple HTTP requests](https://signalwire.com/docs/swml/guides/request.md): Learn how to use the request method in SWML to send HTTP requests to a web server.
- [Call whisper](https://signalwire.com/docs/swml/guides/call-whisper.md): A guide that shows you how to perform a Call Whisper using SWML.
- [Forwarding calls](https://signalwire.com/docs/swml/guides/forward-calls.md): Use SWML to forward calls
- [Making and receiving phone calls](https://signalwire.com/docs/swml/guides/make-and-receive-calls.md): Overview of the many ways you can make and receive calls using SignalWire products.
- [Recording calls](https://signalwire.com/docs/swml/guides/record-calls.md): Using SWML to record ongoing calls.
- [Setting up voicemail](https://signalwire.com/docs/swml/guides/voicemail.md): Set up voicemail on a number using SWML.
- [Simple IVR](https://signalwire.com/docs/swml/guides/ivr.md): Learn how to create a simple IVR with SWML.
- [SWAIG](https://signalwire.com/docs/swml/guides/swaig.md): The SignalWire AI Gateway connects your AI Agents to functionality on your backend.
- [Enable functions dynamically](https://signalwire.com/docs/swml/guides/toggle-functions.md): Learn how to use `toggle_functions` to toggle functions on and off.
- [Execute SWML from a function](https://signalwire.com/docs/swml/guides/executing-swml.md): Learn how to execute SWML from a SWAIG function.
- [Handle SWAIG function calls inline](https://signalwire.com/docs/swml/guides/data-map.md): Learn how to use `data_map` in SWML SWAIG functions to process, transform, and utilize incoming data effectively.
- [Store data outside LLM context](https://signalwire.com/docs/swml/guides/set-meta-data.md): Learn how to use the `set_meta_data` action to store function metadata without exposing it to the LLM.
- [Switch AI context mid-call](https://signalwire.com/docs/swml/guides/context-switch.md): Learn how to use `context_switch` to shift the focus of the conversation.


> **Note:** This page contains both a page directory (above) and the landing page content (below). The page directory is generated for agent use and does not appear on the landing page.

> 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
[Server 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

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

#### JSON

```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

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

#### JSON

```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.

**`version`** `string` — default: 1.0.0

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

---

**`sections`** `object` — required

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

---

**`sections.main`** `object[]` — required

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.

---

**`sections.<name>`** `object[]`

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

#### [Quickstart](/docs/swml/guides)

Quickly create and deploy SWML through the SignalWire Dashboard

#### [AI guides](/docs/swml/guides)

Learn how AI methods are used in SWML

#### [Calling reference](/docs/swml/reference/calling)

Methods for handling inbound and outbound calls

#### [Messaging reference](/docs/swml/reference/messaging)

Methods for handling inbound SMS and MMS messages