The WhatsApp Business API stops working for predictable reasons. Messages fail to deliver, webhooks stop responding, templates get rejected, verification stalls, or an account gets restricted: and the path back to normal is not always obvious. This guide covers the most common API issues, why each one happens, and exactly what to do to resolve it. If you are working with a platform provider like Intelli, many of these issues can be worked through more effectively with Intelli's guided support alongside Meta's standard processes.
Why Are My WhatsApp API Messages Not Delivering?
Message delivery failures on the WhatsApp Business API have four main causes.
Recipients are blocking or reporting your messages. WhatsApp's Business Messaging Policy requires businesses to obtain opt-in permission before sending messages. Sending to contacts who have not opted in is a policy violation. Beyond the compliance issue, contacts who were not expecting to hear from you are far more likely to block your number or report the message as spam. Meta tracks block and report rates closely as part of your message quality rating. When those rates exceed acceptable thresholds, Meta can restrict your account or take enforcement action. Building a properly opted-in contact list is both a policy requirement and the most direct way to protect your quality rating and account standing.
The phone number format is wrong. WhatsApp requires all numbers in full international format: the country code followed by the number, no spaces, no brackets, no hyphens, no leading zeros. Formatting errors prevent delivery. Some API providers return an error code, others may not. Either way, check your number format if messages are not going through.
Correct formats by country:
Ghana: +233201234567 (not 0201234567)
Nigeria: +2348012345678 (not 08012345678)
Kenya: +254712345678 (not 0712345678)
South Africa: +27821234567 (not 0821234567)
United Kingdom: +447700900123 (not 07700900123)
Before sending any campaign, run your contact list through a number formatting check. Most bulk imports from CRMs or spreadsheets carry local formats that need converting.
Your messaging limit has been reached. Since October 2025, WhatsApp messaging limits apply at the Business Portfolio level, meaning the limit is shared across all WhatsApp numbers in your portfolio.
The current limits are 250 → 2,000 → 10,000 → 100,000 → Unlimited unique users per rolling 24 hours for business-initiated messaging outside the customer-service window.
New portfolios start at 250. To move to 2,000, businesses can qualify through Meta business verification, partner verification, or by delivering 2,000 qualifying template messages to unique users within a rolling 30-day period.
From 2,000 onward, upgrades are automatic. Meta can move you to the next tier when your message quality is high and you have used at least 50% of your current limit within the previous seven days. For example, a portfolio at 2,000 would need to reach at least 1,000 unique users within that period.
If you exceed your current limit, additional business-initiated messages will not be sent until capacity becomes available again. Messages sent within an open customer-service window do not count toward this limit.
To check your limit, go to WhatsApp Manager → Account tools → Messaging limits. Also remember that inactive or non-WhatsApp numbers will not count toward your actual usage, even if they appear in your contact list.
Your quality rating is too low. Meta monitors how recipients respond to your messages. High block rates and report rates lower your quality rating and can restrict or pause your sending capability.
To check your quality rating: go to Meta Business Manager, open WhatsApp Manager, and select your phone number. Your quality rating is displayed as High (green), Medium (yellow), or Low (red). A Low rating can result in restrictions on your sending. Note that individual templates also carry their own quality ratings and can be paused independently of the phone number's overall rating. If specific templates are not sending but others are, check the template-level quality rating as well.
If your rating is Low or Medium, pause proactive broadcasts, review the opt-in quality of your recent sends, and allow the rating time to recover before resuming. A rating typically reflects the last seven days of recipient feedback.
Why Is My WhatsApp Business Verification Stuck?
Meta's business verification process is the step that most commonly delays API go-lives. Here is why it stalls and what to do.
Name mismatch between Meta Business Manager and your registration documents. The business name in Meta Business Manager must match your registration documents exactly. "Accra Traders Ltd" and "Accra Traders Limited" are treated as different names by Meta's system. Check that punctuation, spacing, and abbreviations match precisely before submitting.
Wrong document type uploaded. Meta requires official government-issued business registration documents. The correct documents vary by country:
Ghana: Registration or incorporation certificates from the Office of the Registrar of Companies (ORC) are commonly accepted. Tax registration documents may also be requested. Download fresh copies from orc.gov.gh if your documents are old or damaged.
Nigeria: Registration or incorporation documents are commonly required. Meta generally accepts registration certificates, incorporation documents, tax registration certificates, and similar official organisational documents. The specific combination requested can vary by verification case.
Kenya: Business registration certificates and government-issued tax documents are commonly accepted. The specific requirements depend on what Meta needs to confirm for your business.
South Africa: Registration documents from the Companies and Intellectual Property Commission (CIPC) are commonly accepted. SARS tax documentation may also be requested depending on the verification case.
If your country is not listed above and you are unsure which documents Meta requires, contact Intelli's support team at [email protected]: the team has experience with verification across multiple African markets and can advise on the correct documentation for your country.
Tax ID not recognised. If Meta is asking for a Tax ID and it is not being accepted, ensure you are entering the number without spaces or dashes in exactly the format Meta expects for your country.
Review is genuinely delayed. Meta's documentation states most business verifications are processed within 48 hours, though some take longer. Intelli's experience across African markets has shown this can vary. If verification has not moved after 7 business days, raise it with your API provider rather than submitting again. Contact Intelli's support team at [email protected] with your Business Manager ID and submission date.
Why Are My WhatsApp Templates Being Rejected?
Template rejection is one of the most common and most frustrating API issues. Meta's automated review system rejects templates for specific reasons, and understanding each one allows you to fix and resubmit quickly.
Variable placeholders without examples. Every template variable must have a sample value provided at submission. A template with {{1}} but no example content for that variable will be rejected. Add sample values for every placeholder before submitting.
Promotional content in a utility template. Utility templates are for transactional messages: confirmations, receipts, updates. If a template submitted as utility contains promotional language such as "exclusive offer," "limited time," or "save," Meta may approve it as a marketing template instead, or reclassify an already-approved utility template to marketing. This means it will be charged at the higher marketing message rate. Review the category and content of every template before submitting.
Prohibited and restricted content. WhatsApp prohibits businesses from using the platform to promote or facilitate certain regulated goods and services, including alcohol and tobacco, real-money gambling, certain financial products, drugs, weapons, adult products, and other restricted categories. These restrictions can apply even where the business is locally licensed. Political parties, politicians, candidates, and political campaigns are also prohibited from using the WhatsApp Business Platform. Always check the current WhatsApp Business Messaging Policy before building templates for a regulated industry.
Header and body mismatch. The template header, body, and footer must be consistent and coherent. A header that says "Order Update" with a body that delivers a promotional message will be flagged.
Generic or unclear purpose. Templates that do not clearly serve a specific business purpose: messages that feel like spam in their construction: are rejected. Each template should have one clear purpose that is evident from its content.
Template not synced after approval. This is not technically a rejection, but it has the same practical effect. After a template is approved by Meta, it needs to be synced within your API platform before it can be used for sending. If you attempt to send with a newly approved template and it fails, check whether the template has been synced in your platform dashboard. In Intelli, you can trigger a sync manually from the templates section.
If your template is rejected, fix the stated rejection reason before resubmitting.
Why Is My WhatsApp Account Restricted or Banned?
Account restrictions can result from poor messaging quality, negative user feedback, or violations of WhatsApp's Business Messaging Policy. Meta monitors how recipients respond to your messages through block rates and report rates, and also enforces its Business Messaging Policy directly, independently of the quality rating system. Understanding which mechanism caused a restriction affects the resolution path.
High block rate. When a significant proportion of recipients block your number after receiving a message, Meta interprets this as unwanted communication and reduces your quality rating. A sustained high block rate can lead to messaging restrictions or further enforcement action.
Sending to non-opted-in contacts. Sending to contacts who did not explicitly consent to receive your messages is both a policy violation and a quality risk. Recipients who do not recognise your business are more likely to block or report the message. This can damage your quality rating and, where Meta determines policy has been violated, lead to enforcement action.
Template misuse. Using a utility template for promotional purposes can result in the template being reclassified as a marketing template, or in enforcement action depending on the nature of the violation.
If your account has been restricted, check your quality rating in WhatsApp Manager and address the underlying cause before sending again. If it has been banned, submit an appeal through Meta Business Manager under the WhatsApp account section.
If you are an Intelli customer and your account has been restricted or banned, contact [email protected]. Intelli's team can help you understand what triggered the action and guide you through the steps to address it alongside Meta's review process.
Why Are My Webhooks Not Receiving Messages?
Webhooks are the mechanism through which your WhatsApp platform receives incoming messages and delivery status updates. If your webhook stops receiving events, incoming messages are not processed.
The webhook URL is not publicly accessible. A webhook endpoint on localhost or behind a firewall that is not exposed to the internet will not receive events from Meta's servers. Your webhook must be at a publicly accessible HTTPS URL.
SSL certificate issues. Meta requires a valid SSL certificate on your webhook endpoint. An expired, self-signed, or misconfigured certificate can prevent webhook verification or delivery from completing.
Webhook verification failed. Meta sends a verification request to your webhook when it is first registered or after changes. If the verification response does not return the correct challenge token, the webhook will not be active.
App not subscribed to the correct WABA. In Meta's app settings, ensure the app is subscribed to the relevant WhatsApp Business Account (WABA). On the Cloud API, inbound messages and message status notifications both arrive under the webhook's messages field. Status updates appear as a statuses object within that field rather than as a separate subscription type. Check that the app subscription is active and correctly linked to your WABA.
If you are using a platform like Intelli, webhook configuration is handled by the platform and issues are surfaced in the platform dashboard rather than requiring manual diagnosis.
Why Are My WhatsApp Messaging Limits Not Increasing?
Since October 2025, WhatsApp messaging limits operate at the Business Portfolio level. New business portfolios start at 250 unique contacts per 24 hours. The next level is 2,000. Progression beyond 2,000 is automatic based on quality and usage.
Progression requires consistent use of your current capacity. Moving from 250 to 2,000 requires an eligible scaling path, such as Meta business verification, partner verification, or delivering 2,000 qualifying messages within a rolling 30-day period. From 2,000 onward, upgrades are automatic when message quality is high and you have used at least 50% of your current limit within the previous seven days.
Message quality must be high. For automatic scaling at 2,000 and above, Meta requires high message quality, not just medium. A medium quality rating may not be sufficient to trigger automatic progression. Address quality issues first: review your opt-in practices, clean your contact list, and pause campaigns until the rating recovers to high. Then resume sending while ensuring consistent utilisation of your current capacity.
Check that contacts are actually on WhatsApp. Your list may include numbers that are inactive or not registered on WhatsApp. These do not count toward your used capacity even if they are in your send list. Your effective daily reach may be lower than you think, which can slow progression.
What to Do When You Cannot Fix It Yourself
Some API issues are resolvable through configuration changes and documentation. Others are more complex and benefit from having experienced support alongside you as you navigate Meta's processes.
As an official Meta Technology Partner, Intelli's support team works with businesses across Ghana, Kenya, Nigeria, and beyond on issues ranging from first verification to template approvals to account recovery. The team can help you understand what is happening with your account and support you through the steps to resolve it: whether that is working through Meta's documentation, helping you prepare the right information for a review, or simply being available when things go wrong.
When something breaks, the question is not just what is wrong. It is who is there to help you work through it. If you are stuck on any of the issues above, reach out at [email protected] or start a conversation on your Intelli dashboard.
Frequently Asked Questions
How long does WhatsApp Business verification take? Meta's documentation states most verifications are processed within 48 hours, though some take longer. If verification has not progressed after 7 business days, contact your API provider rather than resubmitting. Intelli's support team can help you understand what is happening and advise on next steps.
My template was approved but now messages are failing. Why? Common causes include: the template has been paused or disabled by Meta after post-approval review, the business portfolio has reached its messaging limit for business-initiated messages, the recipient's number is not on WhatsApp or is inactive, there is an API credential or configuration error, or the account has been subject to enforcement action. Check WhatsApp Manager for the template status and your account quality rating on the number overview page. Check your portfolio-level messaging limit under Account tools, then Messaging limits. Note that opt-in is a policy requirement under WhatsApp's Business Messaging Policy, but delivery failure and policy compliance are separate technical issues.
Can a banned WhatsApp API account be reinstated? Yes, in many cases. Submit an appeal through Meta Business Manager under the WhatsApp account section. If you are an Intelli customer, contact [email protected]. Intelli's team can help you understand what triggered the action, prepare your appeal, and support you through Meta's review process.
How do I check my quality rating? Log in to Meta Business Manager and open WhatsApp Manager. Your phone number quality rating (High, Medium, or Low) is found in WhatsApp Manager on the individual number overview page. Your portfolio-level messaging limit is found under Account tools, then Messaging limits. These are two distinct metrics in two different locations. Check both when diagnosing sending issues.
My WhatsApp number was working yesterday and stopped today. What happened? There are several possible causes: a quality rating drop from a recent broadcast, a template being paused due to low template-level quality, reaching your messaging limit for the 24-hour period, an account enforcement action from a policy review, or an API credentials or configuration issue. Start by checking your quality rating and template statuses in WhatsApp Manager, and your messaging limit status in the phone number overview. If everything looks normal there, check your API credentials and connection. If you cannot identify the cause, contact [email protected].
Intelli is an official Meta Technology Partner serving businesses across Africa. If your WhatsApp API is not working and you need help resolving it, contact [email protected] or visit intelliconcierge.com to start your free trial.
