> This page is for SWML. > 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. # Messaging SWML overview > Reference for Messaging SWML — document modes, webhook payload, variable expansion, and methods for handling inbound SMS and MMS. 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](/docs/swml/reference/calling). ## Document structure A Messaging 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 [messaging methods](#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 \[#webhook-payload] When SignalWire fetches a Messaging SWML document from an external URL, it POSTs the [inbound message webhook payload](/docs/apis/rest/webhooks/inbound-message-webhook) to your server — on the initial inbound-message fetch and on every fetch triggered by a [`transfer`](/docs/swml/reference/messaging/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. See the [SWML inbound message webhook reference](/docs/apis/rest/webhooks/inbound-message-webhook) for the complete request schema. The fields used by SWML are documented below. **`message`** `object` The inbound message that triggered the SWML document. --- **`message.message_id`** `string` Unique identifier for the inbound message segment. --- **`message.project_id`** `string` The Project ID this message belongs to. --- **`message.space_id`** `string` The Space ID this message belongs to. --- **`message.direction`** `string` The direction of the message. Always `inbound` for messages that trigger a Messaging SWML document. --- **`message.type`** `string` The message type. Possible values: `sms`, `mms`. --- **`message.from`** `string` Sender phone number in E.164 format. --- **`message.to`** `string` Recipient phone number in E.164 format (the SignalWire number that received the message). --- **`message.body`** `string` The text content of the inbound message. --- **`message.media`** `object[]` Media attachments on the inbound message. Empty array when no media is attached. --- **`message.media[].url`** `string` URL where the media file is stored. --- **`message.media[].content_type`** `string` MIME type of the media file (e.g., `image/jpeg`, `image/png`). --- **`message.media[].size`** `integer` Size of the media file in bytes. --- **`message.segments`** `integer` Number of SMS segments the inbound message was split into. --- **`message.timestamp`** `string` ISO 8601 timestamp of when the inbound message was received. --- **`params`** `object` Parameters passed by the calling [`transfer`](/docs/swml/reference/messaging/transfer) or [`execute`](/docs/swml/reference/messaging/execute) step. Empty `{}` on the initial inbound fetch. Section-scoped — restored to the caller's value when an `execute` returns. --- **`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 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`** `string` Result of the most recent [`reply`](/docs/swml/reference/messaging/reply) step. Set after the step completes. Possible values: `queued`, `failed`. --- **`vars.reply_message_id`** `string` Message segment ID of the most recent successful `reply`. Set after the step completes. --- **`vars.request_result`** `string` Result of the most recent [`request`](/docs/swml/reference/messaging/request) step. Set after the step completes. Possible values: `success`, `failed`, `timeout`, `limit_exceeded`. --- **`vars.request_response`** `object` 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`** `integer` HTTP response code from the most recent `request`. Set after the step completes. --- **`vars.request_response_body`** `string` Raw response body from the most recent `request`. Set after the step completes. Truncated to 64 KB. --- 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 full-mode SWML document — each item in a `sections.` 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. #### [reply](/docs/swml/reference/messaging/reply) Send an SMS or MMS back to the sender of the inbound message. Use for auto-replies, confirmations, and keyword responses. #### [receive](/docs/swml/reference/messaging/receive) 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. #### [execute](/docs/swml/reference/messaging/execute) Run another section of the current document, then resume when it finishes. Use to reuse a sequence of steps from more than one place. #### [return](/docs/swml/reference/messaging/return) Hand control back to the section that called the current one, optionally passing a value the caller can read. #### [transfer](/docs/swml/reference/messaging/transfer) 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. #### [goto](/docs/swml/reference/messaging/goto) Restart from a named point earlier or later in the current section. Use for retry loops that repeat a step until it succeeds. #### [label](/docs/swml/reference/messaging/label) Mark a place in the section that `goto` can jump to. Labels perform no action; they serve as navigation anchors. #### [switch](/docs/swml/reference/messaging/switch) 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. #### [request](/docs/swml/reference/messaging/request) Call an external API while handling the message — for example, to look up a customer record before replying.