WhatsApp message sent but the customer did not receive it: causes and fixes

Understanding the chain avoids looking in the wrong place. First, your system makes the call and the API accepts it (success response). Second, the instance puts it in the queue, respecting the configured delay between messages. Third, the WhatsApp session sends it to the platform's servers (one tick). Fourth, the recipient's device receives it (two ticks) and then the person reads it.

Each stage has a typical failure cause: bad data in the first, queue or disconnection in the second, number restriction in the third, and the customer's device or block in the fourth. The glossary describes the delivery states.

This is the most frequent cause. The number must go with the country code and digits only, and some countries have their own format rules. A landline, a deactivated line or a mistyped number may even be accepted by the API but will reach no one.

Before campaigns and for one-off suspicions, check whether the number has WhatsApp with the check endpoint, which returns whether each number is registered and its identifier. The number validation tool does the same on the page. Cleaning the list before sending also improves the number's reputation.

curl -X POST https://api.zapzapapi.com/api/v1/SEU_INSTANCE_ID/chat/check \
  -H "Content-Type: application/json" \
  -H "x-api-key: SUA_API_KEY" \
  -H "x-api-secret: SEU_API_SECRET" \
  -d '{"numbers":["5511999999999"]}'

If the session dropped, messages do not go out. Query the instance status: connected, connecting or disconnected. When disconnected, a new QR code scan is needed. Turn on connection change alerts in your webhook so you hear about it right away, and not from the customer.

Messages sent during the disconnection may not have been accepted, so it is worth resending after reconnecting, taking care not to duplicate. Use the API's message history to check what actually went out before resending.

curl https://api.zapzapapi.com/api/v1/SEU_INSTANCE_ID/instance/status \
  -H "x-api-key: SUA_API_KEY" \
  -H "x-api-secret: SEU_API_SECRET"

The instance has a minimum and maximum delay between messages, and campaigns use random intervals. In large batches, the last message can take a while to leave, and whoever looks early concludes it "did not go". The instance status response shows the configured delay.

If the delay is high for no reason, adjust it carefully: cutting the interval too much raises restriction risk. For campaigns, follow progress through the send folder instead of resending. See bulk messaging.

If the customer blocked your number, the message stays at one tick, undelivered, and the platform does not tell you. If their phone has no internet or is off, the second tick appears when it comes back. One tick for many hours and the second never arriving is the classic pattern of a block or an offline device.

Do not insist with repeated resends: they increase reports. Try an alternative channel, such as a call or email, and confirm with the customer whether they can see your messages. Anyone who repeatedly shows undelivered messages should be removed from the send list.

When WhatsApp limits the number, messages may stay unsent or go out only to some contacts. The limits endpoint reports how many new conversations the number can start right now, which helps tell a limitation from an integration error.

If the cause is a restriction, follow the blocked number step by step and review your sending behavior with the risk matrix. Unofficial API use is not provided for in WhatsApp's Terms, and the decision on the account belongs to the platform.

1) Check the number: does it have WhatsApp? Are the format and country code right? 2) Check the instance: is it connected? 3) Check the history: does the message appear in the instance's messages? 4) Check the webhook: did the status event arrive? Use the recent deliveries endpoint and the errors endpoint to see whether your server answered 2xx. 5) Check the recipient: did they block you, are they offline, or is it a number that no longer replies?

Recording the message ID returned by the send lets you cross-check every stage. If the problem is the webhook not arriving, see the guide on receiving messages by webhook. If the problem is general, the API documentation lists the supporting endpoints.

curl -X POST https://api.zapzapapi.com/api/v1/SEU_INSTANCE_ID/message/find \
  -H "Content-Type: application/json" \
  -H "x-api-key: SUA_API_KEY" \
  -H "x-api-secret: SEU_API_SECRET" \
  -d '{"chatid":"5511999999999@s.whatsapp.net","limit":20}'

curl "https://api.zapzapapi.com/api/v1/instances/SEU_INSTANCE_ID/webhook/deliveries?limit=20" \
  -H "x-api-key: SUA_API_KEY" \
  -H "x-api-secret: SEU_API_SECRET"

Validate numbers before campaigns, monitor the connection with alerts, record the ID of every send, handle delivery status in the webhook (marking failures in your system) and create a rule to drop anyone who accumulates failures. For the end customer, offer an alternative channel when a message is critical, such as collections or confirmations.

Finally, distrust "sent" metrics as proof of delivery. Measure delivered, read and replied, and use the reply as the most reliable sign that the conversation exists.

Sometimes the message reached the customer, but your system did not record the status because the webhook failed. In that case the internal panel shows "not delivered" and the team resends, creating duplicates. Compare the instance's message history with your database before concluding there was a delivery failure.

Use the webhook test endpoint to validate the URL, look at the recent deliveries to see the HTTP code your server returned and the error list to find timeouts. If your endpoint is slow, answer 2xx immediately and process later, in a queue.

In groups, the identifier ends in g.us and differs from a person's number; using the wrong format yields a message that never arrives. For numbers from other countries, confirm the country code and use the number check before sending, because each country has its own format rules.