Inbound Messages (Relays)

To receive inbound SMS messages, you need a dedicated longcode (mobile number) purchased from Phonovation. Contact sales@phonovation.com to get one set up.

When a recipient replies to your dedicated longcode, the Phonovation gateway relays the inbound message to a URL you provide via HTTP POST.

Receiving opt-outs

Even without a dedicated longcode, all Phonovation customers can receive opt-out messages at their inbound relay URL. Opt-outs are always sent to the shared shortcode 50123 — when a recipient texts STOP or OPTOUT to 50123, the relay fires to your endpoint with SMS-To=50123. You do not need a longcode to handle opt-outs. See Opt-out payloads below.

Setup

To receive inbound messages, contact sales@phonovation.com to purchase a dedicated longcode. Once provisioned, provide your relay URL to support@phonovation.com. The endpoint must:

Accept HTTP POST requests
Return a 200 OK response

Relay parameters

Parameter	Example	Description
`SMS-Type`	`AuthCode`	Message type — see SMS-Type values below
`SMS-Content`	`Test reply`	Full message body
`SMS-Keyphrase`	`CONFIRM` or `*`	First word of the message, used for keyword routing. `*` means no specific keyword was matched
`SMS-Network`	`272/1`	Network code in MCC/MNC format — may be empty
`SMS-From`	`353871111111`	Sender’s mobile number (GSM format)
`SMS-To`	`353877777777`	The number the message was sent to (GSM format)
`SMS-NotifyId`	`order-001`	The `notifyId` from the original outbound message, if one was set — otherwise empty
`SMS-Verify`	`9db038748b3088971d913616c13e769b`	MD5 hash for payload verification — see below
`SMS-TimeStamp`	`2026-04-09 16:03:11`	Gateway receipt time (`yyyy-MM-dd HH:mm:ss`)
`SMS-AuthCode`	`AUTH:reply/1450707`	Legacy. Routing code used by older integrations — ignore in new builds
`SMS-GroupCode`	`AUTH:G353871234568/*`	Legacy. Group routing code used by older integrations — ignore in new builds

SMS-Type values

Value	Meaning
`AuthCode`	Standard inbound relay message
`Text`	Plain text message — seen in some legacy configurations

