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

# Incoming SMS

> Vodafone sends this inbound SMS relay payload to your configured
callback URL via HTTP POST.

In the API playground, replace `callbackUrl` with the URL for your test
endpoint. The example default is `https://callback.yourcompany.com`.

Your endpoint must accept `application/x-www-form-urlencoded` POST
requests and return `200 OK` after accepting the payload.




## OpenAPI

````yaml openapi/incoming-sms-callback.yaml POST /
openapi: 3.1.0
info:
  title: Vodafone Bulk Text Incoming SMS Callback
  version: 1.0.0
  description: |
    Use this operation to test the Incoming SMS payload against your own
    callback URL. Vodafone sends this payload to the exact callback endpoint
    configured on your account.
  contact:
    name: Vodafone Bulk Text Support
    email: bulktext.ie@vodafone.com
servers:
  - url: '{callbackUrl}'
    description: Your Incoming SMS callback URL
    variables:
      callbackUrl:
        default: https://callback.yourcompany.com
        description: >
          Enter the full callback URL Vodafone should post Incoming SMS relays
          to, for example `https://callback.yourcompany.com`.
security: []
tags:
  - name: Incoming SMS
    description: Inbound SMS replies, keyword messages, and opt-out messages.
paths:
  /:
    post:
      tags:
        - Incoming SMS
      summary: Receive incoming SMS messages
      description: |
        Vodafone sends this inbound SMS relay payload to your configured
        callback URL via HTTP POST.

        In the API playground, replace `callbackUrl` with the URL for your test
        endpoint. The example default is `https://callback.yourcompany.com`.

        Your endpoint must accept `application/x-www-form-urlencoded` POST
        requests and return `200 OK` after accepting the payload.
      operationId: testIncomingSmsCallback
      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: '353896073106'
                  SMS-To: '353870934726'
                  SMS-NotifyId: ''
                  SMS-Verify: 5b49b61a65520226f3da14764f7c182b
                  SMS-TimeStamp: '2026-04-09 16:03:11'
                  SMS-AuthCode: AUTH:reply/1450707
                  SMS-GroupCode: AUTH:G353870934726/*
              optOut:
                summary: Opt-out message
                value:
                  SMS-Type: AuthCode
                  SMS-Content: Optout
                  SMS-Keyphrase: '*'
                  SMS-Network: ''
                  SMS-From: '353896073106'
                  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 callback endpoint accepted the inbound SMS payload.
      security: []
components:
  schemas:
    InboundMessageWebhook:
      type: object
      description: >
        Inbound SMS relay payload sent by Vodafone to a customer callback URL
        for replies, keyword messages, and opt-outs.
      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. `AuthCode` is the standard inbound relay type; `Text`
            may appear in some legacy configurations.
        SMS-Content:
          type: string
          description: Full inbound SMS message body.
          examples:
            - Test reply
            - Optout
        SMS-Keyphrase:
          type: string
          description: >
            First word of the message, used for keyword routing. `*` means no
            specific keyword was matched.
          examples:
            - '*'
            - CONFIRM
            - STOP
        SMS-Network:
          type: string
          description: >
            Network code in MCC/MNC format. For Irish numbers, MCC is `272`.
            This field may be empty depending on network and message type.
          examples:
            - 272/1
            - ''
        SMS-From:
          type: string
          description: Sender mobile number in GSM format.
          examples:
            - '353896073106'
        SMS-To:
          type: string
          description: >
            Number the message was sent to. Opt-out payloads use shared
            shortcode `50123`.
          examples:
            - '353870934726'
            - '50123'
        SMS-NotifyId:
          type: string
          description: >
            `notifyId` from the original outbound message where Vodafone can
            correlate the reply; otherwise an empty string.
          examples:
            - order-001
            - ''
        SMS-Verify:
          type: string
          description: MD5 verification hash for confirming the relay came from Vodafone.
          examples:
            - 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`.
          examples:
            - '2026-04-09 16:03:11'
        SMS-AuthCode:
          type: string
          description: >-
            Legacy routing code used by older integrations. Ignore in new
            builds.
          examples:
            - AUTH:reply/1450707
        SMS-GroupCode:
          type: string
          description: >-
            Legacy group routing code used by older integrations. Ignore in new
            builds.
          examples:
            - AUTH:G353870934726/*

````