> For a complete index of all SignalWire documentation pages, fetch https://signalwire.com/docs/llms.txt # Calling SWML overview > Reference for Calling SWML — document structure, webhook payload, variable expansion, and methods for handling inbound and outbound calls. Calling SWML is the flavor of SWML used to handle voice calls — inbound calls arriving on a phone number configured with a SWML calling handler, outbound REST-initiated calls that point at a SWML URL, and re-fetches triggered by methods that hit an external URL. For handling inbound SMS and MMS messages, see the [Messaging SWML overview](/docs/swml/reference/messaging). ## Document structure A Calling SWML document follows the standard [SWML document structure](/docs/swml#document-structure) — a top-level `sections` map with `sections.main` as the entry point. Each section contains an array of [calling methods](#methods) that run sequentially. ```yaml version: 1.0.0 sections: main: - answer: {} - play: url: "say:Hello!" - hangup: {} ``` ```json { "version": "1.0.0", "sections": { "main": [ { "answer": {} }, { "play": { "url": "say:Hello!" } }, { "hangup": {} } ] } } ``` ## Webhook and variable payload \[#webhook-payload] When SignalWire fetches a Calling SWML document from an external URL, it POSTs this payload to your server — on the initial inbound fetch and on every fetch triggered by a method that hits an external URL (`execute` with a remote URL, [`transfer`](/docs/swml/reference/calling/transfer), [`join_conference.wait_url`](/docs/swml/reference/calling/join-conference#properties), [`enter_queue.wait_url`](/docs/swml/reference/calling/enter-queue#properties), and [`connect.confirm`](/docs/swml/reference/calling/connect#properties)). Your server must respond with a valid SWML document using one of these content types: `application/json`, `application/yaml`, or `text/x-yaml`. Inside the executing document, the `call`, `params`, and `envs` fields are available for variable expansion via `${...}` (JavaScript expressions) and `%{...}` (path substitution). As the script runs, methods also populate the **`vars.*` runtime scope** — those values are not in the initial inbound payload, but they are propagated across `transfer` boundaries and delivered on subsequent fetches. Information about the current call. Call-specific and read-only. Each call leg (A-leg, B-leg) has its own unique `call` object with different `call_id`, `from`, `to`, etc. When connecting to a new leg, the `call` object is re-initialized with the new leg's data. A unique identifier for the call. The current state of the call. The direction of this call. Possible values: `inbound`, `outbound`. The number/URI that initiated this call. The headers associated with this call. The name of the header. The value of the header. A unique identifier for the node handling the call. The Project ID this call belongs to. A unique identifier for the current call segment. The Space ID this call belongs to. The number/URI of the destination of this call. The type of call. Possible values: `sip`, `phone`, `webrtc`. SIP-specific data for SIP calls. Only present when `call.type` is `sip`. Contains detailed SIP header information. The host portion of the SIP Contact header. Additional parameters from the SIP Contact header. The port from the SIP Contact header. The full URI from the SIP Contact header. The user portion of the SIP Contact header. The host portion of the SIP From header. The full URI from the SIP From header. The user portion of the SIP From header. The host portion of the SIP request URI. The full SIP request URI. The user portion of the SIP request URI. The host portion of the SIP To header. The full URI from the SIP To header. The user portion of the SIP To header. Parameters passed by the calling [`execute`](/docs/swml/reference/calling/execute) or [`transfer`](/docs/swml/reference/calling/transfer) step. Empty `{}` on the initial inbound fetch. Section-scoped — each `execute`/`transfer` replaces (does not merge with) the caller's `params`; when an `execute` returns, the caller's original `params` are restored. Runtime variable scope, populated by methods as the script executes. **Not part of the initial inbound payload** — values appear here only after a method that sets them has run. The full `vars` object is propagated across `transfer` boundaries (and on remote-URL `execute`) and delivered as a top-level `vars` field on subsequent webhook payloads. **Created by:** [`set`](/docs/swml/reference/calling/set) — explicitly create or update variables. Method outputs — many methods auto-populate variables (e.g., `prompt_value`, `record_url`, `return_value`). See each method's reference page for what it sets. **Removed by:** [`unset`](/docs/swml/reference/calling/unset). **Scope:** Global within a single call session. Variables persist across all sections and through `execute` calls. Connecting to a new call leg resets the `vars` object to an empty state. **Access:** Variables can be accessed with or without the `vars.` prefix. When you reference a variable without a scope prefix (e.g., `${my_variable}`), SWML first checks `vars`. If not found in `vars`, it automatically falls back to `envs`. Environment variables configured at the account or project level. Account/project-scoped and read-only. Set in your SignalWire account configuration, not within SWML scripts. **Fallback behavior:** When you reference a variable without a scope prefix (e.g., `${my_variable}`), SWML first checks `vars`. If not found in `vars`, it automatically falls back to `envs`. The `envs` object is included in POST request bodies to external servers, but the ability to set environment variables in the SignalWire Dashboard is not yet available in production. This feature is coming soon. See [Variables](/docs/swml/reference/variables) for variable-expansion syntax, deployment-mode differences, and tips on accessing nested fields and array elements. ## Methods A method is a single step in a SWML document — each item in a `sections.` array invokes one method. Each method's reference page documents its parameters, defaults, and any output variables it sets. Methods below are grouped by what they do. ### Conversational AI Hand the call to an AI agent that holds a natural conversation, recognizes intent, and can call out to your backend via SWAIG functions or webhooks. Hand the call to a SignalWire AI agent that holds a natural conversation and can invoke SWAIG functions. Hand the call to an Amazon Bedrock-backed AI agent. ### Call lifecycle Control when the call is answered, ended, and what kind of party is on the other end before deciding how to handle it. Answer an inbound call. Some methods (e.g. `play`) auto-answer if needed. End the call. Detect whether the answering party is a human or an answering machine. ### Audio & speech Play audio to the caller, prompt for input, and stream live transcription or translation. Includes noise reduction for clearer audio. Play TTS speech, audio files, silence, or ring tones. Play audio or speech and capture DTMF or speech input. Stream live transcription of the call. Stream live translation of the call. Start the noise reduction filter on the call audio. Stop the noise reduction filter. ### Connecting parties Bring other phones, SIP endpoints, video rooms, or queued agents into the call. Dial out to other phone or SIP destinations — series, parallel, or mixed. Join the call to a conference room. Join the call to a SignalWire video room. Place the call in a queue with wait music, timeout, and status callbacks. ### Recording & taps Record the call to storage, or stream call media to an external sink in real time. Record audio and wait for completion before continuing execution. Start a background recording of the call. Stop a background recording started by `record_call`. Stream call media to an RTP or WebSocket sink. Stop a media stream started by `tap`. ### Messaging & side channels Send messages, faxes, DTMF, and other out-of-band signals from inside a call. Also collects payments and emits custom project events. Send an outbound SMS to a phone number. Send DTMF tones into the call. Send an outbound fax. Interpret the inbound call as a fax and process it. Transfer a SIP call by issuing a SIP `REFER`. Collect a PCI-compliant payment over the phone. Emit a custom event onto the project's event stream. ### Control flow Direct execution within a SWML document — call subroutines, jump between labels, branch on expressions, or tail-call into another document entirely. Call a named section or external SWML URL as a subroutine. Return from an `execute`-invoked section, optionally producing a `return_value`. Tail-call into another section or external SWML document — does not return. Jump to a `label` within the current section, optionally repeating up to a limit. Mark a jump target for `goto`. Branch on a JavaScript expression. Branch on a variable's value with case matching. ### State & integration Manage script variables, pause execution, and reach your backend over HTTP. Set one or more script variables. Remove one or more script variables. Pause execution for a specified duration. Make an HTTP request to an external URL; optionally parse the response into variables.