Example relay payload

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/*

URL-encode the POST body before sending. Some field values may contain characters that break unencoded requests.

Verifying the payload

The SMS-Verify field is an MD5 hash to confirm the relay genuinely came from Phonovation. The formula follows the same pattern as DLR verification. Contact support@phonovation.com for your specific verification key.

curl -X POST https://example.com/sms/inbound \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "SMS-From=353861234567&SMS-Content=Test%20reply&SMS-Verify=EXPECTED_MD5_HASH"

const crypto = require('crypto');

function verifyRelay({ from, content, clientSecret, verify }) {
  const expected = crypto
    .createHash('md5')
    .update(from + content + clientSecret)
    .digest('hex');
  return expected === verify;
}

import hashlib

def verify_relay(sms_from, content, client_secret, verify):
    expected = hashlib.md5(
        f"{sms_from}{content}{client_secret}".encode()
    ).hexdigest()
    return expected == verify

using System.Security.Cryptography;
using System.Text;

bool VerifyRelay(string smsFrom, string content, string clientSecret, string verify)
{
    var input = Encoding.UTF8.GetBytes(smsFrom + content + clientSecret);
    var hash = MD5.HashData(input);
    var expected = Convert.ToHexString(hash).ToLowerInvariant();
    return expected == verify;
}

import java.security.MessageDigest;
import java.util.HexFormat;

boolean verifyRelay(String smsFrom, String content, String clientSecret, String verify) throws Exception {
    MessageDigest md5 = MessageDigest.getInstance("MD5");
    byte[] hash = md5.digest((smsFrom + content + clientSecret).getBytes());
    String expected = HexFormat.of().formatHex(hash);
    return expected.equals(verify);
}

function verifyRelay($smsFrom, $content, $clientSecret, $verify) {
    $expected = md5($smsFrom . $content . $clientSecret);
    return $expected === $verify;
}

Correlating replies with notifyId

Inbound relay payloads include an SMS-NotifyId field. When the gateway can link the inbound reply to an outbound message that had a notifyId set, this field will be populated with that value. If no link can be made, it will be empty. For cases where SMS-NotifyId is empty, use SMS-From (the sender’s mobile number) to look up the record in your system. If you stored the notifyId alongside the phone number when you sent the original message, a single lookup gives you the full context. See notifyId for end-to-end flow examples showing outbound, webhook, DLR, and inbound reply all tied together.

Opt-out payloads

Opt-out messages arrive at your relay URL like any other inbound message. You can identify them by SMS-To=50123 — this is always the destination for opt-outs regardless of your longcode or sender ID.

Opt-out relay payload

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/*

When you receive a payload with SMS-To=50123, add SMS-From to your suppression list immediately and do not send further marketing messages to that number.

Keyword routing

The SMS-Keyphrase contains the first word of the inbound message. A value of * means the message did not match a specific keyword. Use the keyphrase to route messages to different handlers in your application:

curl -X POST https://example.com/sms/inbound \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "SMS-Keyphrase=CONFIRM&SMS-From=353861234567&SMS-Content=CONFIRM"

from flask import Flask, request

app = Flask(__name__)

@app.post("/sms/inbound")
def inbound():
    keyphrase = request.form.get("SMS-Keyphrase", "").upper()
    sender = request.form.get("SMS-From")
    content = request.form.get("SMS-Content")

    if keyphrase == "STOP":
        handle_opt_out(sender)
    elif keyphrase == "CONFIRM":
        handle_confirmation(sender)
    elif keyphrase == "CANCEL":
        handle_cancellation(sender)
    else:
        handle_general(sender, content)

    return "", 200

app.MapPost("/sms/inbound", async (HttpRequest request) =>
{
    var form = await request.ReadFormAsync();
    var keyphrase = form["SMS-Keyphrase"].ToString().ToUpperInvariant();
    var from = form["SMS-From"].ToString();
    var content = form["SMS-Content"].ToString();

    switch (keyphrase)
    {
        case "STOP":
            HandleOptOut(from);
            break;
        case "CONFIRM":
            HandleConfirmation(from);
            break;
        case "CANCEL":
            HandleCancellation(from);
            break;
        default:
            HandleGeneral(from, content);
            break;
    }

    return Results.Ok();
});

post("/sms/inbound", (req, res) -> {
    String keyphrase = req.queryParams("SMS-Keyphrase").toUpperCase();
    String from = req.queryParams("SMS-From");
    String content = req.queryParams("SMS-Content");

    switch (keyphrase) {
        case "STOP" -> handleOptOut(from);
        case "CONFIRM" -> handleConfirmation(from);
        case "CANCEL" -> handleCancellation(from);
        default -> handleGeneral(from, content);
    }

    res.status(200);
    return "";
});

$keyphrase = strtoupper($_POST['SMS-Keyphrase'] ?? '');
$from = $_POST['SMS-From'] ?? '';
$content = $_POST['SMS-Content'] ?? '';

switch ($keyphrase) {
    case 'STOP':
        handleOptOut($from);
        break;
    case 'CONFIRM':
        handleConfirmation($from);
        break;
    case 'CANCEL':
        handleCancellation($from);
        break;
    default:
        handleGeneral($from, $content);
}

http_response_code(200);

app.post('/sms/inbound', (req, res) => {
  const { 'SMS-Keyphrase': keyphrase, 'SMS-From': from, 'SMS-Content': content } = req.body;

  switch (keyphrase.toUpperCase()) {
    case 'STOP':
      handleOptOut(from);
      break;
    case 'CONFIRM':
      handleConfirmation(from);
      break;
    case 'CANCEL':
      handleCancellation(from);
      break;
    default:
      handleGeneral(from, content);
  }

  res.sendStatus(200);
});

Network codes (SMS-Network)

When present, SMS-Network uses MCC/MNC format. For Irish numbers, MCC is always 272:

MNC	Carrier
`1`	Vodafone
`2`	O2
`3`	Meteor

This field may be empty depending on the network and message type.

Get started

Send messages

Receive events

Security and compliance

Tools

Receiving opt-outs

Setup

Relay parameters

SMS-Type values

Example relay payload

Verifying the payload

Correlating replies with notifyId

Opt-out payloads

Keyword routing

Network codes (SMS-Network)

​Receiving opt-outs

​Setup

​Relay parameters

​SMS-Type values

​Example relay payload

​Verifying the payload

​Correlating replies with notifyId

​Opt-out payloads

​Keyword routing

​Network codes (SMS-Network)

Receiving opt-outs

Setup

Relay parameters

SMS-Type values

Example relay payload

Verifying the payload

Correlating replies with notifyId

Opt-out payloads

Keyword routing

Network codes (SMS-Network)