> ## Documentation Index
> Fetch the complete documentation index at: https://developers.phonovation.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Receive inbound SMS messages

> Phonovation sends this webhook when it receives an inbound SMS for your account.

Inbound SMS webhooks work regardless of send API version, including the OAuth API and legacy APIs.

Set `callbackHost` to your callback hostname before sending a test request. Do not include `https://`.


Inbound SMS webhooks send customer replies, keyword messages, and opt-outs to your endpoint.

<Note>
  Inbound SMS webhooks work regardless of send API version. You can receive replies and opt-outs for messages sent through the OAuth API or legacy APIs.
</Note>

```mermaid title="Inbound SMS flow" theme={"dark"}
sequenceDiagram
  participant Customer as Mobile user
  participant Network as Mobile network
  participant Gateway as Phonovation gateway
  participant Endpoint as Your webhook endpoint

  Customer->>Network: Send SMS
  Network->>Gateway: Route inbound message
  Gateway->>Endpoint: Inbound SMS webhook
  Endpoint-->>Gateway: 200 OK
```

## Quick facts

| Item                  | Detail                                                     |
| --------------------- | ---------------------------------------------------------- |
| **Format**            | `application/x-www-form-urlencoded`                        |
| **Opt-out shortcode** | `50123`                                                    |
| **Correlation**       | Use `SMS-NotifyId` when present; otherwise use `SMS-From`  |
| **Verification**      | `SMS-Verify = MD5(SMS-From + SMS-Content + client secret)` |


## OpenAPI

````yaml openapi/inbound-message-webhook.yaml POST /
openapi: 3.1.2
info:
  title: Phonovation SMS Inbound Message Webhook
  version: 1.0.0
  description: Inbound SMS webhook payload sent by Phonovation to your callback URL.
  contact:
    name: Phonovation Support
    email: support@phonovation.com
servers:
  - url: https://{callbackHost}
    description: Customer-provided callback server
    variables:
      callbackHost:
        default: callback.yourcompany.com
        description: Callback hostname only. Do not include `https://` or a trailing path.
security: []
tags:
  - name: Incoming SMS
    description: Inbound SMS webhook payloads sent by Phonovation.
paths:
  /:
    post:
      tags:
        - Incoming SMS
      summary: Receive inbound SMS messages
      description: >
        Phonovation sends this webhook when it receives an inbound SMS for your
        account.


        Inbound SMS webhooks work regardless of send API version, including the
        OAuth API and legacy APIs.


        Set `callbackHost` to your callback hostname before sending a test
        request. Do not include `https://`.
      operationId: receiveInboundMessage
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/InboundMessageWebhook'
            examples:
              inboundReply:
                summary: Customer reply
                value:
                  SMS-Type: AuthCode
                  SMS-Content: Test reply
                  SMS-Keyphrase: '*'
                  SMS-Network: ''
                  SMS-From: '353861234567'
                  SMS-To: '353871234568'
                  SMS-NotifyId: ''
                  SMS-Verify: 5b49b61a65520226f3da14764f7c182b
                  SMS-TimeStamp: '2026-04-09 16:03:11'
                  SMS-AuthCode: AUTH:reply/1450707
                  SMS-GroupCode: AUTH:G353871234568/*
              optOut:
                summary: Opt-out message
                value:
                  SMS-Type: AuthCode
                  SMS-Content: Optout
                  SMS-Keyphrase: '*'
                  SMS-Network: ''
                  SMS-From: '353861234567'
                  SMS-To: '50123'
                  SMS-NotifyId: ''
                  SMS-Verify: 5b49b61a65520226f3da14764f7c182b
                  SMS-TimeStamp: '2026-04-09 16:31:52'
                  SMS-AuthCode: AUTH:reply/177157
                  SMS-GroupCode: AUTH:G50123/*
      responses:
        '200':
          description: Your webhook endpoint accepted the inbound SMS payload.
      security: []
components:
  schemas:
    InboundMessageWebhook:
      type: object
      required:
        - SMS-Type
        - SMS-Content
        - SMS-Keyphrase
        - SMS-From
        - SMS-To
        - SMS-NotifyId
        - SMS-Verify
        - SMS-TimeStamp
      properties:
        SMS-Type:
          type: string
          enum:
            - AuthCode
            - Text
          description: Message type.
          default: AuthCode
        SMS-Content:
          type: string
          description: Full inbound SMS message body.
          default: Test reply
        SMS-Keyphrase:
          type: string
          description: First word of the message, used for keyword routing.
          default: '*'
        SMS-Network:
          type: string
          description: Network code in MCC/MNC format. This field may be empty.
          default: ''
        SMS-From:
          type: string
          description: Sender mobile number in Irish international format.
          default: '353861234567'
        SMS-To:
          type: string
          description: >-
            Number the message was sent to. Opt-out payloads use shared
            shortcode `50123`.
          default: '353871234568'
        SMS-NotifyId:
          type: string
          description: The `notifyId` from the original outbound message when available.
          default: ''
        SMS-Verify:
          type: string
          description: >-
            MD5 verification hash built from `SMS-From + SMS-Content + your
            Client Secret`.
          default: 5b49b61a65520226f3da14764f7c182b
        SMS-TimeStamp:
          type: string
          pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2} [0-9]{2}:[0-9]{2}:[0-9]{2}$
          description: Gateway receipt time, formatted as `yyyy-MM-dd HH:mm:ss`.
          default: '2026-04-09 16:03:11'
        SMS-AuthCode:
          type: string
          description: >-
            Legacy routing code used by older integrations. Ignore in new
            builds.
          default: AUTH:reply/1450707
        SMS-GroupCode:
          type: string
          description: >-
            Legacy group routing code used by older integrations. Ignore in new
            builds.
          default: AUTH:G353871234568/*

````