Troubleshooting common WhatsApp campaign errors

When sending WhatsApp campaigns through SparkTG, you may occasionally run into errors that prevent messages from being delivered. Most of these are caused by Meta's (WhatsApp's) own policies, template configuration issues, or account-level restrictions. This guide walks through each error type, what it means, and exactly how to fix it.

1. Message not delivered — undeliverable number

If a campaign message fails and the log shows a delivery failure against a specific contact, the recipient's number likely has one of the following issues:

• The number is not registered on WhatsApp or the account has been deactivated.
• The country code (+91 for India, etc.) is missing or incorrect in your contact list.
• The recipient is using an outdated version of WhatsApp that cannot receive Business API messages.
• The recipient has not accepted WhatsApp's latest Terms of Service — they need to open WhatsApp and accept the updated terms before messages can be delivered.

1. 1

   Verify contact format

   In SparkTG → Contacts, open the affected contact and confirm the number includes the full country code with no spaces or special characters. Example: 919876543210 (not 09876543210).

2. 2

   Remove invalid numbers from the campaign

   Use the Validate Numbers option before sending a campaign. SparkTG will flag numbers not registered on WhatsApp so you can exclude them before the send.

3. 3

   Ask the recipient to update WhatsApp

   If the contact is reachable via another channel, ask them to update the WhatsApp app and accept the latest Terms of Service, then retry the message.

2. Marketing message blocked by Meta quality restrictions

Meta actively monitors the quality of marketing messages sent through the Business API. If your templates have a low quality rating — typically because recipients are blocking or reporting your messages — Meta will temporarily restrict further delivery and ask you to retry after a cooling-off period.

• Review your template content — ensure it is relevant, personalised, and expected by the recipient.
• Audit your contact list — remove contacts who have not explicitly opted in to receive WhatsApp messages from your business.
• Wait for the cooldown period to pass (usually 24–48 hours) before retrying the campaign.
• Check your template quality rating in Meta Business Manager → WhatsApp Manager → Message Templates.

3. Contact unreachable — Meta experiment restriction

Since mid-2023, Meta has been running an ongoing experiment where a small percentage of WhatsApp users do not receive marketing template messages from businesses unless the user has initiated a conversation first. This shows up in SparkTG campaign logs as a delivery failure on specific contacts.

• Only marketing category templates are affected. Utility and authentication templates are not impacted.
• If a contact falls under this experiment, the only way to send them a marketing message is to first receive an inbound message from them.
• Once they send you a message, you have a 24-hour window to send any template message including marketing ones.
• Reach out to the affected contacts via another channel (email, SMS, phone call) and ask them to send you a WhatsApp message to initiate the session.

4. Campaign paused — messaging limit reached

WhatsApp enforces tiered daily messaging limits on all Business API accounts: 1,000 → 10,000 → 100,000 unique contacts per 24 hours. If your campaign exceeds your current tier limit, messages will stop sending until the 24-hour window resets.

1. 1

   Check your current messaging tier

   SparkTG Dashboard → WhatsApp → Channel Status. Your current limit and usage for the rolling 24-hour window are displayed here.

2. 2

   Wait for the window to reset

   The 24-hour window is rolling, not a fixed midnight reset. Once it clears, the paused campaign will resume automatically if auto-retry is enabled.

3. 3

   Increase your messaging tier over time

   Meta automatically upgrades your tier based on consistent high-volume sending and a good quality rating. There is no manual upgrade request — maintain high delivery rates and low block rates to tier up faster.

5. Account locked or restricted by Meta

If your WhatsApp Business Account (WABA) has been flagged for policy violations, Meta may restrict or disable it entirely. SparkTG will display an account-level error across all campaigns when this happens.

1. 1

   Check account status in Meta Business Manager

   Log in to business.facebook.com → Settings → WhatsApp Accounts. If restricted, you will see a banner with the reason and an option to appeal.

2. 2

   Submit an appeal to Meta

   Click Request Review in Meta Business Manager. Reviews typically take 24–48 hours. You will receive an email notification once a decision is made.

3. 3

   Contact SparkTG support if restriction is lifted but error persists

   Once Meta lifts the restriction, it can take up to 2 hours for the change to propagate to the SparkTG platform. If the error continues after that window, raise a support ticket with your WABA ID.

6. Template errors — formatting, variables, and approval issues

Template errors are the most common category of WhatsApp campaign failures. They typically occur due to missing variables, incorrect formatting, or a template that has been paused or rejected by Meta.

• Blank or missing variables: Every {{variable}} placeholder in your template must have a value supplied at send time. If any variable is empty, the message will fail. Check your contact data to ensure all required fields are filled.
• Missing or invalid media: If your template has an image, video, or document header, a valid media file must be provided for every send. PDF is the only supported format for document headers.
• Newlines or tabs in variables: Do not include line breaks, tab characters, or more than four consecutive spaces inside any template variable value — Meta will reject the message.
• Template paused by Meta: Meta automatically pauses templates with a low quality rating. Go to WhatsApp Manager → Message Templates and check the status. You can resubmit the content as a new template if the original is permanently disabled.
• Template name not found: If sending via the SparkTG API, verify the template name is an exact match — it is case-sensitive. Newly approved templates can take up to 30 minutes to become available via API.

7. Messages failing due to payment or billing issues

WhatsApp charges per conversation (not per message). If Meta cannot charge your payment method, outbound messages will fail at the API level with a payment-related error code.

1. 1

   Check payment method in Meta Business Manager

   Go to business.facebook.com → Settings → Payments. Verify that a valid payment method is on file and no invoices are overdue.

2. 2

   Verify SparkTG account credits

   SparkTG Dashboard → Billing. Ensure your SparkTG account balance is sufficient for the campaign volume. Campaigns will not dispatch if the account credit falls below the minimum threshold.

3. 3

   Re-verify onboarding if recently migrated

   If you recently migrated your WhatsApp number from another provider to SparkTG, ensure the Business Verification and payment setup steps in Meta Business Manager were completed in full. Incomplete migrations can cause persistent payment errors.

8. Media upload errors

If your template includes a media header and the upload fails, the entire campaign send will be blocked. WhatsApp has strict requirements on media format and codec.

• Images: Must be JPEG or PNG, 8-bit colour, RGB or RGBA mode. Maximum file size 5 MB.
• Videos: Must use H.264 video codec and AAC audio codec. Only one audio stream is allowed. Maximum file size 16 MB.
• Documents: Only PDF format is supported for template message headers. Maximum file size 100 MB.
• If a video meets the size limit but still fails, the codec is likely the issue. Re-encode the video using a tool like HandBrake (H.264 + AAC) and re-upload.

9. Message text too long

WhatsApp enforces strict character limits on every part of a template. If any section exceeds its limit, the message will not send.

• Header text: 60 characters maximum.
• Body text: 1,024 characters maximum.
• Footer text: 60 characters maximum.
• Call-to-action button URL: 2,000 characters maximum.
• Formatting symbols (*, _, ~) count toward the character limit.

10. Campaign blocked — insufficient credits

• Go to SparkTG Dashboard → Billing and check your available credit balance.
• Top up your account before re-launching the campaign.
• Verify that all contacts in your campaign list have valid country codes — invalid numbers consume credits on failed delivery attempts.