To receive inbound SMS messages, you need a dedicated longcode (mobile number) purchased from Phonovation. Contact sales@phonovation.com to get one set up. 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
- Support up to TLS 1.2
- 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:G353870934726/* | 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=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/*
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.
const crypto = require('crypto');
function verifyRelay({ from, content, password, verify }) {
const expected = crypto
.createHash('md5')
.update(from + content + password)
.digest('hex');
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.
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/*
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:
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 |
