notifyId is a string you define and attach to each recipient when sending an SMS. Phonovation echoes it back in every outbound event for that recipient — webhooks and DLRs — so you can match each callback to the right record in your own system without relying on phone numbers.
Where it appears
| System | Field | Notes |
|---|
| Outbound send | recipientInfo[].notifyId | You set it here — per recipient |
| Webhook | NotifyId | Echoed back per recipient |
| DLR | SMS-NotifyId | Echoed back per recipient |
| Inbound relay | SMS-NotifyId | Populated when the gateway links the reply to an outbound with a notifyId set — otherwise empty |
Rules
- User-defined — you choose the value. Use whatever makes sense for your system: a database ID, an order number, a UUID.
- Per recipient — set independently on each entry in
recipientInfo, so different recipients in the same campaign can carry different identifiers.
- Optional — if omitted, webhook and DLR callbacks will carry an empty
NotifyId/SMS-NotifyId. You can still receive callbacks; you just won’t be able to match them automatically.
- String only — any string up to a reasonable length. There is no enforced format.
Setting a notifyId
{
"text": "Your appointment is confirmed for tomorrow at 10am.",
"from": "Clinic",
"recipientInfo": [
{ "msisdn": "353861234567", "notifyId": "appt-8821" },
{ "msisdn": "353871234567", "notifyId": "appt-8822" }
]
}
notifyId through every subsequent callback.
Use cases
Order and transaction tracking
Attach an order ID so every delivery callback maps directly to a record in your database — no phone number lookups needed.
{ "msisdn": "353861234567", "notifyId": "order-10045" }
SMS-NotifyId=order-10045, you update that order row to sms_delivered = true.
Multi-step user journeys
Use the same identifier across the full send → deliver → reply flow to keep a user’s journey stitched together in your logs.
{ "msisdn": "353871234567", "notifyId": "user-7712-step-2" }
Audit trails and support
Store the notifyId alongside the send record. If a customer contacts support claiming they never received a message, you can pull the DLR and webhook logs for that ID immediately.
Batch reconciliation
After a large campaign send, use notifyId values to reconcile delivery status back to your CRM or data warehouse — matching each row by ID rather than by phone number.
Full flow example — appointment reminder
This example traces a single message from send through to a reply, showing where notifyId appears at each step.
Scenario: A clinic sends an appointment reminder. The patient can reply CONFIRM or CANCEL.
1. Send the message
POST /api/v2/Campaign
{
"text": "Hi Sarah, your appointment is tomorrow at 10am. Reply CONFIRM or CANCEL.",
"from": "Clinic",
"recipientInfo": [
{ "msisdn": "353861234567", "notifyId": "appt-8821" }
]
}
2. Webhook fires — message accepted
Phonovation immediately sends a webhook to your endpoint:
{
"Status": "MESSAGE_SUCCESS",
"FinishedAt": "2026-04-09T09:01:12.000Z",
"Message": "Your message has been queued.",
"NotifyId": "appt-8821"
}
8821 as sms_queued.
3. DLR fires — message delivered to handset
Minutes later, once the network confirms delivery:
SMS-Type=Notification
SMS-NotifyId=appt-8821
SMS-Success=True
SMS-To=353861234567
SMS-From=Clinic
SMS-TotalToSend=1
SMS-TotalSent=1
SMS-TotalFailed=0
SMS-TimeStamp=2026-04-09 09:01:45
8821 as sms_delivered.
4. Patient replies — inbound relay fires
Sarah texts back CONFIRM. Your inbound relay receives:
SMS-Type=Text
SMS-Content=CONFIRM
SMS-Keyphrase=CONFIRM
SMS-From=353861234567
SMS-To=Clinic
SMS-TimeStamp=2026-04-09 09:03:11
SMS-NotifyId. When the gateway can link the reply to the original outbound message, this will be populated with appt-8821 — no phone number lookup needed. If it’s empty, fall back to looking up SMS-From (353861234567) in your system to find the associated record.
Full state after each step
| Step | Event | notifyId visible | Appointment 8821 status |
|---|
| 1 | Send API call | You set appt-8821 | sms_pending |
| 2 | Webhook | NotifyId: appt-8821 | sms_queued |
| 3 | DLR | SMS-NotifyId: appt-8821 | sms_delivered |
| 4 | Inbound reply | SMS-NotifyId: appt-8821 (or use SMS-From fallback) | confirmed |
Full flow example — e-commerce order notification
Scenario: An online shop notifies a customer their order has shipped. If the customer replies, the shop wants to know which order they’re referring to.
1. Send the message
{
"text": "Your order #10045 has shipped! Track it at: example.com/track/10045",
"from": "ShopName",
"recipientInfo": [
{ "msisdn": "353871234567", "notifyId": "order-10045" }
]
}
2. Webhook — accepted
{
"Status": "MESSAGE_SUCCESS",
"FinishedAt": "2026-04-09T11:14:00.000Z",
"Message": "Your message has been queued.",
"NotifyId": "order-10045"
}
3. DLR — delivered
SMS-NotifyId=order-10045
SMS-Success=True
SMS-To=353871234567
SMS-TimeStamp=2026-04-09 11:14:22
orders table: sms_delivered_at = 2026-04-09 11:14:22 where id = 10045.
4. Customer replies
SMS-Type=AuthCode
SMS-Content=Where is my order?
SMS-Keyphrase=*
SMS-From=353871234567
SMS-To=ShopName
SMS-NotifyId=order-10045
SMS-NotifyId is populated directly — route straight to your support queue with the order context pre-filled. No phone number lookup needed.
Tips
- Keep
notifyId values unique per send where possible. Reusing the same ID across multiple sends makes it harder to distinguish callbacks.
- For inbound replies, check
SMS-NotifyId first. If it’s populated, you have a direct link to the original send. If it’s empty, fall back to looking up SMS-From in your records — so it’s worth storing notifyId alongside the phone number at send time as a safety net.
notifyId has no meaning to the Phonovation network — it is purely for your use. The gateway stores and echoes it; nothing else.
Last modified on April 9, 2026
