Why is my WhatsApp template message showing 'undeliverable'?

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.

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. 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. 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. 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. 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. 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. 1

   Ask the recipient to update WhatsApp

   Android: Google Play Store → My Apps → WhatsApp → Update. iOS: App Store → search WhatsApp → Update.

2. 2

   Retry after update

   Most delivery failures caused by app version resolve immediately after an update. Retry from SparkTG Dashboard → Campaign Logs.

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.

• 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.