WhatsApp not sending#

WhatsApp messages are failing, or they "send" but the customer never gets them. The CRM refuses sends for a small, well-defined set of reasons and records the exact one on the message. Find the failure code, fix its cause, resend. Almost nothing here is guesswork — the system tells you what is wrong.

Who this is for: workspace admins managing the WhatsApp channel, and super admins who own the platform WhatsApp configuration.

Problem#

Messages stuck or failed in an automation, an inbox reply that never delivers, or templates that cannot be sent at all.

What you see#

The failure codes, decoded#

The checks run in that order — the first failing gate is the code you get, so fixing one code may reveal the next. Work through them until the message sends.

Likely causes#

• WhatsApp connection revoked/expired (Meta side), or credentials edited wrongly.
• Templates: not synced, not approved, or renamed in Meta.
• Contact opted out with a stop keyword, or a phone number that cannot receive WhatsApp.
• Sending free-form messages outside WhatsApp's 24-hour reply window — the composer warns you; only approved templates are acceptable outside the window.
• A stalled queue: the message is fine, the worker is not running (see Incident response).

Quick fix#

1. Open the failed message and read its failure_code — use the table above.
2. Admin → Settings → WhatsApp → Test Message. If the test fails, fix the connection first; if it succeeds, the connection is fine and the failure is message-specific (template, opt-out, phone, media).
3. If several messages failed at once, check the System Health WhatsApp card's queue_failures and the worker state.

Step-by-step fix#

1. Connection — connect WhatsApp Business. Then run Test Message from the settings page. Connection fields you may need to verify: WABA ID, Phone Number ID, display number, access token, app secret, verify token. Actions available: Sync Templates, Test Message, Reconnect, Disconnect.
2. Templates — open Admin → WhatsApp templates, sync, and confirm the template you send with is approved. Only approved templates may be used to start/continue conversations outside the 24-hour customer-service window.
3. 24-hour window — inside the window (customer messaged you recently) free-form text is fine; outside it, use a template. The composer tells you when you are outside the window.
4. Opt-outs — when a customer replies with a stop keyword (exact match — defaults are stop, unsubscribe, do not message; the workspace can change the list), the contact is marked opted out (whatsapp_opted_out_at, source inbound_keyword, with the reason recorded and whatsapp_opted_out activity on the contact). Sends to that contact then fail with OPTED_OUT — this is the system protecting you from complaints. Only remove the opt-out if the customer explicitly asks to resume, and do it deliberately on the contact record.
5. Queue — if nothing is sending at all (not even tests), it is a queue/worker problem, not WhatsApp: read the queue runbook in Incident response and check queue_failures on System Health.
6. Webhook health — the inbound webhook URL Meta calls is {app URL}/api/messaging/whatsapp/webhook/{tenant}/{token}; if deliveries/read receipts are not updating, verify this URL and token against Meta's configuration.
7. Retry the message — after fixing the cause, resend. An automation that failed once will not silently retry by itself.

Admin fix#

• Reconnect the channel, sync templates, and fix the contact (number, opt-out state) — everything above is admin-panel work.
• If templates are stuck pending for days, the delay is Meta's review, not the CRM — templates must be approved on Meta's side; rejected ones must be edited and resubmitted there.

Developer fix#

• The guard chain in SendWhatsAppAction runs in this exact order: TEMPLATE_UNAVAILABLE → TEMPLATE_NOT_APPROVED → OPTED_OUT → WHATSAPP_NOT_CONNECTED → NO_VALID_PHONE → MISSING_TEMPLATE_VARIABLE → MEDIA_NOT_FOUND. Failures persist as failed LeadMessage rows with the failure_code above.
• Opt-out handling lives in WhatsAppMessageService: exact keyword match against defaults ['stop', 'unsubscribe', 'do not message'], overridable per workspace (automation.whatsapp_optout_keywords); it stamps whatsapp_opted_out_at, whatsapp_opt_out_source = inbound_keyword, and the reason.
• The System Health WhatsApp card counts failed_jobs whose payload references SendLeadMessage — a fast systemic read.
• The 24-hour window is enforced by WhatsApp itself; the CRM surfaces it as a composer hint, not a hard block — sends outside the window with non-template content will be rejected by Meta.

Logs to check#

• The failed message's failure_code and any provider response — always the fastest source.
• storage/logs/laravel.log — WhatsApp API errors and queue failures around the send time.
• System Health WhatsApp card — connections, templates, and messages today / delivered / read / failed counts.

When to escalate#

• The connection reconnects and tests pass, but all template sends fail for every contact.
• Meta restrictions on the number/business (quality rating, account review) — that is a Meta-side action only the business owner can resolve.
• Deliveries show sent but no delivered/read for a whole day with everything green in the CRM — check the number status in Meta Business Manager, then escalate to the super admin.

Related guides#

• WhatsApp Business API
• Message templates
• How WhatsApp messages are delivered
• Incident response