Messages appear in WhatsApp Web with a yellow warning icon but are never delivered. ⚠️

[SaidAlHendi]

I'm experiencing an issue where messages sent through OpenWA appear in the WhatsApp Web chat, but they are never actually delivered.

The API returns successfully without throwing an error.
The message appears in the WhatsApp Web chat.

This issue seems like the message is being created locally in the WhatsApp Web session but is never acknowledged or sent to WhatsApp's servers. I'd appreciate any guidance on whether this is a known issue or if there's a way to diagnose why the message fails to leave the client.

[rmyndharis]

Thanks for the report — and especially for the screenshot. That amber triangle is the most informative part of it, and it points somewhere different from where your description lands.

What the triangle actually means

WhatsApp Web renders an outgoing message's delivery state in the slot right after the timestamp: a clock while the message is still pending locally, one check once WhatsApp's servers have accepted it, two on delivery to the device. The amber triangle is none of those — it's the error state (ack -1).

So the message wasn't "created locally and never acknowledged". It was acknowledged, and the acknowledgement was a failure. That distinction matters for diagnosis: a message that genuinely never leaves the client sits under a clock indefinitely, whereas yours got an answer from WhatsApp and the answer was "no".

Why the API still returned success

A 201 from the send endpoints means the gateway handed the message to the WhatsApp client and got a message object back — not that the recipient received it. WhatsApp doesn't reject an undeliverable recipient synchronously, so at the moment your HTTP call returns there is genuinely nothing to report. Real delivery state arrives asynchronously, afterwards. That contract is spelled out in docs/06-api-specification.md under "Send response: 201 means accepted, not delivered", and in Swagger.

The failure signal already exists — please check it

This is the part worth acting on: OpenWA maps an error ack to failed on both engines and surfaces it in three places, so you shouldn't have to infer anything from the WhatsApp Web UI.

1. The stored message's status

curl -H "X-API-Key: $API_KEY" \
  "http://localhost:2785/api/sessions/{sessionId}/messages?chatId=628123456789@c.us&limit=5"

Look at status on the message you sent. It advances sent → delivered → read, or lands on failed when WhatsApp reports an error for it. Give it a minute or so after sending — the ack is asynchronous.

2. The message.failed webhook

Subscribe to it (it's dispatched in addition to message.ack, so you can also just watch message.ack and filter on status: "failed"):

{ "events": ["message.ack", "message.failed"] }

Payload: { id, messageId, status: "failed", ack: -1 }.

3. The dashboard's Chats view, which is the quickest check of the three. It renders the same icon set WhatsApp Web does — 🕒 pending, ✓ sent, ✓✓ delivered/read, ⚠️ failed — driven by the status above. So open the same chat there and compare it against your screenshot:

• Dashboard also shows ⚠️ → the error ack reached us and everything on our side worked; the send was rejected by WhatsApp, and the question becomes why (below).
• Dashboard shows ✓ or 🕒 while WhatsApp Web shows ⚠️ → the two disagree, meaning the failure never reached the gateway. That's a defect on our end and I'd want to chase it.

Either answer is useful to me, so please do run this one.

What I need to narrow it down

1. OpenWA version and engine (whatsapp-web.js or Baileys). This one is load-bearing — see the note at the bottom.
2. Was this a number you'd already exchanged messages with, or a first contact? DM or group?
3. What does the recipient check return?

   curl -H "X-API-Key: $API_KEY" \
     "http://localhost:2785/api/sessions/{sessionId}/contacts/check/628123456789"

   → { number, exists, whatsappId }
4. Does it happen to every recipient, or only some?

Most likely causes, and how to tell them apart

If it happens to every recipient — the strong candidate is a restriction on the sending account itself. This is common with numbers that started sending API traffic without any prior organic use, and it is invisible from the gateway's side: the session stays connected and every send comes back with an error ack. The one-step test is to send to the same recipient from the phone directly, using the WhatsApp app. If that also fails or shows the triangle, the problem is at the account level and no gateway change will move it.

If it happens only to some recipients — most likely the recipient isn't reachable: not registered on WhatsApp, or a number you've never exchanged messages with. We've seen this exact symptom before, with the same amber triangle, in #736. Question 3 above settles it — and it's worth actually running rather than inferring, since "didn't arrive" has several possible causes and only the check endpoint distinguishes them (a registered recipient who is merely offline never reaches two checks either).

A cause we can rule out already: the whatsapp-web.js message-id backport. When that's missing, sends fail outright with "the engine returned no message" instead of succeeding, so your 201 tells me it's applied.

One version-specific note

If you're on v0.8.18 or older, there's a path where an error ack is dropped before it ever reaches the status update — on WhatsApp Web builds that renamed the serialized message id, the ack arrived with an id we couldn't read. The message would stay at sent forever and no message.failed would fire, even though WhatsApp did report the failure. Fixed in v0.8.19 (#765); the current release is v0.12.1. If you're on an older build, upgrading is the first step and may well be the whole answer.

---

If it turns out the recipient checks out as exists: true, the message stays at sent, and no message.failed ever fires — on a current version — then that's a real gap on our end rather than a WhatsApp-side rejection, and I'll open a bug for it. Happy to keep digging either way.