Skip to main content
Delivery receipts are callback events for WhatsApp messages sent through the API. When a request includes receiptRequest, the platform sends HTTP POST requests to the configured callbackUrl with Content-Type: application/json.
The callback body is a JSON object with a type discriminator. WhatsApp outbound status callbacks use WhatsAppOutboundMessageReceipt.
Ensure that the callback URL is publicly accessible and can handle unauthenticated HTTP POST requests.

​
WhatsAppOutboundMessageReceipt

Sent when the delivery status of a message you sent to a user changes. A single sent message can produce multiple callbacks in sequence: Sent, Delivered, then Read or Played for voice messages. A failed message produces a Failed callback.

​
Example: Delivered

{
  "type": "WhatsAppOutboundMessageReceipt",
  "wabaId": "102290129340398",
  "phoneNumberId": "106540352242922",
  "wamId": "wamid.HBgLMTY1MDM4Nzk0MzkVAgASGBQzQUFERjg0NDEzNDdFODU3MUMxMAA=",
  "correlator": "8f24c8c6-7e7c-4b6f-a622-d4a25f91d3c1",
  "sender": "15550783881",
  "recipient": "254700111213",
  "timestamp": "2025-05-11T10:31:13Z",
  "deliveryStatus": "Delivered",
  "conversationId": "8f842dbba350821654c9dfed31f5635c",
  "pricing": {
    "type": "Regular",
    "category": "Marketing"
  }
}

​
Example: Failed

{
  "type": "WhatsAppOutboundMessageReceipt",
  "wabaId": "102290129340398",
  "phoneNumberId": "106540352242922",
  "wamId": "wamid.HBgLMTY1MDM4Nzk0MzkVAgARGBI0QUQ2MjA4NEYyRkExNjMyREUA",
  "correlator": "8f24c8c6-7e7c-4b6f-a622-d4a25f91d3c1",
  "sender": "15550783881",
  "recipient": "254700111213",
  "timestamp": "2025-05-11T10:35:00Z",
  "deliveryStatus": "Failed",
  "reason": "This message was not delivered to maintain healthy ecosystem engagement.",
  "reasonCode": "131049"
}

​
Fields

FieldTypeAlways presentDescription
typestringYesAlways WhatsAppOutboundMessageReceipt
wabaIdstringYesYour WhatsApp Business Account ID.
phoneNumberIdstringYesWhatsApp Business Account Phone Number ID through which the message was sent.
wamIdstringNoWhatsApp message ID assigned by Meta. May be omitted for Failed when termination to Meta was not successful.
correlatorstringYesUnique ID that correlates with your original message request.
senderstringYesSender phone number (Business).
recipientstringYesRecipient phone number (User).
timestampstringYesISO 8601 timestamp for when the status event occurred, in UTC.
deliveryStatusstringYesCurrent delivery state. See Delivery Status values.
conversationIdstringNoWhatsApp conversation window ID. Present with Sent and with one of either Delivered or Read. Omitted unless the conversation used a free entry point.
pricingobjectNoPricing type and category. Present on Sent and on one of either Delivered or Read, not both, and never on Failed.
reasonstringNoHuman-readable error description. Only present when deliveryStatus is Failed.
reasonCodestringNoNumeric error code as a string. Only present when deliveryStatus is Failed.

​
Delivery Status Values

ValueWhatsApp UIMeaning
WaitingClock iconMessage is being processed and has not yet been sent to the recipient’s device
SentSingle checkmarkMessage sent from Meta’s servers to the recipient
DeliveredTwo checkmarksMessage delivered to the recipient’s device
ReadTwo blue checkmarksMessage displayed in an open chat on the recipient’s device
PlayedBlue microphoneVoice message played by the recipient
FailedRed error triangleMessage could not be sent or delivered
Uncertain-Delivery outcome is unknown; the message may or may not have been delivered

​
Pricing Type Values

ValueDescription
RegularMessage is billable.
FreeCustomerServiceMessage is free because it was either a utility template message or non-template message sent within a customer service window.
FreeEntryPointMessage is free because it was sent within an open free entry point window.

​
Pricing Category Values

ValueDescription
AuthenticationAuthentication message
AuthenticationInternationalAuthentication message billed at international rate
MarketingMarketing message
MarketingLiteMarketing Messages API message
ReferralConversationFree entry point conversation
ServiceService message
UtilityUtility message

​
Callback Sequence

A successfully delivered message produces sequential WhatsAppOutboundMessageReceipt callbacks: 
POST /your-callback  ->  deliveryStatus: "Sent"       (pricing present)
POST /your-callback  ->  deliveryStatus: "Delivered"  (pricing may be present)
POST /your-callback  ->  deliveryStatus: "Read"       (pricing present if not already sent with "Delivered")
A failed message produces a single callback: 
POST /your-callback  ->  deliveryStatus: "Failed"     (reason and reasonCode present)
If a message is delivered and read at the same time, for example when the recipient has the chat open, the Delivered callback is skipped and only Read is sent.

​
Receipt Request

An optional object on send requests that enables delivery status callbacks. It must be included in the WhatsApp message request body when sending a message to receive delivery receipts for that message. 
{
  "correlator": "12345678-1234-5678-1234-567812345678",
  "callbackUrl": "https://acme.org/whatsapp/delivery-reports"
}
FieldTypeConstraints
correlatorstringNon-empty, maximum 100 characters. Used to correlate callbacks to the originating request. Recommended: UUID.
callbackUrlstringValid https:// or http:// URL. The endpoint must not require authentication.
When provided, both fields are required. An invalid receiptRequest causes the entire request to be rejected with 400 Bad Request before any messages are dispatched.