Skip to main content

Get WhatsApp message status

GET 
/api/partner-gateway/v1/whatsapp/messages/:messageId

Returns the current delivery status of a WhatsApp Business message identified by its messageId. Use this endpoint to track the full lifecycle of a WhatsApp message after it has been sent, including whether the recipient has read it. The messageId is the identifier returned in the response when you originally sent the message through the WhatsApp send endpoint. Store this identifier on your side at send time so you can poll for status later. WhatsApp delivery statuses and their meanings: DELIVERED - the WhatsApp servers confirmed that the message was delivered to the recipient device. This corresponds to double grey checkmarks in the WhatsApp UI. The recipient may not have opened the conversation yet. Reading is not a separate status: when the recipient opens the conversation — the double blue checkmarks in the WhatsApp UI — the readDate field is filled in while deliveryStatus stays DELIVERED. Read receipts are unique to WhatsApp among the supported channels, and recipients can switch them off in their privacy settings, in which case readDate stays null even after the message has been read. ERROR - the message could not be delivered. Common causes include: the recipient phone number is not registered on WhatsApp, the WhatsApp Business account has been restricted or banned, the message template was rejected, or the destination number is invalid. Check the response details for the specific error reason. CONVERSATION_CLOSED - the 24-hour customer-service window had closed, so a non-template message could not be sent. DISABLED - the recipient has WhatsApp messaging from businesses switched off. UNSUPPORTED - the recipient's number does not support the message that was sent. EXPIRED - the message was not delivered within the allowed time window and was discarded. This can happen when the recipient device is offline for an extended period. UNKNOWN - no status information is available from WhatsApp, which may indicate the message is still being processed or that the status callback was not received. WhatsApp has no separate in-flight status, so a message still awaiting its first receipt reads UNKNOWN. The Delivery Statuses table in the API overview lists the numeric code the delivery webhook sends for each of these statuses. WhatsApp-specific considerations: WhatsApp enforces a 24-hour customer service window. Outside this window, you can only send pre-approved template messages. Sending a non-template message outside the window will result in a CONVERSATION_CLOSED status. Also, WhatsApp has rate limits and quality ratings that can affect delivery. This endpoint is a per-channel shortcut over the same delivery-status source as GET /partner-gateway/v1/messages/status/{customerMessageId}?channel=WHATSAPP, which returns the identical payload and can also look up SMS — prefer it when you track more than one channel. Error responses: 401 is returned if the API key is missing or invalid. 404 is returned if the messageId does not exist or does not belong to the authenticated company.

Request​

Responses​

Message status retrieved successfully

Last updated on