Calling SWML overview

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.

Document structure

A Calling SWML document follows the standard SWML document structure — a top-level sections map with sections.main as the entry point. Each section contains an array of calling methods that run sequentially.

1
version: 1.0.0
2
sections:
3
  main:
4
    - answer: {}
5
    - play:
6
        url: "say:Hello!"
7
    - hangup: {}

Webhook and variable 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, join_conference.wait_url, enter_queue.wait_url, and connect.confirm). 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.

1
{
2
  "call": {
3
    "call_id": "c2d3e4f5-a6b7-8901-cdef-234567890abc",
4
    "node_id": "a1b2c3d4-1111-2222-3333-444455556666",
5
    "segment_id": "d3e4f5a6-b7c8-9012-defa-345678901bcd",
6
    "call_state": "created",
7
    "direction": "inbound",
8
    "type": "sip",
9
    "from": "sip:user@example.com",
10
    "to": "sip:destination@yourdomain.com",
11
    "headers": [],
12
    "project_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
13
    "space_id": "d3e4f5a6-b7c8-9012-defa-345678901bcd"
14
  },
15
  "vars": {
16
    "user_selection": "1"
17
  },
18
  "envs": {
19
    "api_key": "<YOUR_API_KEY>",
20
    "webhook_url": "https://example.com/webhook",
21
    "id": "12345",
22
    "case_number": "54321"
23
  },
24
  "params": {
25
    "department": "sales"
26
  }
27
}

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

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.

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.

Connecting parties

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

Recording & taps

Record the call to storage, or stream call media to an external sink in real time.

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.

Control flow

Direct execution within a SWML document — call subroutines, jump between labels, branch on expressions, or tail-call into another document entirely.

State & integration

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