> For a complete index of all SignalWire documentation pages, fetch https://signalwire.com/docs/llms.txt

# SWML inbound message webhook

POST 

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.

Reference: https://signalwire.com/docs/apis/rest/swml-webhook/webhooks/inbound-message-webhook

## OpenAPI 3.1 Webhook Specification

```yaml
openapi: 3.1.0
info:
  title: signalwire-rest
  version: 1.0.0
paths: {}
webhooks:
  inbound-message-webhook:
    post:
      operationId: inbound-message-webhook
      summary: SWML inbound message webhook
      description: >-
        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.
      responses:
        '200':
          description: Webhook received successfully
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                message:
                  $ref: >-
                    #/components/schemas/WebhooksInboundMessageWebhookPayloadContentApplicationJsonSchemaMessage
                  description: The inbound message that triggered this fetch.
                vars:
                  $ref: >-
                    #/components/schemas/WebhooksInboundMessageWebhookPayloadContentApplicationJsonSchemaVars
                  description: >-
                    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:
                  $ref: >-
                    #/components/schemas/WebhooksInboundMessageWebhookPayloadContentApplicationJsonSchemaParams
                  description: >-
                    Parameters passed via a SWML messaging `transfer` step. An
                    empty object on the initial document fetch.
              required:
                - message
                - params
components:
  schemas:
    WebhooksInboundMessageWebhookPayloadContentApplicationJsonSchemaMessageDirection:
      type: string
      enum:
        - inbound
      description: >-
        Direction of the message. Always `inbound` for messages handled by an
        SWML messaging script.
      title: >-
        WebhooksInboundMessageWebhookPayloadContentApplicationJsonSchemaMessageDirection
    WebhooksInboundMessageWebhookPayloadContentApplicationJsonSchemaMessageType:
      type: string
      enum:
        - sms
        - mms
      description: The kind of message.
      title: >-
        WebhooksInboundMessageWebhookPayloadContentApplicationJsonSchemaMessageType
    WebhooksInboundMessageWebhookPayloadContentApplicationJsonSchemaMessageMediaItems:
      type: object
      properties:
        url:
          type: string
          format: uri
          description: URL to download the media file.
        content_type:
          type: string
          description: MIME type of the media file.
        size:
          type: integer
          description: File size in bytes.
      required:
        - url
        - content_type
        - size
      description: A single MMS media attachment included on an inbound message.
      title: >-
        WebhooksInboundMessageWebhookPayloadContentApplicationJsonSchemaMessageMediaItems
    WebhooksInboundMessageWebhookPayloadContentApplicationJsonSchemaMessage:
      type: object
      properties:
        message_id:
          type: string
          format: uuid
          description: Unique identifier for the inbound message.
        project_id:
          type: string
          format: uuid
          description: The Project ID this message belongs to.
        space_id:
          type: string
          format: uuid
          description: The Space ID this message belongs to.
        direction:
          $ref: >-
            #/components/schemas/WebhooksInboundMessageWebhookPayloadContentApplicationJsonSchemaMessageDirection
          description: >-
            Direction of the message. Always `inbound` for messages handled by
            an SWML messaging script.
        type:
          $ref: >-
            #/components/schemas/WebhooksInboundMessageWebhookPayloadContentApplicationJsonSchemaMessageType
          description: The kind of message.
        from:
          type: string
          description: Phone number that sent the message.
        to:
          type: string
          description: Phone number that received the message.
        body:
          type:
            - string
            - 'null'
          description: >-
            The text content of the message. Null on media-only MMS where the
            carrier did not include a text body.
        media:
          type: array
          items:
            $ref: >-
              #/components/schemas/WebhooksInboundMessageWebhookPayloadContentApplicationJsonSchemaMessageMediaItems
          description: MMS media attachments. Empty when the message has no attachments.
        segments:
          type: integer
          description: Number of SMS segments the message body was split into.
        timestamp:
          type: string
          format: date-time
          description: >-
            Timestamp in UTC (ISO 8601, seconds precision) of when the message
            was received.
      required:
        - message_id
        - project_id
        - space_id
        - direction
        - type
        - from
        - to
        - body
        - media
        - segments
        - timestamp
      description: The inbound message that triggered this fetch.
      title: WebhooksInboundMessageWebhookPayloadContentApplicationJsonSchemaMessage
    WebhooksInboundMessageWebhookPayloadContentApplicationJsonSchemaVars:
      type: object
      properties: {}
      description: >-
        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`.
      title: WebhooksInboundMessageWebhookPayloadContentApplicationJsonSchemaVars
    WebhooksInboundMessageWebhookPayloadContentApplicationJsonSchemaParams:
      type: object
      properties: {}
      description: >-
        Parameters passed via a SWML messaging `transfer` step. An empty object
        on the initial document fetch.
      title: WebhooksInboundMessageWebhookPayloadContentApplicationJsonSchemaParams

```