A message is stuck or failed
Every message goes through a queue, so the API answers at once and the session sends it a moment later. Its status then moves forward:
| Status | Meaning |
|---|---|
| Queued | Waiting its turn. With account protection on, a session sends one message every few seconds. |
| Sent | WhatsApp accepted it. |
| Delivered | It reached the recipient's phone. |
| Read | The recipient opened it, if they share read receipts. |
| Failed | It could not be sent; the message's error says why. |
Stuck on Queued
The session is probably not connected: check its status and see A session shows Disconnected. Queued messages go out as soon as it is back. A message that cannot be sent within 24 hours fails. A long queue on a connected session drains at account protection's pace.
Stuck on Sent
WhatsApp accepted the message, but the recipient's phone has not received it yet, usually because it is offline. It turns Delivered when the phone comes back. Messages to your own number never show Delivered.
Failed
Common reasons in the error:
- The number is not on WhatsApp. Check it with Check numbers before sending.
- The media could not be downloaded. The URL must be public and stay valid for a few minutes; or upload the file first.
- The session was logged out or banned.
Fix the cause, then click Resend on the message in the Messages tab (or call POST /v1/messages/{id}/resend). If your app retries requests itself, send an Idempotency-Key so a retry never sends twice.