Why is my WhatsApp template message showing 'undeliverable'?
Resolve WhatsApp message undeliverable errors in SparkTG. Covers unregistered numbers, blocked contacts, outdated app versions, T&C acceptance, and Meta caps.
When a template message sent through SparkTG's WhatsApp Business API fails to reach a recipient, the campaign log will show a delivery failure against that contact. This does not mean SparkTG failed to send the message — it means WhatsApp's delivery layer returned an undeliverable status after the message was dispatched. The root cause is always on the recipient's side or within Meta's delivery policies.
SparkTG relays the exact error code returned by Meta's API. If you see this error, SparkTG has already transmitted the message successfully — the issue is downstream at WhatsApp's delivery layer.
What causes a template message to be undeliverable?
There are five distinct reasons WhatsApp marks an outbound template message as undeliverable. Understanding which one applies to your situation is the fastest path to resolution.
Reason 1 — The recipient's number is not on WhatsApp
The phone number exists but has never been registered on WhatsApp, or the WhatsApp account linked to that number has been deactivated. This is the most common cause for bulk campaign failures on freshly imported contact lists.
- 1
Use SparkTG's number validation before sending
SparkTG Dashboard → Campaigns → New Campaign → Audience. Click Validate Contacts before scheduling. SparkTG will check each number against WhatsApp's database and flag unregistered numbers so you can exclude them before any credits are consumed.
- 2
Clean your contact list regularly
Numbers that were valid six months ago may no longer be active WhatsApp accounts. Run a validation pass on any contact list older than 90 days before using it in a campaign.
Reason 2 — The recipient has blocked your business number
If a user has blocked your WhatsApp Business number, all outbound messages — including template messages — will be silently marked as undeliverable. WhatsApp does not notify businesses when they are blocked, to protect user privacy.
- You cannot unblock yourself — only the recipient can remove the block.
- Reach out through an alternate channel (email, SMS, phone) and ask them to check Settings → Privacy → Blocked Contacts in WhatsApp.
- A high block rate across a campaign signals that your message content or frequency is unwanted — audit your opt-in process and template relevance.
Reason 3 — Recipient has not accepted WhatsApp's latest Terms of Service
WhatsApp periodically updates its Terms of Service. Until a user accepts the updated terms, they cannot receive Business API messages — even if they can still send and receive personal messages.
- 1
Ask the recipient to open WhatsApp
When updated terms are pending, WhatsApp shows an acceptance prompt the next time the user opens the app. The user just needs to open WhatsApp and accept.
- 2
If the prompt does not appear automatically
Ask the recipient to navigate to WhatsApp → Settings → Help → Terms and Privacy Policy. If an updated version is pending, it will appear there.
- 3
Retry after acceptance
Once the recipient accepts the terms, retry the message from SparkTG Dashboard → Campaign Logs → select the failed contact → Retry.
Reason 4 — Recipient is using an outdated WhatsApp version
Template messages with interactive buttons, headers, or rich media require a minimum WhatsApp version on the recipient's device. Very old app versions cannot render these message types.
- Android: version 2.21.15.15 or later
- WhatsApp Business (Android): version 2.21.15.15 or later
- iOS: version 2.21.170.4 or later
- WhatsApp Business (iOS): version 2.21.170.4 or later
- KaiOS: version 2.2130.10 or later
- WhatsApp Web: version 2.2132.6 or later
- 1
Ask the recipient to update WhatsApp
Android: Google Play Store → My Apps → WhatsApp → Update. iOS: App Store → search WhatsApp → Update.
- 2
Retry after update
Most delivery failures caused by app version resolve immediately after an update. Retry from SparkTG Dashboard → Campaign Logs.
Outdated app versions are more common in regions with limited connectivity or older Android devices. For these segments, consider plain text templates without interactive buttons as a fallback.
Reason 5 — Meta's per-user marketing message frequency cap
To protect users from being overwhelmed by business messages, Meta limits how many marketing template messages a single user can receive across all businesses within a set time window. This is a per-user, platform-wide cap — it applies even if your business has never messaged that contact before.
This cap is invisible to businesses — you cannot know in advance whether a contact has hit their limit. It is enforced entirely by Meta and resets within 24 hours.
- There is no way to bypass this cap — it is a Meta platform restriction.
- Affected contacts become reachable again once the cap resets, typically within 24 hours.
- Retrying immediately will not help — wait for the reset before re-attempting.
- Utility and authentication template categories are not subject to this frequency cap. Recategorising eligible messages as utility templates can improve deliverability.
Frequently asked questions
- Is this error caused by SparkTG? No — SparkTG successfully transmits the message to Meta's API. The undeliverable status is returned by WhatsApp's delivery layer based on the recipient's account state or Meta's own policies.
- Will I be charged for undelivered messages? WhatsApp charges are per conversation session, not per individual message. If no session was opened, no conversation charge applies. Review SparkTG Dashboard → Billing → Usage for a per-contact breakdown.
- Can I retry failed messages automatically? Yes — go to SparkTG Dashboard → Campaign Settings → Retry Policy to schedule automatic retries for failed contacts after a defined interval.
- How do I see which contacts failed and why? SparkTG Dashboard → Campaigns → select your campaign → Delivery Report. Each failed contact shows the specific error code and reason returned by Meta.
How to reduce undeliverable rates on future campaigns
- Only message contacts who have actively opted in to receive WhatsApp messages from your business — this is a Meta policy requirement and the single biggest factor in delivery rates.
- Validate your contact list before every campaign using SparkTG's built-in number validation tool.
- Avoid sending high-frequency marketing templates to the same audience in a short window — this accelerates the per-user marketing cap.
- Use utility or authentication template categories wherever appropriate — these are exempt from the marketing frequency cap.
- Monitor your template quality rating regularly in SparkTG → WhatsApp → Channel Status. A declining quality score is an early warning sign of rising undeliverable rates.
If undeliverable rates on a campaign exceed 10%, review your opt-in collection process before sending further campaigns. Raise a support ticket from SparkTG Dashboard → Help → Contact Support with your Campaign ID if you need a detailed delivery analysis from our team.
Frequently asked questions
What does 'Message Undeliverable' mean in a SparkTG WhatsApp campaign?
How do I know if a recipient has blocked my WhatsApp Business number?
What WhatsApp app versions are required to receive template messages?
What is Meta's per-user marketing frequency cap and can I bypass it?
Should I retry undeliverable messages immediately?
How can I reduce undeliverable rates on future WhatsApp campaigns?
Was this article helpful?
Still stuck? Contact our support team →