Callback: Delivery Notification

OneXtel posts a Delivery Notification callback to your configured endpoint whenever the delivery status of an outbound WhatsApp message changes. The events originate from Meta’s webhooks and give you real-time visibility from submission through to outcome. Register your endpoint under Configuration → Add New Callback — see Callback configuration.

Status lifecycle

Every message moves through a defined set of statuses. Map all four in your system, or your delivery tracking will be wrong.

Status	Meaning	Triggered when
`sent`	Accepted by the WhatsApp server	The API request is validated and queued
`delivered`	Delivered to the recipient’s device	The device receives the message
`read`	Read by the recipient	The user opens the message, if read receipts are enabled
`failed`	Delivery failed	An error occurred — invalid number, throttling, ecosystem health, or template rejection

read only ever arrives if the recipient has read receipts enabled. Its absence is not evidence the message went unread, so never treat delivered without a subsequent read as a failure.

Payload format

{
  "waba_id": "entry.id",
  "custref1": "custref1",
  "custref2": "custref2",
  "custref3": "custref3",
  "custref4": "custref4",
  "custref5": "custref5",
  "entry": [
    {
      "id": "entry.id",
      "changes": [
        {
          "value": {
            "metadata": {
              "display_phone_number": "...",
              "phone_number_id": "..."
            },
            "statuses": [
              {
                "id": "message_id",
                "status": "sent/delivered/read/failed",
                "timestamp": "unix_timestamp",
                "errors": {
                  "code": "...",
                  "message": "...",
                  "title": "...",
                  "href": "...",
                  "error_data": {
                    "details": "..."
                  }
                },
                "conversation": {
                  "id": "...",
                  "origin": {
                    "type": "user_initiated/business_initiated/referral"
                  },
                  "expiration_timestamp": "..."
                },
                "pricing": {
                  "category": "utility/marketing/authentication",
                  "billable": true,
                  "pricing_model": "..."
                },
                "recipient_id": "customer_phone_number"
              }
            ],
            "messaging_product": "whatsapp"
          },
          "field": "messages"
        }
      ]
    }
  ]
}

Top-level fields

string

Unique identifier of the WhatsApp Business Account generating the event.

string

Custom key passed at the time of submission, echoed back unchanged.

string

Custom key passed at the time of submission.

string

Custom key passed at the time of submission.

string

Custom key passed at the time of submission.

string

Custom key passed at the time of submission.

array

Webhook event batches from WhatsApp.

Show entry properties

string

Unique ID of the WhatsApp Business Account.

array

Event changes related to messages and status updates.

Show changes properties

string

Type of webhook event — messages for delivery status.

object

Core object containing message delivery and metadata details.

The custref1–custref5 fields are the simplest way to correlate a callback with your own records — set them on the original send and they come straight back. See Send template messages.

Value fields

string

The business WhatsApp number visible to users.

string

Unique ID of the WhatsApp number.

string

Messaging platform identifier — whatsapp.

array

Message delivery status updates.

Status fields

string

Unique message ID. Match it against the ID returned when you sent the message.

string

Delivery status — sent, delivered, read, or failed.

string

Unix timestamp of the status event.

string

Recipient’s WhatsApp phone number.

Errors

The errors object is present only when status is failed.

string

Error code indicating the failure reason. See WhatsApp error codes for the values OneXtel has observed and whether each is worth retrying.

string

Description of the error.

string

Short error category or title.

string

URL for detailed error documentation.

string

Additional granular error detail.

Meta publishes the full list of failure reasons in its error codes reference.

Conversation

string

Unique conversation identifier.

string

How the conversation was initiated — user_initiated, business_initiated, or referral.

string

Timestamp when the conversation window expires.

expiration_timestamp is when the session window closes. After it passes you can no longer send free-form messages to that recipient — only templates. Track it if your application sends session messages. See Send session messages.

Pricing

string

Message category used for billing — utility, marketing, or authentication.

boolean

Whether the message is billable.

string

Pricing model used for billing.

The pricing object is what to reconcile billing against — category here is the category Meta actually charged at, which is not always the category you submitted the template under.

WhatsApp

RCS

SMS (India)

SMS (International)

OmniChannel

Verify

Callback: Delivery Notification

Status lifecycle

Payload format

Top-level fields

Value fields

Status fields

Errors

Conversation

Pricing

​Status lifecycle

​Payload format

​Top-level fields

​Value fields

​Status fields

​Errors

​Conversation

​Pricing

​Related

Status lifecycle

Payload format

Top-level fields

Value fields

Status fields

Errors

Conversation

Pricing

Related