WhatsApp API not receiving messages: nine causes in order, and the symptom that points to each
A WhatsApp API number not receiving messages, or a silent webhook? How to separate sending from receiving in a minute, then nine causes by frequency: webhook subscription and the messages field, the number on the app, the test number, the token, registration, the template, two platforms, blocks and server errors — with a table mapping each symptom to its cause.
On this page 4
The short answer
First separate sending from receiving: send a test message and reply from your phone. If receiving alone is silent, the likeliest cause is the webhook subscription or a missing «messages» field, then a number still on the WhatsApp app without coexistence, then a test number, then an expired token. Reconnecting the number from the platform fixes the first three in a minute.
Also asked as: «الواتساب api مش بيستقبل رسايل» · «الويب هوك ما يوصل شي» · «ليش ما توصلني رسائل العملاء على المنصة» · «whatsapp api not receiving messages» · «واتساب API لا يعمل» · «WhatsApp webhook not working»
Before anything: find which direction is broken
Sending and receiving are two different paths at Meta. Sending is a request you make to their servers; receiving is an event they make to your server through a webhook. So send a test message from the platform to your own number, then reply to it from your phone. If the first arrives and the second does not, the fault is in receiving alone, and this list is for it. If the first never arrives, start from causes two and five.
The causes, in the order we actually see them
- The webhook is not subscribed, or subscribed without the «messages» field
The commonest cause by far. The subscription in the Meta app needs an initial verification and then a choice of fields, and the messages field gets forgotten or dropped after an edit. Symptoms: sending works, receiving is completely silent, and no log shows an error — because Meta does not send what was not requested. Fix: reconnecting the number from the platform re-subscribes it with its fields, or review the fields in the app settings.
- The number is still on the WhatsApp app
A number registered on the app does not send its events to the API. Either move it fully — delete it from the app, then register it on the API — or enable coexistence mode so both work and everything reaches both. In coexistence the first sync of contacts and history is available only for 24 hours after linking.
- A test number, not a production one
The test number Meta provides receives only from numbers added to its list. A real customer messaging it does not get through. The restriction ends when you move to your real number.
- The access token expired or lost its permissions
A temporary token from the developer console lives for hours; a permanent link uses a system user and a non-expiring token. A token that lost the «whatsapp_business_messaging» permission after an account change fails sending with a clear error, and webhook verification may stop. Fix: reconnecting from the platform issues a valid token.
- The number is not registered yet, or pending verification
A number that was added but never finished registration — the SMS or call code was not entered — or a business account held for Meta verification. The number's state on its platform page says so in words.
- The customer is outside the window and your template is rejected — a sending fault, not receiving
When you start a conversation outside the 24-hour window you need an approved template. A rejected or pending template drops your message, and it looks as if the customer "never replies". Receiving is fine here; the template needs fixing.
- The same number is connected to two platforms
One WhatsApp Business account sends its events to one Meta app. If you connected the number to a second platform after the first, the webhook moved there and the first went silent. Pick one platform for the number.
- Blocked by the customer, or a file Meta rejects
One customer does not get through while others do: they blocked you, or sent a file of a size or type Meta rejects and that message dropped alone. No general fault here.
- The receiving server answers with an error and retries pile up
Meta retries when the server answers with an error, backs off, then stops. On our platform the webhook door is monitored and anything not signed by Meta is refused, so real messages enter and forgeries are turned away — and we tell the two apart from the access log, not the error log.
The symptom points to the cause
| What you see | Most likely cause | Where to fix it |
|---|---|---|
| Sending works, receiving silent, no errors | Webhook subscription or messages field | Reconnect the number from the platform |
| Messages reach the phone, not the platform | Number on the app without coexistence | Enable coexistence or move the number |
| Only certain numbers get through | Test number | Move to the real number |
| Sending fails with a permission error | The token | Reconnect |
| The customer "never replies" to a message you started | Rejected template outside the window | The templates page |
| Silence that began the day another platform was connected | Number on two platforms | Pick one platform |
Frequently asked questions
Messages reach the WhatsApp app on the phone but not the platform — why?
Because the number is still registered on the app, not the API. One number lives in one place: either you move it fully to the API, or you enable coexistence mode so both work and messages reach both. Before that, what reaches the app does not reach the API.
I send from the platform fine but the customer's reply never arrives
Sending goes one way and receiving goes another — the webhook. If sending works and receiving fails, the fault is in the webhook subscription or its fields — specifically the «messages» field — not in the number or the token. It is fixed in the Meta app settings or by reconnecting the number from the platform.
Some customers get through and some do not
Three usual causes: a customer blocked your number, a customer on a very old WhatsApp version, or a message carrying a file of a size or type Meta rejects, which drops alone. Check the webhook log for that specific number before assuming a general fault.
Does a low quality rating stop receiving?
No. The quality rating and messaging limits restrict what you start; what the customer starts always reaches you. If receiving stopped, the cause is elsewhere on this list.
How do I know the number is connected right now?
From the number's page on the platform: connection state and last update. When the link drops you get an alert on WhatsApp or a push in the app that opens the repair page directly — you do not find out from a silent inbox.
Does Meta resend what was missed during an outage?
It retries for a while if the server answered with an error, and does not if the webhook was never subscribed in the first place. That is why the subscription and its fields are the first thing to check, not the last.
Read next
Try the agent before you pay anything
The agent that will answer your customers is the one answering you now: ask it from the chat button here or on WhatsApp. Your account is free with no credit card, and the free trial on your own number or page is activated after you contact our team on customer-service WhatsApp.