Skip to main content

Checking Message Delivery Status

Poll the status of a proactive message you sent through the API so your system knows whether it reached the recipient.

Written by Tarek Khalil

When to check status

Sending a proactive message returns a message_id in the response. Delivery completes asynchronously — the provider takes a few seconds (sometimes longer) to confirm delivery. Use the status endpoints to:

  • Confirm a one-off send actually landed.

  • Poll in a background job after each send.

  • Report delivery state back to your own UI or audit log.

Endpoints

Two endpoints cover the public messaging APIs:

Channel

Endpoint

WhatsApp

GET /api/v1/whatsapp/messages/{message_id}

SMS

GET /api/v1/sms/messages/{message_id}

Authentication is the same API key you used to send the message — WhatsApp API key for WhatsApp, channel API key for SMS. Pass it in the X-Octopods-Auth header.

Request

curl "https://app.octopods.io/api/v1/whatsapp/messages/98765" \
  -H "X-Octopods-Auth: YOUR_WHATSAPP_API_KEY"

Response

HTTP 200 OK:

{
  "request_id": "abc123…",
  "message_id": 98765,
  "status": "DELIVERED",
  "status_message": "Your message has been delivered successfully.",
  "channel_message_id": "provider-id-here",
  "intercom_conversation_id": "",
  "intercom_conversation_part_id": "",
  "last_updated": "2026-04-24T12:34:56Z"
}

Field

Description

message_id

The Octopods ID for the message (matches the message_id returned when you sent it).

status

One of SENT, DELIVERED, READ, FAILED, DELETED, UNKNOWN.

status_message

A human-readable description of the current status.

channel_message_id

The provider’s own message ID.

intercom_conversation_id

ID of the CRM conversation that was opened, if any. Empty string when no conversation was opened.

intercom_conversation_part_id

ID of the specific conversation entry inside that thread, if any.

failure_reason

Present only when status is FAILED. Contains the provider error the message failed with.

last_updated

Timestamp of the most recent status change.

Status values

Status

Meaning

SENT

Octopods handed the message to the provider. No delivery confirmation yet.

DELIVERED

The provider confirmed delivery to the recipient’s device.

READ

The recipient opened the message (WhatsApp only).

FAILED

The send or delivery failed. The response includes a failure_reason.

DELETED

The recipient deleted the message after delivery.

UNKNOWN

Status is not yet available. Retry after a short delay.

A typical WhatsApp send moves SENT → DELIVERED → READ. A typical SMS send moves SENT → DELIVERED.

Error responses

HTTP status

When

How to handle

400

Missing message_id or invalid/deprecated API key.

Include the correct message ID and a current API key.

404 (as error_code: 2, “Resource Not Found”)

The message ID does not belong to this channel, or does not exist.

Verify you are using the same key that sent the message.

Polling guidance

  • Wait at least a few seconds after sending before polling — statuses are updated asynchronously.

  • If you get UNKNOWN, retry after 10–30 seconds rather than immediately.

  • Stop polling once status reaches DELIVERED, READ, FAILED, or DELETED — those are terminal for your polling loop.

  • Respect the WhatsApp rate limits when batching status checks; on a 429, wait until the returned retry timestamp before resuming.

Tip: If you already set open_intercom_conversation: true when sending, the intercom_conversation_id tells you which CRM thread any reply will land in.

What’s next

Did this answer your question?