WhatsApp template messages usually fail because the request, approved template, recipient, account, or delivery policy does not match what the WhatsApp Business Platform expects. Start with the message status and exact error code. A well-run WhatsApp marketing program for ecommerce treats delivery diagnostics as part of the campaign, not as an afterthought.
Do not rewrite the template first just because the customer did not receive it. A message can be rejected before sending, accepted but later marked failed, sent but not delivered, or delivered without being read. Those states point to different causes. Your provider log and status callback should tell you which branch to investigate.
Quick Diagnosis
Open one failed message in your WhatsApp provider dashboard. Record its status, timestamp, recipient country, template name and language, error code, and whether the same template works for another opted-in number. Then test one variable at a time. If you change the copy, number format, template, and integration together, you will not know what fixed it.
| What you see | Check first | Likely area |
|---|---|---|
| Request rejected immediately | API response and parameters | Formatting, authentication, template or variable mismatch |
| Accepted, then failed | Status callback error code | Policy, account, recipient or provider issue |
| Sent, not delivered | Recipient validity and delivery receipt | Device, number, restrictions or ecosystem controls |
| Delivered, not read | Timing and message relevance | This is usually an engagement issue, not delivery failure |
| Only some countries fail | Country rules and number formatting | Regional restrictions, authentication rules or invalid destinations |
| Only media templates fail | Public media URL and file type | Asset access or unsupported media |
1. You Are Looking at the Wrong Message Status
“Not received” is a customer observation, not a technical status. Find out whether your system recorded the message as queued, accepted, sent, delivered, read, failed, or undelivered. With provider integrations, an initial successful API response may only mean the request was accepted for processing. It does not always mean the customer’s WhatsApp app received the message.
Configure status callbacks or webhooks and store the final delivery state. Twilio’s WhatsApp API overview explains that callback data can include message status and an associated error code. That code is far more useful than guessing from the campaign dashboard.
2. The Message Is Outside the 24-Hour Customer Service Window
After the customer sends your business a message, a 24-hour customer service window allows free-form replies. Outside that window, a business-initiated message must use an approved template. A common failure occurs when the team thinks it is sending a template but the integration submits ordinary body text instead of the approved template identifier and variables.
For example, Twilio documents error 63016 when free-form content is sent outside the allowed window. Its current error guidance says approved template content must be sent through the correct template fields outside the service window. Check your provider’s equivalent implementation rather than copying Twilio parameter names into another platform.
3. The Template Is Approved, but Your Request Does Not Match It
Approval does not make every variation valid. The submitted template name, language code, number of variables, variable order, header type, button parameters, and media type need to match the approved version. One missing variable can stop a request before delivery.
Compare the live request with the approved record character by character. Pay special attention to these differences:
- The integration calls an old template name after a new version was approved.
- The approved language is en_US but the request sends a different language code.
- The template expects three body variables and receives two.
- A URL button receives a full URL when the template expects only the variable suffix.
- The header was approved as an image but the request sends a document.
- A variable is empty, malformed, or contains data your provider rejects.
4. The Recipient Did Not Give Valid WhatsApp Opt-In
Business messaging should begin with clear permission. Keep evidence showing where, when, and what the customer agreed to receive. A phone number collected for shipping is not automatically permission for promotional WhatsApp campaigns. Review the current WhatsApp Business Messaging Policy and your provider’s requirements before sending.
Opt-in problems may surface as policy enforcement, poor quality, blocks, or weak engagement rather than one convenient “no opt-in” error. The better fix is not cleverer copy. Fix the collection point, set expectations, and let customers choose the message type they want.
5. The Number Is Invalid, Misformatted, or Not on WhatsApp
Normalize every destination to international E.164 format and validate the country code. Remove local trunk prefixes where required. Do not assume that a valid mobile number is active on WhatsApp, or that a number previously active remains available.
Test a failed destination only through methods allowed by WhatsApp and your provider. Do not build a hidden number-enumeration process. If failures cluster around one import source, audit that source for missing country codes, spreadsheet formatting damage, landlines, duplicates, and stale records.
6. Your Account, Sender, or Business Setup Is Incomplete
If every template fails, inspect the sender before inspecting the copy. Check whether the phone number is connected to the correct WhatsApp Business Account, whether verification or payment settings need attention, whether the access token is valid, and whether the sending account has restrictions.
Sandbox environments create another trap. A test recipient may need to join the sandbox, and the sender address must match the sandbox configuration. Twilio’s undelivered WhatsApp troubleshooting checklist separates sandbox setup, template-window errors, invalid destinations, rate limits, and Business Manager configuration. Use the equivalent log fields in your provider.
7. Messaging Limits or Sending Speed Are Being Hit
Campaigns can fail when volume grows faster than the account or integration can handle. Look for a sharp increase in failures at a particular time, batch size, or recipient count. If small tests work but bulk sends fail, inspect rate limits, throughput, queue behavior, account tier, and retry logic.
Do not repeatedly retry every failed request at full speed. That can produce duplicates, add load, and make the pattern harder to read. Use idempotency where supported, apply a backoff, and retry only errors your provider identifies as temporary.
8. Quality Controls Are Limiting Delivery
A marketing message can be technically valid and still perform poorly because recipients ignore, block, or report it. Relevance matters. Sending the same promotion to every buyer, too often, is not a sustainable delivery strategy.
Segment by permission and behavior. A customer waiting for an order update has a different reason to hear from you than someone who bought once eleven months ago. Transactional updates, service replies, and marketing promotions should not share one indiscriminate list.
9. A Media File or Button URL Cannot Be Reached
For image, video, or document templates, test the final asset URL without being logged in. It should use HTTPS, load quickly, return the correct file, and use a supported type and size. Temporary signed URLs can expire between approval, scheduling, and sending. Redirect chains, bot protection, and hotlink restrictions can also stop a provider from fetching the asset.
Test button URLs too. Replace variables with a real example and open the completed URL. A valid template with a broken dynamic suffix still creates a bad customer experience even if delivery succeeds.
10. Your Webhook or Automation Fails After WhatsApp Accepts the Message
Sometimes the message platform is working and your application is not recording the result. Check webhook response codes, signature validation, queue workers, timeouts, and log retention. Store the provider message ID with the order or customer record so a support agent can trace one complaint from campaign event to final status.
A weak setup says “sent” as soon as the API request leaves your server. A dependable setup updates the record as delivery receipts arrive.
11. The Template Category Does Not Match the Message
Utility, authentication, and marketing messages serve different purposes. Do not disguise a promotion as an order update. If the customer must buy something, claim an offer, or browse a promotion, treat the message according to the applicable marketing rules. Category mismatch can lead to rejection, reclassification, or account-quality problems.
Write the message around the customer’s expected task. “Your order 1842 will arrive today” is a service update. “Your order is arriving, and here is 20% off your next purchase” introduces a promotion. That small addition changes the nature of the message.
12. You Changed Too Many Things During Testing
Use a controlled test matrix. Send the same approved template to one known opted-in number, then test another destination. Test text before media. Test one language before adding translations. Record the result and code for every attempt.
| Test | Keep constant | Change |
|---|---|---|
| Recipient test | Template, sender, variables | One destination number |
| Template test | Sender and recipient | One approved template |
| Media test | Template and recipient | Asset URL |
| Volume test | Audience and template | Batch size and pacing |
A Better Ecommerce Delivery Checklist
- Confirm the customer supplied valid WhatsApp opt-in.
- Open the provider log and copy the exact error code.
- Distinguish failed, undelivered, delivered, and unread.
- Check whether the 24-hour service window is open.
- Compare the request with the approved template record.
- Validate the recipient number and country code.
- Test media and button URLs publicly.
- Review account status, quality, limits, and billing.
- Confirm callbacks are recording the final state.
- Run a one-variable test before retrying the batch.
Fix the System, Then Improve the Message
Once delivery works, review whether the message deserves attention. Organic Cart Studio builds WhatsApp Business templates for ecommerce around the customer’s actual stage, including confirmation, delivery, support, and retention use cases. The goal is not simply to increase the number sent. It is to send fewer messages that arrive with a clear reason.
For operational copy, see the cash-on-delivery confirmation workflow. If the problem is a failed parcel rather than a failed API message, use these failed-delivery WhatsApp replies. The wording and diagnosis are not interchangeable.
FAQs
Why is my approved WhatsApp template not being delivered?
An approved template can still fail because the request does not match its approved name, language, variables, header, or buttons. Delivery can also be blocked by an invalid recipient, account restriction, messaging limit, inaccessible media, policy control, or provider configuration. Start with the exact final status and error code.
Does an accepted WhatsApp API request mean the message was delivered?
No. Accepted generally means the platform or provider accepted the request for processing. Use status callbacks or delivery receipts to learn whether it was later sent, delivered, read, failed, or marked undelivered.
Can I send a normal WhatsApp message outside the 24-hour window?
Business-initiated communication outside the customer service window generally needs an approved template sent through the correct template mechanism. Check the current WhatsApp policy and your provider’s implementation because parameter names and error codes differ.
Should I keep retrying an undelivered template?
Not blindly. Identify whether the error is temporary or permanent, correct the cause, and use controlled retry logic. Repeatedly sending to invalid or disengaged recipients can waste budget and damage message quality.
Leave a Reply