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:
You submit the message from the UI or API.
Octopods hands the message to the provider (Twilio, WhatsApp, or Viber).
The provider attempts delivery to the recipient’s device.
The provider reports the outcome back to Octopods.
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 |
| Octopods handed the message to the provider, but no delivery confirmation has arrived yet. | Wait. Most messages move to |
| The provider confirmed delivery to the recipient’s device. | The message landed. No action needed. |
| The recipient opened the message. WhatsApp only. | The recipient has seen it. |
| The send or delivery failed. A failure reason is available. | Open the message to read the failure reason. See Troubleshooting Failed Proactive Messages. |
| The recipient deleted the message after it was delivered. | Informational only. |
| 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→READSMS, happy path:
SENT→DELIVEREDVBM, happy path:
SENT→DELIVEREDAny channel, failure:
SENT→FAILED(or directlyFAILEDif 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→ SentDELIVERED→ DeliveredFAILED→ Delivery FailedThe 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}orGET /api/v1/sms/messages/{message_id}. See Checking Message Delivery Status.Listing:
GET /api/v1/whatsapp/messagesreturns each message with amessage_status.message_statusfield. 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 |
| The |
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:
Send the WhatsApp template and keep the
message_idfrom the response.Poll
GET /api/v1/whatsapp/messages/{message_id}until the status is terminal (DELIVERED,READ,FAILEDorDELETED). If it’sSENTorUNKNOWN, wait 10–30 seconds and check again.If the status is
FAILED, readfailure_reason. If the problem is the recipient or WhatsApp (for example, “recipient not on WhatsApp”), send the message by SMS withPOST /api/v1/sms/messages. See Send SMS Message.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, andDELETEDwill not change.SENTis 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.UNKNOWNmeans “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
