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 an external URL, it POSTs the
inbound message webhook payload
to your server — on the initial inbound-message fetch and on every fetch triggered by a
transfer step. 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 populate
the vars.* runtime scope — those values are not in the initial inbound payload, but they
are propagated across transfer boundaries and delivered on transfer-driven fetches.
message
The inbound message that triggered the SWML document.
message.message_id
Unique identifier for the inbound message segment.
message.project_id
The Project ID this message belongs to.
message.space_id
The Space ID this message belongs to.
message.direction
The direction of the message. Always inbound for messages that trigger a Messaging SWML document.
message.type
The message type. Possible values: sms, mms.
message.from
Sender phone number in E.164 format.
message.to
Recipient phone number in E.164 format (the SignalWire number that received the message).
message.body
The text content of the inbound message.
message.media
Media attachments on the inbound message. Empty array when no media is attached.
message.media[].url
URL where the media file is stored.
message.media[].content_type
MIME type of the media file (e.g., image/jpeg, image/png).
message.media[].size
Size of the media file in bytes.
message.segments
Number of SMS segments the inbound message was split into.
message.timestamp
ISO 8601 timestamp of when the inbound message was received.
params
vars
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 delivered as a top-level
vars field on the transfer-driven webhook payload.
The standard runtime entries are listed below. Methods may also write additional keys; see each method’s reference page for what it sets.
vars.reply_result
Result of the most recent reply step. Set after
the step completes. Possible values: queued, failed.
vars.reply_message_id
Message segment ID of the most recent successful reply. Set after the step completes.
vars.request_result
Result of the most recent request step. Set
after the step completes. Possible values: success, failed, timeout, limit_exceeded.
vars.request_response
Parsed JSON response from the most recent request. Set after the step completes when
save_variables: true was set on the request step. Access nested fields with dot
notation, e.g., %{vars.request_response.field_name}.
vars.request_response_code
HTTP response code from the most recent request. Set after the step completes.
vars.request_response_body
Raw response body from the most recent request. Set after the step completes. Truncated
to 64 KB.
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.
Send an SMS or MMS back to the sender of the inbound message. Use for auto-replies, confirmations, and keyword responses.
Accept the inbound message without sending a reply. Use to acknowledge the message without an outbound response.
Control flow
Direct execution within the document — reuse blocks of logic, repeat steps, choose between branches, or hand off the message to another document entirely.
Run another section of the current document, then resume when it finishes. Use to reuse a sequence of steps from more than one place.
Hand control back to the section that called the current one, optionally passing a value the caller can read.
Hand off the rest of the conversation to a different SWML document hosted on an external server. The current document stops; the new one takes over.
Restart from a named point earlier or later in the current section. Use for retry loops that repeat a step until it succeeds.
Mark a place in the section that goto can jump to. Labels perform no action; they serve as navigation anchors.
Choose what to do next based on a value from the inbound message or a variable. Use for keyword routing — different replies for different inbound message bodies.
External integration
Reach out to your own backend during message handling, so the reply can depend on data only your systems know.
