---
title: "SWML inbound message webhook"
method: POST
path: "inboundMessageWebhook"
tags: ["SWML Webhook"]
---

# SWML inbound message webhook

`POST inboundMessageWebhook` (webhook)

Payload sent by SignalWire to a SWML messaging webhook URL when an inbound SMS or MMS message arrives on a phone number configured with a SWML message handler. The same payload shape is also used when the SWML messaging `transfer` method targets an external URL — in that case, `params` carries the values supplied to the `transfer` step and `vars` carries the propagated runtime variables from the originating document.

The webhook URL is expected to respond with the SWML document to execute for the inbound message.

## Payload

- object — Payload sent by SignalWire to a SWML messaging webhook URL when an inbound SMS or MMS message arrives on a phone number configured with a SWML message handler. The same payload shape is also used when the SWML messaging `transfer` method targets an external URL — in that case, `params` carries the values supplied to the `transfer` step and `vars` carries the propagated runtime variables from the originating document. The webhook URL is expected to respond with the SWML document to execute for the inbound message.
  - `message` object, required — The inbound message that triggered this fetch.
    - `message_id` string, uuid, required — Unique identifier for the inbound message.
    - `project_id` string, uuid, required — The Project ID this message belongs to.
    - `space_id` string, uuid, required — The Space ID this message belongs to.
    - `direction` 'inbound', required — Direction of the message. Always `inbound` for messages handled by an SWML messaging script.
    - `type` 'sms' | 'mms', required — The kind of message.
    - `from` string, required — Phone number that sent the message.
    - `to` string, required — Phone number that received the message.
    - `body` string, nullable, required — The text content of the message. Null on media-only MMS where the carrier did not include a text body.
    - `media` object[], required — MMS media attachments. Empty when the message has no attachments.
      - `url` string, uri, required — URL to download the media file.
      - `content_type` string, required — MIME type of the media file.
      - `size` integer, required — File size in bytes.
    - `segments` integer, required — Number of SMS segments the message body was split into.
    - `timestamp` string, date-time, required — Timestamp in UTC (ISO 8601, seconds precision) of when the message was received.
  - `vars` object — Script-scope variables propagated from the SWML document that issued a `transfer` step. Absent on the initial inbound-message fetch; present (possibly empty) on fetches driven by a `transfer` step inside a full-mode SWML document. Common keys include `request_result`, `request_response`, `request_response_code`, `request_response_body`, `reply_result`, and `reply_message_id`.
  - `params` object, required — Parameters passed via a SWML messaging `transfer` step. An empty object on the initial document fetch.

## Acknowledgement `200`

Webhook received

---

[API](https://skmtc.net/signalwire/apis/signalwire-rest-api.md) · [All operations](https://skmtc.net/signalwire/apis/signalwire-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/signalwire/signalwire-rest-api/versions/05c5164b85c7/schema)