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. In the HubSpot contact timeline, each proactive message is an event that shows the current status plus the timestamp of the last update. 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.
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).
What’s next