Skip to main content

Check WhatsApp Message Status

Query the delivery status of a previously sent WhatsApp message by its Octopods message ID.

Written by Tarek Khalil

Endpoint

GET https://app.octopods.io/api/v1/whatsapp/messages/:message_id

:message_id is the message_id returned when the message was created. You can also use the message_status_url returned in the send response — it already points at the right endpoint for that specific message.

Authentication

Include your WhatsApp Business API Key in the request header:

X-Octopods-Auth: YOUR_WHATSAPP_BUSINESS_API_KEY

The same key that sent the message must be used to query its status.

Example request

GET https://app.octopods.io/api/v1/whatsapp/messages/3851828
X-Octopods-Auth: YOUR_WHATSAPP_BUSINESS_API_KEY

Success response

On success the API returns HTTP 200 OK with a JSON body:

{
  "request_id": "b14f0e5a-3f3c-4e9c-b1d1-6d19f0c4a721",
  "message_id": 3851828,
  "status": "delivered",
  "phone_number": "+15551234567",
  "channel_message_id": "wamid.HBgNNTUxMTk3MjI3ODA2MhUCABEYE...",
  "sent_at": "2026-04-24T10:23:45Z",
  "delivered_at": "2026-04-24T10:23:48Z",
  "read_at": null,
  "failure_reason": null
}

The exact set of timestamp fields depends on how far the message has progressed. Fields for stages the message hasn’t reached yet are null.

Status values

Status

Meaning

sent

Octopods handed the message to WhatsApp and received an acknowledgement. This is the earliest confirmed state.

delivered

WhatsApp confirmed the message reached the recipient’s device.

read

The recipient opened the message. Only reported if the recipient has read receipts enabled.

failed

The message was rejected. failure_reason describes why.

A “sent” status means Octopods successfully handed the message to WhatsApp — it does not by itself guarantee the recipient received it. Wait for delivered to confirm delivery to the device.

Common failure reasons

When status is failed, failure_reason typically contains one of:

  • Recipient’s phone number is not a valid WhatsApp user.

  • The 24-hour messaging window has closed (for non-template sends).

  • The template is not approved for the recipient’s country.

  • The template was deactivated after the send was queued.

  • The recipient blocked your WhatsApp number.

Error response

If the request is malformed or the message cannot be found, the API returns HTTP 400 Bad Request:

{
  "request_id": "b14f0e5a-3f3c-4e9c-b1d1-6d19f0c4a721",
  "error_code": 1,
  "error": "You must supply message_id in your request payload."
}

Error codes

Code

Name

When it happens

1

ARGUMENT_MISSING

:message_id was omitted from the URL.

6

DEPRECATED_API_KEY

The API key has been rotated or revoked. Fetch the current key from Octopods.

Polling tips

  • Wait at least a few seconds before polling. Status updates from WhatsApp arrive asynchronously, so an immediate poll after send typically returns sent.

  • Back off after delivered. Once a message is delivered, read is the only remaining status — and that only happens if the recipient has read receipts on. Excessive polling for read confirmation wastes your rate-limit budget.

  • Mind the rate limit. Status queries share the same per-API-key rate limit as sends. On a 429, pause until the returned retry timestamp before resuming.

What’s next

Did this answer your question?