SignalWire DocsMessaging 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.
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.
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.
The inbound message that triggered the SWML document.
Unique identifier for the inbound message segment.
The Project ID this message belongs to.
The Space ID this message belongs to.
The direction of the message. Always inbound for messages that trigger a Messaging SWML document.
The message type. Possible values: sms, mms.
Sender phone number in E.164 format.
Recipient phone number in E.164 format (the SignalWire number that received the message).
The text content of the inbound message.
Media attachments on the inbound message. Empty array when no media is attached.
URL where the media file is stored.
MIME type of the media file (e.g., image/jpeg, image/png).
Size of the media file in bytes.
Number of SMS segments the inbound message was split into.
ISO 8601 timestamp of when the inbound message was received.
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.
Result of the most recent reply step. Set after
the step completes. Possible values: queued, failed.
Message segment ID of the most recent successful reply. Set after the step completes.
Result of the most recent request step. Set
after the step completes. Possible values: success, failed, timeout, limit_exceeded.
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}.
HTTP response code from the most recent request. Set after the step completes.
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.
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.
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.
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.
Reach out to your own backend during message handling, so the reply can depend on data only your systems know.