Skip to main content

WhatsApp, SMS and VBM delivery status

Learn what each delivery status means and how to read it consistently across the Intercom Inbox App, the HubSpot extension, Reach (Intercom

Written by Mohamed Elbadwihi

Use this article to check the delivery status of a WhatsApp, SMS or Viber Business Messages (VBM) message, whether you sent it from Intercom, Reach, a HubSpot workflow or the API. It also explains how to find the failure reason, so you can decide whether to try another channel. For more on starting conversations, visit Proactive messaging for Intercom.

The lifecycle of a proactive message

Every proactive message you send — SMS, WhatsApp, or Viber Business Messages (VBM) — goes through the same lifecycle:

  1. You submit the message from the UI or API.

  2. Octopods hands the message to the provider (Twilio, WhatsApp, or Viber).

  3. The provider attempts delivery to the recipient’s device.

  4. The provider reports the outcome back to Octopods.

  5. Octopods updates the status, which you can read anywhere the message is displayed.

Statuses update asynchronously — a message marked SENT a few seconds ago may already be DELIVERED if you refresh.

The six status values

Across every surface — Intercom, HubSpot, Reach (Intercom only), and the API — Octopods uses the same status vocabulary:

Status

What happened

What to do

SENT

Octopods handed the message to the provider, but no delivery confirmation has arrived yet.

Wait. Most messages move to DELIVERED within seconds.

DELIVERED

The provider confirmed delivery to the recipient’s device.

The message landed. No action needed.

READ

The recipient opened the message. WhatsApp only.

The recipient has seen it.

FAILED

The send or delivery failed. A failure reason is available.

Open the message to read the failure reason. See Troubleshooting Failed Proactive Messages.

DELETED

The recipient deleted the message after it was delivered.

Informational only.

UNKNOWN

Status is not yet available from the provider.

Retry the status check after 10–30 seconds.

Typical status transitions

Most messages follow one of these paths:

  • WhatsApp, happy path: SENT → DELIVERED → READ

  • SMS, happy path: SENT → DELIVERED

  • VBM, happy path: SENT → DELIVERED

  • Any channel, failure: SENT → FAILED (or directly FAILED if Octopods could not hand it to the provider)

A status is considered terminal once it reaches DELIVERED, READ, FAILED, or DELETED — it won’t move from there. SENT and UNKNOWN are not terminal; keep polling until one of the terminal states arrives.

Reading status in each surface

The same status values surface differently depending on where you look.

In the Intercom Inbox App. In the Inbox App history view (View sent messages → click a row), the Delivery Status field shows an icon and a short label:

  • SENT → Sent

  • DELIVERED → Delivered

  • FAILED → Delivery Failed

  • The intermediate Send Attempted label appears when Octopods has accepted the send but the provider has not yet confirmed.

In HubSpot. Octopods doesn’t write timeline events of its own. The conversation is linked to the HubSpot contact and shown on its activity timeline. Delivery tracking is covered in full in Tracking Proactive Message Delivery in HubSpot.

In the Reach extension (Intercom). After a send, Reach shows a live delivery timeline on the confirmation screen — Queued, Sent, Delivered, and (for WhatsApp) Read. In the sent history list, each message card shows a status indicator and label for the current state.

In the API. The API surfaces status in two places:

  • Polling by ID: GET /api/v1/whatsapp/messages/{message_id} or GET /api/v1/sms/messages/{message_id}. See Checking Message Delivery Status.

  • Listing: GET /api/v1/whatsapp/messages returns each message with a message_status.message_status field. See Listing Sent Messages.

Both endpoints return the uppercase status values (SENT, DELIVERED, READ, FAILED, DELETED, UNKNOWN) exactly as described above.

Check whether a WhatsApp template was delivered or failed

Where to look depends on how you sent the template.

Sent from

Where to see the status

Where to see the failure reason

Intercom Inbox App

View sent messages, then click the row. Check the Delivery Status field.

Click the failed row to see the details.

HubSpot workflow

The contact’s Message History table, and HubSpot’s workflow history for the enrollment.

The Details column of Message History, or the per-step result in the workflow history.

API

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

The failure_reason field in the same response.

For the meaning of each failure reason, see Troubleshooting Failed Proactive Messages. For workflow sends, see Monitoring Workflow Message Delivery.

Fall back to SMS when WhatsApp fails

Octopods doesn’t switch a failed WhatsApp message to SMS for you. There’s no automatic WhatsApp-to-SMS fallback anywhere in Octopods. You can build the fallback yourself with the API:

  1. Send the WhatsApp template and keep the message_id from the response.

  2. Poll GET /api/v1/whatsapp/messages/{message_id} until the status is terminal (DELIVERED, READ, FAILED or DELETED). If it’s SENT or UNKNOWN, wait 10–30 seconds and check again.

  3. If the status is FAILED, read failure_reason. If the problem is the recipient or WhatsApp (for example, “recipient not on WhatsApp”), send the message by SMS with POST /api/v1/sms/messages. See Send SMS Message.

  4. Don’t fall back for input errors such as an invalid phone number or missing template variables. Fix the request instead, because SMS will fail for the same reason.

Set a time limit on step 2. A message can stay at SENT for a while if the recipient’s phone is offline, and that isn’t a failure.

Octopods doesn’t send delivery status webhooks or callbacks, so polling the status endpoint is the way to get the result. A HubSpot workflow can’t branch on an Octopods delivery status either: the workflow action only fails if the send itself fails.

When to trust a status

  • Terminal statuses are reliable. DELIVERED, READ, FAILED, and DELETED will not change.

  • SENT is a progress marker. Octopods has passed the message to the provider but does not yet know the outcome. Most messages leave this state within seconds.

  • UNKNOWN means “ask again later”. The provider hasn’t reported yet. Retry after 10–30 seconds.

Note: A DELIVERED status means the provider confirmed delivery to the device — it does not guarantee the recipient saw the message. For that signal, watch for READ (WhatsApp only).

Note: DELIVERED and READ come from the provider. If a customer says they didn’t get a message that shows DELIVERED, the message reached their device. Ask them to check archived chats, blocked contacts or their SMS spam folder. The Delivered tag in HubSpot’s Message History works differently; see Tracking Proactive Message Delivery in HubSpot.

What’s next

Did this answer your question?