Overview
Two different problems are often confused:
- Disconnected channel: affects every message in that inbox. The number dropped or lost its session — that case is covered in Common WhatsApp errors.
- A single message that failed: only that bubble shows the failed status, with the reason right below it. The rest of the conversation keeps working.
When a send fails, the platform records the reason returned by WhatsApp (or by the gateway) and marks only that message as failed. So the first step is always to read the reason on the bubble — it points to exactly what to fix.
Prerequisites
- A connected WhatsApp channel (Cloud or Web). If the channel is disconnected, all messages fail — fix the connection first.
- Agent access to the conversation where the message failed.
Step by step
- Open the conversation and find the bubble with the failed status. The error reason appears next to the message.
- Fix it according to the cause (template, 24h window, media, conversation type — see the table below).
- Use Retry when available. If the outcome is uncertain, confirm the original send before repeating it.
- Follow the receipts for that message: sent means provider acceptance; delivered or read confirm later stages.
When the send outcome is uncertain
A timeout, server error or response without acknowledgement can happen after the provider accepted the message. In that situation, the platform reports an uncertain outcome and blocks automatic retries and automatic channel fallback. Wait for confirmation and check the provider history before trying again.
For the first minutes the bubble shows Awaiting confirmation, as a notice rather than an error. The message may already have been delivered, so do not send it again during that time: the second copy would reach the customer as a duplicate. In a hybrid inbox (WhatsApp Cloud paired with WhatsApp Web), when the WhatsApp Web session shows that the text was in fact sent, the same bubble turns to sent on its own, without creating another message. This applies to plain text messages; media, buttons, lists and templates are not resolved this way, and a WhatsApp Cloud-only inbox has no such signal. If nothing arrives within about three minutes, the bubble turns to Send not yet confirmed and shows the diagnostic.
Retry is available for public outgoing messages with a confirmed rejection. The attempt keeps the same message, content, attachments and send identity. Private notes, incoming messages and sends still being processed cannot be retried with this button. Scheduled messages use their scheduling recovery workflow.
A provider-confirmed identifier proves acceptance, not delivery to the recipient. If a later receipt reported failure, that status is preserved. Reopening or repeating the request does not erase the identifier or send another copy. Historical failures without delivery diagnostics and providers without sufficient confirmation require verification; the system does not infer certainty from the error text.
Settings & options
- Message status: sent, delivered, read, failed.
- Failure reason: the bubble shows the available diagnostic. When provider confirmation is missing, it explains the uncertain outcome and the need to verify it.
Common causes
| Cause | Where it happens | What to do |
|---|---|---|
| Template not found or invalid | Cloud | Use an approved template (correct name + language) when replying outside the window. |
| 24h window closed | Cloud | Reopen the conversation with an approved template; only then send a free-form message. |
| Media too large or unsupported type | Cloud and Web | Reduce the file (default limit 40 MB) and use an accepted format (image, video, audio, document). |
| Communities only accept text announcements | Web | In a community, send text only (no media, poll, or buttons). |
| Interactive feature rejected | Web | Buttons/lists/carousel/flow depend on the gateway and WhatsApp; if rejected, the reason appears on the bubble. |
| Native catalog not supported by the provider | non-Cloud | Native product messages are Cloud-only; other providers fall back to the standard product card. |
| Number dropped/disconnected | Cloud and Web | Reconnect the channel — see Common WhatsApp errors. |
Cloud vs Web
- WhatsApp Cloud follows Meta's rules: it has a 24h window and requires an approved template to reopen the conversation. The reason shown on the bubble is Meta's error message, verbatim.
- WhatsApp Web does not use approved templates and has no 24h window — every reply goes out as a session message. The reason shown comes from the connected gateway. Lists and flows only render in 1:1 chats; in groups they arrive as text.
Text above the composer limit
The counter warns when few characters remain. If the text exceeds the limit, it explains the excess, the transport limit and how to fix it. Sending is disabled: split the text manually into multiple messages.
- WhatsApp Web without a hybrid pairing: up to 65,536 characters in plain text.
- WhatsApp Cloud: up to 4,096 characters in a free-form text message.
- Hybrid inbox: the composer keeps a 4,096-character limit even when you select Web. This inbox may use the official API as a fallback after a definite Web rejection. Automatic mode may also choose Cloud.
- WhatsApp channel post: up to 4,096 characters, both in the channel conversation and in Publish to channel, in the Hub.
These limits apply to plain text. Templates, buttons, lists and media have their own rules. In WhatsApp Web buttons and lists, the body, button text, title, footer and section titles are counted in bytes: accents and emoji take more than one. When one of these fields goes over its limit, it tells you, and sending stays blocked until you shorten the text. The platform does not split the text automatically.
Use cases
- Reopen a Cloud conversation that passed 24h, using an approved template.
- Resend media that was rejected for size, after reducing the file.
- Understand why a button worked but the list did not show in a group (on Web).
Tips, limits & best practices
- On Cloud, keep approved templates ready and respect the 24h window.
- Avoid media above the upload limit (default 40 MB) and prefer common formats.
- On Web, remember that list and flow only show in 1:1 chats; in a group, use buttons or text.
- In communities, communicate by text only.
- For campaigns and bulk sends, follow Limits, anti-ban & best practices.
Troubleshooting
- "Template not found or invalid template name" (Cloud): the template you set does not exist, has a different language, or is not approved. Pick an approved template with the correct name and language and resend.
- Failure due to expired 24h window (Cloud): more than 24h passed since the customer last replied. Reopen with an approved template; after that the conversation accepts free-form messages again.
- Media rejected: the file exceeds the limit (default 40 MB) or the type is not accepted. Reduce the size and use image/video/audio/document in a common format.
- Community ("WhatsApp communities only accept text announcements..."): the message had media, a poll, or buttons. In a community, send text only.
- Interactive feature rejected (buttons, lists, carousel, or flow): the platform sends these features without a block of its own — WhatsApp and the gateway are what validate them. If a rejection comes back (for example, a permission message from the gateway), the exact text appears on the bubble; follow that guidance or use a compatible format.
- Number dropped/disconnected: if many messages fail, the problem is the connection, not the message — see Common WhatsApp errors.