Messaging SWML overview

Messaging SWML is the flavor of SWML used to handle inbound SMS and MMS messages. When a message arrives on a phone number configured with a SWML message handler, SignalWire fetches and processes the SWML document, optionally sending an outbound reply.

For handling voice calls, see the Calling SWML overview.

Document structure

A Messaging 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 messaging methods that run sequentially. A document can execute up to 100 method steps per inbound message; once that ceiling is hit, execution stops.

Webhook and variable payload

When SignalWire fetches a Messaging SWML document from a URL, it sends the inbound message webhook payload to your server in the request body. The request method depends on what triggered the fetch:

• The initial fetch, when the message arrives, uses the request method set on the SWML Webhook assigned to the phone number: primary_request_method for its primary URL, or fallback_request_method when SignalWire falls back to its fallback URL. Both default to POST.
• A fetch triggered by a transfer step uses transfer.method (POST by default).
• A fetch triggered by an execute step always uses POST.

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 same message and params fields are available for %{...} variable expansion (for example, %{message.from}). As the script runs, methods also set runtime variables such as request_result, which you read the same way (for example, %{request_result}). Those values are not in the initial inbound payload. On fetches triggered by transfer or execute, the current values are sent to your server in the payload’s vars field.

{
  "message": {
    "message_id": "c2d3e4f5-a6b7-8901-cdef-234567890abc",
    "project_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "space_id": "d3e4f5a6-b7c8-9012-defa-345678901bcd",
    "direction": "inbound",
    "type": "sms",
    "from": "+15551231234",
    "to": "+15553214321",
    "body": "Hello, I need help",
    "media": [],
    "segments": 1,
    "timestamp": "2024-01-15T10:30:00Z"
  },
  "params": {}
}

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 full-mode 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.

Message handling

Decide what to do with the inbound message — send an outbound reply, or accept it silently.

Control flow

Direct execution within the document — reuse blocks of logic, repeat steps, choose between branches, or hand off the message to another section or document.

External integration

Reach out to your own backend during message handling, so the reply can depend on data only your systems know.