> Fetch clean Markdown by appending `.md` to any page URL under https://signalwire.com/docs or requesting it with the HTTP header `Accept: text/markdown`. The root index at https://signalwire.com/docs/llms.txt lists the available documentation indexes.

# Calling

## Docs

- [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.
- [multilingual](https://signalwire.com/docs/swml/reference/calling/ai/multilingual.md): Configure one AI Agent to detect the caller's language and answer in it, switching as the caller switches.
- [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.


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

> Fetch clean Markdown by appending `.md` to any page URL under https://signalwire.com/docs or requesting it with the HTTP header `Accept: text/markdown`. The root index at https://signalwire.com/docs/llms.txt lists the available documentation indexes.

# 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

```yaml
version: 1.0.0
sections:
  main:
    - answer: {}
    - play:
        url: "say:Hello!"
    - hangup: {}
```

#### JSON

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

See the [SWML inbound call webhook reference](/docs/apis/rest/webhooks/inbound-call-webhook) for the complete request schema. The fields used by SWML are documented below.

**`call`** `object`

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.

---

**`call.call_id`** `string`

A unique identifier for the call.

---

**`call.call_state`** `string`

The current state of the call.

---

**`call.direction`** `string`

The direction of this call. Possible values: `inbound`, `outbound`.

---

**`call.from`** `string`

The number/URI that initiated this call.

---

**`call.headers`** `object[]`

The headers associated with this call.

---

**`call.headers[].name`** `string`

The name of the header.

---

**`call.headers[].value`** `string`

The value of the header.

---

**`call.node_id`** `string`

A unique identifier for the node handling the call.

---

**`call.project_id`** `string`

The Project ID this call belongs to.

---

**`call.segment_id`** `string`

A unique identifier for the current call segment.

---

**`call.space_id`** `string`

The Space ID this call belongs to.

---

**`call.to`** `string`

The number/URI of the destination of this call.

---

**`call.type`** `string`

The type of call. Possible values: `sip`, `phone`, `webrtc`.

---

**`call.sip_data`** `object`

SIP-specific data for SIP calls. Only present when `call.type` is `sip`. Contains detailed
SIP header information.

---

**`call.sip_data.sip_contact_host`** `string`

The host portion of the SIP Contact header.

---

**`call.sip_data.sip_contact_params`** `object`

Additional parameters from the SIP Contact header.

---

**`call.sip_data.sip_contact_port`** `string`

The port from the SIP Contact header.

---

**`call.sip_data.sip_contact_uri`** `string`

The full URI from the SIP Contact header.

---

**`call.sip_data.sip_contact_user`** `string`

The user portion of the SIP Contact header.

---

**`call.sip_data.sip_from_host`** `string`

The host portion of the SIP From header.

---

**`call.sip_data.sip_from_uri`** `string`

The full URI from the SIP From header.

---

**`call.sip_data.sip_from_user`** `string`

The user portion of the SIP From header.

---

**`call.sip_data.sip_req_host`** `string`

The host portion of the SIP request URI.

---

**`call.sip_data.sip_req_uri`** `string`

The full SIP request URI.

---

**`call.sip_data.sip_req_user`** `string`

The user portion of the SIP request URI.

---

**`call.sip_data.sip_to_host`** `string`

The host portion of the SIP To header.

---

**`call.sip_data.sip_to_uri`** `string`

The full URI from the SIP To header.

---

**`call.sip_data.sip_to_user`** `string`

The user portion of the SIP To header.

---

**`params`** `object`

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.

---

**`vars`** `object`

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

---

**`envs`** `object`

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

> **Warning**
>
> 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.<name>` 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.

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

Hand the call to a SignalWire AI agent that holds a natural conversation and can invoke SWAIG functions.

#### [amazon\_bedrock](/docs/swml/reference/calling/amazon-bedrock)

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](/docs/swml/reference/calling/answer)

Answer an inbound call. Some methods (e.g. `play`) auto-answer if needed.

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

End the call.

#### [detect\_machine](/docs/swml/reference/calling/detect-machine)

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.
Run background transcription of the call, and reduce noise for clearer audio.

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

Play TTS speech, audio files, silence, or ring tones.

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

Play audio or speech and capture DTMF or speech input.

#### [live\_transcribe](/docs/swml/reference/calling/live-transcribe)

Stream live transcription of the call.

#### [live\_translate](/docs/swml/reference/calling/live-translate)

Stream live translation of the call.

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

Transcribe the entire call in the background.

#### [transcribe\_stop](/docs/swml/reference/calling/transcribe-stop)

Stop a background transcription started by `transcribe`.

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

Start the noise reduction filter on the call audio.

#### [stop\_denoise](/docs/swml/reference/calling/stop-denoise)

Stop the noise reduction filter.

### Connecting parties

Bring other phones, SIP endpoints, video rooms, or queued agents into the call.

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

Dial out to other phone or SIP destinations — series, parallel, or mixed.

#### [join\_conference](/docs/swml/reference/calling/join-conference)

Join the call to a conference room.

#### [join\_room](/docs/swml/reference/calling/join-room)

Join the call to a SignalWire video room.

#### [enter\_queue](/docs/swml/reference/calling/enter-queue)

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](/docs/swml/reference/calling/record)

Record audio and wait for completion before continuing execution.

#### [record\_call](/docs/swml/reference/calling/record-call)

Start a background recording of the call.

#### [stop\_record\_call](/docs/swml/reference/calling/stop-record-call)

Stop a background recording started by `record_call`.

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

Stream call media to an RTP or WebSocket sink.

#### [stop\_tap](/docs/swml/reference/calling/stop-tap)

Stop a media stream started by `tap`.

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

Stream call audio to a WebSocket endpoint in the background.

#### [stop\_stream](/docs/swml/reference/calling/stop-stream)

Stop a stream started by `stream`.

### 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\_sms](/docs/swml/reference/calling/send-sms)

Send an outbound SMS to a phone number.

#### [send\_digits](/docs/swml/reference/calling/send-digits)

Send DTMF tones into the call.

#### [send\_fax](/docs/swml/reference/calling/send-fax)

Send an outbound fax.

#### [receive\_fax](/docs/swml/reference/calling/receive-fax)

Interpret the inbound call as a fax and process it.

#### [sip\_refer](/docs/swml/reference/calling/sip-refer)

Transfer a SIP call by issuing a SIP `REFER`.

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

Collect a PCI-compliant payment over the phone.

#### [user\_event](/docs/swml/reference/calling/user-event)

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.

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

Call a named section or external SWML URL as a subroutine.

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

Return from an `execute`-invoked section, optionally producing a `return_value`.

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

Tail-call into another section or external SWML document — does not return.

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

Jump to a `label` within the current section, optionally repeating up to a limit.

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

Mark a jump target for `goto`.

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

Branch on a JavaScript expression.

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

Branch on a variable's value with case matching.

### State & integration

Manage script variables, pause execution, and reach your backend over HTTP.

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

Set one or more script variables.

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

Remove one or more script variables.

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

Pause execution for a specified duration.

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

Make an HTTP request to an external URL; optionally parse the response into variables.