{"slug":"swml-overview","title":"SWML — SignalWire Markup Language Overview","tags":["signalwire","swml","call-flow","voice"],"agent_summary":"SWML is JSON or YAML that defines a call flow. Covers the document shape (version, sections, main), verb categories, expression substitution, and how SWML is served (hosted file, web hook, Call Flow Builder, or generated by Python SDK).","trigger_phrases":["what is SWML","SWML document structure","SWML sections main","SWML version 1.0.0","how to host SWML","SWML vs TwiML"],"runnable":true,"markdown":"\n# SWML — SignalWire Markup Language\n\nSWML is a JSON or YAML script that describes a phone call. Each call execution loads one SWML document and runs the verbs inside it. SWML is the SignalWire equivalent of TwiML — but it is JSON-first, has a built-in `ai` verb, supports expression substitution natively, and accepts both `.json` and `.yaml`.\n\n## Document shape\n\n```yaml\nversion: 1.0.0\nsections:\n main:\n - answer: {}\n - play:\n url: \"say:Hello there.\"\n - hangup: {}\n```\n\nEquivalent JSON:\n\n```json\n{\n \"version\": \"1.0.0\",\n \"sections\": {\n \"main\": [\n { \"answer\": {} },\n { \"play\": { \"url\": \"say:Hello there.\" } },\n { \"hangup\": {} }\n ]\n }\n}\n```\n\n`sections` is an object; `main` is the entry section. Other named sections are reachable via `goto`, `execute`, or `swml_transfer`.\n\n## How SWML is served\n\n| Source | When to use |\n|---|---|\n| Hosted file (S3, your CDN, a static URL) | Truly static flows |\n| Web hook returning SWML | Anything dynamic — flow depends on caller, time, CRM lookup |\n| Call Flow Builder export | No-code visual flow, deployed inside the SignalWire portal |\n| Python Agents SDK | Programmatic, AI-first agents (auto-generates the SWML) |\n\nSignalWire fetches the SWML each call. The endpoint must return `application/json` or `application/yaml`. A web hook can vary the SWML per call by reading the inbound request body.\n\n## Verb categories\n\n### Call control\n\n| Verb | Notes |\n|---|---|\n| `answer` | Answers the inbound call. Optional unless explicit timing matters. |\n| `hangup` | Ends the call. Reason field is for logs. |\n| `connect` | Bridges to a PSTN number, SIP URI, or another endpoint. See [connect verb](/topic/swml-connect-verb). |\n| `goto` | Jumps to another section or step inside the current document. |\n| `execute` | Fetches and runs a sub-document, returns when done. |\n| `cond` | Conditional branching (if/elif/else). |\n\n### Media\n\n| Verb | Notes |\n|---|---|\n| `play` | Plays an audio URL, ringtone, silence, or TTS via the `say:` prefix. |\n| `prompt` | Plays a prompt and gathers DTMF or speech. |\n| `record` | Foreground recording (blocking). Use for voicemail. |\n| `record_call` | Background recording (non-blocking). Use for dashboards. |\n| `live_transcribe` | Real-time transcript streaming to a webhook. |\n| `tap` | Forks audio to another endpoint for live monitoring. |\n| `denoise` | Enables noise suppression mid-call. |\n\n### AI\n\n| Verb | Notes |\n|---|---|\n| `ai` | Runs an AI agent inside the call — speech in, speech out, SWAIG functions. See [ai verb](/topic/swml-ai-verb). |\n| `context_switch` | Switches the active AI context mid-call. See [context switch](/topic/swml-context-switch). |\n\n### Queue / conference\n\n| Verb | Notes |\n|---|---|\n| `enter_queue` | Place the caller in a call queue. |\n| `join_conference` | Add the caller to a conference room. |\n| `join_room` | Join a Relay video room. |\n\n### Detection\n\n| Verb | Notes |\n|---|---|\n| `detect_machine` | Answering-machine detection — branches based on human/voicemail outcome. |\n\n## Expression substitution\n\nSWML supports inline expressions in any string field.\n\n| Pattern | Expands to |\n|---|---|\n| `%{call.from}` | Caller's E.164 number |\n| `%{call.to}` | The dialed DID |\n| `%{call.call_id}` | Unique call ID |\n| `%{call.direction}` | `inbound` or `outbound` |\n| `%{vars.}` | Custom variable set earlier |\n| `%{record_call_url}` | URL of last `record_call` recording |\n| `%{record_url}` | URL of last `record` (foreground) recording |\n| `%{prompt_value}` | Speech value from last `prompt` |\n\nExpressions also accept light JavaScript:\n\n```yaml\n- play:\n url: \"say:Your area code is %{call.from.slice(2,5)}.\"\n```\n\nIn SWAIG/data-map context the prefix is `${...}` (not `%{...}`). The `%{...}` form is the SWML in-document substitution prefix; `${...}` is the SWAIG/DataMap variable prefix.\n\n## Sections, goto, and execute\n\n`goto` is in-document jumping. `execute` is a sub-routine — fetches and runs a remote SWML, returns.\n\n```yaml\nversion: 1.0.0\nsections:\n main:\n - prompt:\n play: \"say:Press 1 for sales, 2 for support.\"\n max_digits: 1\n terminators: \"#\"\n - cond:\n if: \"%{prompt_value} == '1'\"\n then:\n - goto:\n section: sales\n elif: \"%{prompt_value} == '2'\"\n then:\n - goto:\n section: support\n else:\n - play:\n url: \"say:Invalid choice.\"\n - hangup: {}\n sales:\n - connect:\n to: \"+15555550101\"\n support:\n - connect:\n to: \"+15555550102\"\n```\n\n## Anti-patterns\n\n- Forgetting `version: 1.0.0` at the top — script fails validation.\n- Returning HTML or plain text from your webhook — must be JSON or YAML with the correct content type.\n- Calling `goto` with a section name that doesn't exist — call hangs up silently.\n- Mixing `%{...}` (SWML) and `${...}` (SWAIG/DataMap) prefixes — wrong prefix = no substitution.\n- Hosting SWML on a slow endpoint — every call pays the round-trip. Aim for sub-200ms.\n\n## See also\n\n- [SWML AI verb](/topic/swml-ai-verb)\n- [SWML connect](/topic/swml-connect-verb)\n- [SWML record and transcribe](/topic/swml-record-and-transcribe)\n- [SWML IVR and gather](/topic/swml-ivr-and-gather)\n- [Call Flow Builder](/topic/signalwire-call-flow-builder)\n","html":"

SWML — SignalWire Markup Language

\n

SWML is a JSON or YAML script that describes a phone call. Each call execution loads one SWML document and runs the verbs inside it. SWML is the SignalWire equivalent of TwiML — but it is JSON-first, has a built-in ai verb, supports expression substitution natively, and accepts both .json and .yaml.

\n

Document shape

\n
version: 1.0.0\nsections:\n  main:\n    - answer: {}\n    - play:\n        url: \"say:Hello there.\"\n    - hangup: {}\n
\n

Equivalent JSON:

\n
{\n  \"version\": \"1.0.0\",\n  \"sections\": {\n    \"main\": [\n      { \"answer\": {} },\n      { \"play\": { \"url\": \"say:Hello there.\" } },\n      { \"hangup\": {} }\n    ]\n  }\n}\n
\n

sections is an object; main is the entry section. Other named sections are reachable via goto, execute, or swml_transfer.

\n

How SWML is served

\n

| Source | When to use |\n|---|---|\n| Hosted file (S3, your CDN, a static URL) | Truly static flows |\n| Web hook returning SWML | Anything dynamic — flow depends on caller, time, CRM lookup |\n| Call Flow Builder export | No-code visual flow, deployed inside the SignalWire portal |\n| Python Agents SDK | Programmatic, AI-first agents (auto-generates the SWML) |

\n

SignalWire fetches the SWML each call. The endpoint must return application/json or application/yaml. A web hook can vary the SWML per call by reading the inbound request body.

\n

Verb categories

\n

Call control

\n

| Verb | Notes |\n|---|---|\n| answer | Answers the inbound call. Optional unless explicit timing matters. |\n| hangup | Ends the call. Reason field is for logs. |\n| connect | Bridges to a PSTN number, SIP URI, or another endpoint. See connect verb. |\n| goto | Jumps to another section or step inside the current document. |\n| execute | Fetches and runs a sub-document, returns when done. |\n| cond | Conditional branching (if/elif/else). |

\n

Media

\n

| Verb | Notes |\n|---|---|\n| play | Plays an audio URL, ringtone, silence, or TTS via the say: prefix. |\n| prompt | Plays a prompt and gathers DTMF or speech. |\n| record | Foreground recording (blocking). Use for voicemail. |\n| record_call | Background recording (non-blocking). Use for dashboards. |\n| live_transcribe | Real-time transcript streaming to a webhook. |\n| tap | Forks audio to another endpoint for live monitoring. |\n| denoise | Enables noise suppression mid-call. |

\n

AI

\n

| Verb | Notes |\n|---|---|\n| ai | Runs an AI agent inside the call — speech in, speech out, SWAIG functions. See ai verb. |\n| context_switch | Switches the active AI context mid-call. See context switch. |

\n

Queue / conference

\n

| Verb | Notes |\n|---|---|\n| enter_queue | Place the caller in a call queue. |\n| join_conference | Add the caller to a conference room. |\n| join_room | Join a Relay video room. |

\n

Detection

\n

| Verb | Notes |\n|---|---|\n| detect_machine | Answering-machine detection — branches based on human/voicemail outcome. |

\n

Expression substitution

\n

SWML supports inline expressions in any string field.

\n

| Pattern | Expands to |\n|---|---|\n| %{call.from} | Caller's E.164 number |\n| %{call.to} | The dialed DID |\n| %{call.call_id} | Unique call ID |\n| %{call.direction} | inbound or outbound |\n| %{vars.<key>} | Custom variable set earlier |\n| %{record_call_url} | URL of last record_call recording |\n| %{record_url} | URL of last record (foreground) recording |\n| %{prompt_value} | Speech value from last prompt |

\n

Expressions also accept light JavaScript:

\n
- play:\n    url: \"say:Your area code is %{call.from.slice(2,5)}.\"\n
\n

In SWAIG/data-map context the prefix is ${...} (not %{...}). The %{...} form is the SWML in-document substitution prefix; ${...} is the SWAIG/DataMap variable prefix.

\n

Sections, goto, and execute

\n

goto is in-document jumping. execute is a sub-routine — fetches and runs a remote SWML, returns.

\n
version: 1.0.0\nsections:\n  main:\n    - prompt:\n        play: \"say:Press 1 for sales, 2 for support.\"\n        max_digits: 1\n        terminators: \"#\"\n    - cond:\n        if: \"%{prompt_value} == '1'\"\n        then:\n          - goto:\n              section: sales\n        elif: \"%{prompt_value} == '2'\"\n        then:\n          - goto:\n              section: support\n        else:\n          - play:\n              url: \"say:Invalid choice.\"\n          - hangup: {}\n  sales:\n    - connect:\n        to: \"+15555550101\"\n  support:\n    - connect:\n        to: \"+15555550102\"\n
\n

Anti-patterns

\n\n

See also

\n\n"}