Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.belio.co.ke/llms.txt

Use this file to discover all available pages before exploring further.

Delivery receipts provide a mechanism to track the status of messages sent through the API. When you send a WhatsApp message with a receiptRequest, the system will send a delivery receipt to your specified callback URL once the message reaches its final state. This allows you to monitor the delivery status of your messages in real-time.
Delivery receipts are sent to the callback URL specified in the receiptRequest object of the message request. If you do not include a receiptRequest, no delivery receipt will be sent.
Ensure that the callback URL is publicly accessible and can handle incoming HTTP POST requests to receive the delivery receipts.

​
Delivery Receipt Format

{
  "type": "WhatsAppDeliveryReceipt",
  "wamId": "wamid.HBgLMjU0NzAwMTExMjEzFQIAERgSM...",
  "phone": "254700111213",
  "timestamp": "2026-04-29T14:32:00+03:00",
  "deliveryStatus": "Delivered",
  "conversationId": "conv-abc123",
  "pricingCategory": "Marketing",
  "reason": "Internal error",
  "reasonCode": "99"
}
FieldTypeAlways presentDescription
typestringYesAlways WhatsAppDeliveryReceipt
wamIdstringYesWhatsApp message ID assigned by Meta’s servers
phonestringYesRecipient phone number in E.164 format
timestampstringYesISO 8601 datetime of the status event
deliveryStatusstringYesCurrent delivery state.
conversationIdstringNoMeta conversation ID; present once a conversation window is opened
pricingCategorystringNoPricing category applied to this message.
reasonstringNoHuman-readable failure reason; present when deliveryStatus is Failed
reasonCodestringNoMachine-readable error code; present when deliveryStatus is Failed

​
Delivery Statuses

ValueWhatsApp UI equivalentDescription
WaitingClockMessage is queued and waiting to be sent to the recipient’s device (default initial state)
SentSingle checkmarkMessage was sent from WhatsApp servers to the recipient
DeliveredTwo checkmarksMessage was successfully delivered to the recipient’s device
ReadTwo blue checkmarksMessage was displayed in an open chat thread on the recipient’s device
FailedRed error triangleMessage could not be delivered to the recipient’s device
PlayedBlue microphoneVoice message was played for the first time on the recipient’s device

​
Pricing Categories

WhatsApp Business charges per conversation, categorized by the nature of the message. The pricingCategory field in delivery receipts and the units map in the send response both use these values.
ValueDescription
AuthenticationSent as part of an authentication flow (e.g. OTP). Authentication rate applies
AuthenticationInternationalAuthentication message sent to an international (non-domestic) number. International authentication rate applies
MarketingPromotional or marketing content. Marketing rate applies
MarketingLiteSent via the Marketing Messages API (lighter marketing tier). Marketing Messages API rate applies
ReferralConversationConversation initiated through a free entry point (e.g. Click-to-WhatsApp ad). No charge applies
ServiceSent in response to a user-initiated message within the 24-hour service window. Service rate applies
UtilityTransactional or account-related notifications (e.g. order confirmations). Utility rate applies

​
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.