Documentation
Troubleshooting: when something does not work
The usual problems between your store, Meta and your phone, what causes them and how to fix them. Most of them Connection Doctor finds for you.
Start with these two screens
- Connection Doctor (WAPI Connect → Health & tools → Connection Doctor) checks every link between your store and WhatsApp, and lists the messages that failed in the last 24 hours with the reason in plain words. Press “Check again” after each change. The Connection Doctor guide explains every card.
- Message log (Health & tools → Message log) shows each message the plugin sent or received, with its status and, for a failed one, Meta’s error.
The webhook will not verify
Meta says it could not validate the callback URL or the verify token when you press “Verify and save”. Check, in this order:
- The verify token. The word in Meta’s “Verify token” must be exactly the one in Settings → WhatsApp API → “Webhook Verify Token”, and saved in the plugin before you press “Verify and save”. Copy it again; a space at the end is enough to fail.
- The callback URL. Copy it from the plugin (Overview, Settings → WhatsApp API or Connection Doctor). It ends in
/wp-json/almorshed-whatsapp/v1/webhook. - HTTPS. Meta only calls addresses on HTTPS with a valid certificate.
- Nothing in between. A security plugin, a firewall or a Cloudflare rule that blocks
/wp-json/, a maintenance or “coming soon” mode, or a password on the whole site keeps Meta out. Permalinks must be anything except “Plain”.
Each failed check is written to the Message log as “Webhook verification failed: the verify token does not match, or the mode is wrong.” If nothing shows there at all, Meta’s call did not reach WordPress: look at point 4.
Open this address in a browser, with your own site and your own verify token: https://your-store.com/wp-json/almorshed-whatsapp/v1/webhook?hub.mode=subscribe&hub.verify_token=YOUR-TOKEN&hub.challenge=12345. A page that shows only 12345 means the webhook answers correctly. “Forbidden” means the token does not match. An error page or a login page means something blocks the address.
Customer messages do not arrive
Sending works, but customer messages never reach the inbox, automations do not start, and delivered or read ticks stay empty. Open Connection Doctor and look at the subscription and “Webhook receiving” cards.
“Meta is not sending customer messages to any app”
Your WhatsApp Business Account is not subscribed to your Meta app, so Meta drops every incoming message before it reaches any website. Press “Subscribe now”, then check that your app’s webhook points to this store.
Your WhatsApp account is subscribed to another app
The subscription card lists the names of the subscribed apps. If your own app is not among them, Meta delivers this account’s events only to those other apps, for example one from a tool you used before. Your app is subscribed with one call to Meta’s Graph API with your token (POST /<WABA-ID>/subscribed_apps). If you are not comfortable doing that, open a ticket and we walk you through it.
“Customer messages are sent to another address”
Your account sends its messages to another address, often a tool you used before. Press “Send them to this store”. It needs your verify token to be saved first.
The app is still in Development mode
While your Meta app is in Development mode, Meta can hold back messages from real customers, even when delivery statuses arrive. Add your store’s “Privacy Policy URL” in App settings → Basic, then publish the app (switch it to Live). See the webhook guide and the privacy URL.
Delivery statuses arrive, but no customer message
Turn on the messages field in your Meta app (WhatsApp → Configuration → Webhook fields), and check that the app is Live. Then send a message from another phone and press “Check again”.
“Recent WhatsApp calls were rejected”
Here “calls” means requests from WhatsApp to your store. Usually the App Secret in the plugin does not match your Meta app: copy it again exactly, or clear it by typing - in the field and saving.
Messages arrive for a different Phone Number ID
Your app sends this store the messages of another number. Check the Phone Number ID in Settings → WhatsApp API.
Messages are not sent
- “Sending is stopped” or “The plugin is turned off” in Connection Doctor: untick “Emergency Disable”, or tick “Enable Plugin”, in Settings → General.
- “WhatsApp sending is paused: …” at the top of the plugin’s screens: the license ended and its 14-day grace period is over, or the key is not active on this site. Renew it, or activate it again, in Settings → License. Customer messages still arrive and are saved meanwhile.
- “Messages waiting in the background queue”: WP-Cron does not run on your server. Press “Run them now”, and ask your host for a real cron job for WordPress.
- The message failed: the reason and Meta’s code are in Connection Doctor’s sending errors and in the Message log. The table below explains the common codes.
Common error codes
Meta returns a number with every failed message. The plugin shows it next to the reason, in Connection Doctor, the Message log and campaign reports.
| Code | What it means | What to do |
|---|---|---|
| 131005, 10 | No permission: the access token does not have, or no longer has, the permission it needs | Create a permanent System User token with whatsapp_business_messaging, whatsapp_business_management and business_management, put it in Settings → WhatsApp API, then resume or retry. |
| 131030 | The recipient’s number is not in the allowed list. It only happens with Meta’s public test number. | Add the recipient to the test number’s recipient list in your Meta app, or send from your own registered business number. |
| 131047 | More than 24 hours passed since the customer last wrote, so only a template can be sent | Send an approved template. In the inbox, the box says “Templates only” and offers “Send a template”. When the customer answers, you can write freely again. |
| 131026 | Not reachable on WhatsApp: the number is not on WhatsApp, or the customer uses an old WhatsApp version | Sending again will not help. Check the number, or ask the customer through another channel to update WhatsApp or message your number first. |
| 133010 | Your business number is not registered on the WhatsApp Cloud API | Register it with your 6-digit PIN, as in the phone number guide, then resume. |
| 133016 | Too many register or deregister attempts for this number in a short time | Meta allows 10 register requests per number in 72 hours. Wait, then try once more with the right Phone Number ID, token and PIN. |
| 100 | Meta refused the message data: often an empty or wrong variable, a wrong image link, or a parameter Meta does not accept | Check the template’s variables and their “If empty, use…” values, and that header files are public https links. |
| 190 | The access token expired or is invalid, usually the 24-hour test token | Put a new permanent access token in the settings (tick “Replace with a new token”), then retry. |
| 131042 | Payment problem in your Meta account: an unpaid balance or no working card | Pay the balance or fix the card in Meta’s billing (“Fix in Meta”), then resume or retry. |
| 131049 | Held back by WhatsApp: Meta limits how many marketing messages one person receives from all businesses | Do not resend now; try again in a few days. |
| 131050 | The customer stopped marketing messages from your business | Nothing to do: the plugin moves them to Unsubscribed. |
| 132001 | Template not found: this name and language do not exist or are not approved | Check the template name and language code in the plugin against WhatsApp Manager. |
| 132000 | The number of variables does not match the approved template | Fill in every variable the template has, no more and no fewer. |
| 132015, 132016 | Template paused or disabled by Meta because of low quality | See template rejected or paused. |
| 131048 | Spam limit reached: too many people blocked or reported your messages | Send fewer marketing messages, only to interested customers who agreed. |
| 131056, 130429 | Too many messages to the same person, or sending too fast | Wait a little; for campaigns, lower the sending speed and retry. |
A code that is not in this list shows on the plugin’s screens as “WhatsApp error …” with Meta’s own text. Meta’s full list is in its error codes reference.
A template was rejected or paused
- Rejected: the Templates screen (WAPI Connect → Templates) shows Meta’s reason in plain words next to the part to fix; WhatsApp Manager shows it too. Common ones: an offer inside a utility template, a variable at the start or end, two variables side by side, a missing sample, or content against Meta’s rules. Fix it and submit again, or create a new template with another name.
- Paused (error 132015): many customers blocked or reported messages with this template. Messages with it fail, and the running campaigns that use it are held before any message goes out. Make the message more useful, send it only to customers who agreed, or use another template.
- Disabled (error 132016): Meta switched the template off for good. Create a new one.
With the message_template_status_update and message_template_quality_update webhook fields on, the Templates screen updates itself and Account health records each change, says where the template is used, and alerts you. More in the templates guide.
The daily limit is reached
Meta limits how many different customers you can message with a template in any 24 hours. Replies to customers who wrote to you are not limited. New accounts start low (250 customers a day at the time of writing, 17 October 2026).
- See where you stand in Account health: your limit and how many customers this store messaged in the last 24 hours.
- Before a campaign, the wizard warns “More people than WhatsApp allows today” and offers “Send to … only”. Send the rest the next day.
- From 250 the limit can rise to 2,000 after business verification in Meta, or after 2,000 delivered template messages to different customers in 30 days with good quality. From 2,000 it rises by itself when you use at least half of it with good quality. Only Meta can change it.
- The plugin counts only its own messages. If another tool sends from the same number, you reach Meta’s limit sooner than the screen shows.
Notifications do not arrive on iPhone
- iOS 16.4 or newer. Older iPhones cannot get notifications from a web app.
- Opened from the Home Screen icon. Add the inbox to the Home Screen from Safari (Share → “Add to Home Screen”) and always open it from that icon. In a Safari tab there is no “Turn on notifications” button.
- Allowed. In the inbox open Settings → Notifications → “Turn on notifications” and tap “Allow”. If you refused once, it says “Notifications are blocked”: in the iPhone’s Settings → Notifications, open the inbox app (called “Messages” unless you renamed it) and allow notifications, then open the inbox again.
- Test it. Tap “Send a test notification”. If the test does not arrive, check that Focus or Do Not Disturb is off, and that your site is on HTTPS. Your server also needs to reach Apple’s push service: a firewall that blocks outgoing connections stops every notification.
- The test arrives, but messages do not. Then customer messages are not reaching the store: see messages do not arrive.
Each phone turns on notifications by itself, and logging out stops them on that phone. Connection Doctor’s “Phone notifications” card shows how many devices receive them. More in the inbox app guide.
Still stuck?
Open a ticket with your site address, the plugin version, what you did, what you expected and what happened, plus the error text and code from Connection Doctor or the Message log. Never send your access token, App Secret or passwords.