Skip to main content

Troubleshooting undelivered messages

Diagnose and fix proactive messages that end up in a `FAILED` state, whether they failed at validation, at Octopods, or at the provider.

Written by Mohamed Elbadwihi

This article helps you find out why a proactive message failed, or why a message shows as sent but never reaches the customer. It covers WhatsApp, Viber Business Messages and SMS, including Intercom Twilio SMS that isn’t delivered. To learn more about starting conversations, visit Proactive messaging for Intercom.

Start here

Every failed proactive message has a reason attached. Open the message in whichever surface you noticed it in:

  • Intercom Inbox App — click the failed row in View sent messages to see the details.

  • HubSpot — for sends from the contact record, check the Octopods card. For workflow sends, open the workflow’s action log in HubSpot.

  • Reach — open the message in the sent history list to see the failure reason on the message detail screen.

  • API — call GET /api/v1/whatsapp/messages/{message_id} or GET /api/v1/sms/messages/{message_id}; the response includes a failure_reason field.

The reason tells you where the failure happened. The categories below walk through the most common ones.

Recipient problems

These are the most common failures. They usually mean the number you sent to is not a valid target for the channel.

Symptom

What it means

How to fix

“Phone number is missing.”

The send request had no recipient phone number.

Supply destination_phone in the request, or confirm the contact in Intercom/HubSpot has a phone number associated.

“Invalid Phone number.”

The phone is not in E.164 format.

Re-format as + followed by the country code and the number, with no spaces or hyphens.

“Your Lead or User does not have a Phone Number associated with them.”

The selected Intercom/HubSpot contact has no phone on record.

Add a phone to the contact record, then retry.

“recipient not on WhatsApp” (WhatsApp only)

The number is correct, but is not registered on WhatsApp.

Try SMS or another channel, or confirm the recipient is on WhatsApp.

SMS reports “landline” or “unreachable”

The number is a landline, suspended, or outside a region your SMS channel supports.

Try a different number or channel. Check your SMS channel’s regional coverage.

Channel and account problems

These point at the sending side rather than the recipient.

Symptom

What it means

How to fix

“Your origin sending Channel / Number is unknown to us.”

The sending channel is not connected or is disabled.

Reconnect the channel in Settings → Channels, or pick a different channel.

“Deprecated API key.”

The API key used to send has been rotated or revoked.

Copy the current key from the channel’s settings screen and update your integration.

HTTP 429 with a “too many requests” message and a retry timestamp (WhatsApp API)

You hit the WhatsApp rate limit and Octopods blocked the API key for a short period.

Pause sends until the timestamp in the response has passed, then resume.

Template message fails with “Template does not exist or is not approved”

The template has been paused, rejected, or deleted at the provider.

Confirm the template is in the Approved state in Settings → Channels → Templates. Re-submit if needed.

Template problems

Template-only channels (WhatsApp template sends and Viber Business Messages, or VBM) add a few specific failure modes.

Symptom

What it means

How to fix

“Invalid header media URL.”

The header_attachment_url (WhatsApp) or header_image_url (VBM) was empty, not reachable, or did not match the template’s declared header type.

Host the file on a public URL and confirm it matches the header format (image, video, or document).

“The number of variables you supplied does not match the template.”

You sent too few or too many values for the template’s placeholders.

Count placeholders in the template body (and header/footer/buttons if present) and supply exactly that many values.

Variables show as {{1}} in the delivered message

At least one variable was left blank.

Fill every placeholder the template declares — blanks are rendered literally.

Provider failures

Sometimes the provider itself returns an error. These come through as the error field in an API response, or as a plain-text failure reason in the UI. The three common categories:

  • WhatsApp provider error. Causes include re-engagement window expired (no session with the user), template paused at Meta, or a WhatsApp-side rate limit. Most are temporary — retry after a short delay.

  • SMS provider error. Causes include carrier filtering, an invalid number, or a geographic region not enabled on your account. Inspect the provider’s returned error text for specifics.

  • VBM provider error. Causes include template rejection at Viber or a geographic coverage issue.

Note: If a provider error recurs consistently for the same recipient, treat it as a recipient-specific problem (wrong channel, wrong number, or recipient opt-out) rather than a provider outage.

Intercom Twilio SMS not delivered, but shown as sent

A status of Sent means Octopods handed the message to Twilio. It doesn’t mean the customer’s phone received it. Carriers can still filter or reject the message after that. See WhatsApp, SMS and VBM delivery status.

Find the real result in Twilio. In the Twilio Console, open Monitor, then Messaging logs, and search for the customer’s number. Each message shows its final status (for example Delivered, Undelivered or Failed) and a Twilio error code.

Twilio error code

What it means

What to do

30034

The message came from a US number that isn’t registered for A2P 10DLC.

Finish your A2P 10DLC brand and campaign registration. See Setting up Twilio SMS for Intercom.

30007

The carrier filtered the message.

Check your A2P registration, and avoid link shorteners and content that looks like spam.

30003, 30005

The phone is unreachable, or the number is unknown or no longer active.

Confirm the number with the customer, or use another channel.

30006

The number is a landline or can’t receive SMS.

Use another number or channel.

21610

The customer replied STOP to this number.

Twilio blocks further messages until the customer replies START.

21408

Your Twilio account isn’t allowed to send to that country.

Turn on the country in Twilio’s Messaging Geo Permissions.

Other common causes:

  • Your sender can’t send to this customer. Alphanumeric sender IDs only send outbound and aren’t allowed in every country, including the US. Use a phone number for two-way conversations.

  • Short codes. Short codes aren’t supported in Octopods. Use a long code or toll-free number.

  • Twilio trial account. A Twilio trial account can only send to numbers you’ve verified in Twilio. Upgrade the Twilio account.

  • The channel is disconnected. If you rotated your Twilio Auth Token, the Octopods channel disconnects. The token can’t be edited in place: deactivate the channel on its detail page, then activate it again with the new token. See Channel Statuses and Troubleshooting.

Replies sent from an Intercom conversation. For normal replies your team sends from a conversation, Octopods doesn’t show a delivery status. If a reply fails to send, Octopods adds a note to the conversation. The Delivery Status field exists only for proactive messages, in the Intercom Inbox App.

Retry guidance

  • Transient failures (provider error, rate limit, UNKNOWN status that never resolves): retry after 30–60 seconds. If it keeps failing, escalate.

  • Validation failures (missing phone, invalid phone, missing template variables): do not retry without fixing the input first.

  • Permission failures (deprecated API key, unknown channel, template not approved): the fix is in your workspace settings, not in the request. Resolve there, then retry.

When nothing works

If a message keeps failing and none of the categories above apply:

  1. Note the exact failure reason and timestamp.

  2. Copy the message_id (API) or open the message detail view (UI).

  3. Contact Octopods support with the message ID, channel name, and failure reason.

What’s next

Did this answer your question?