WhatsApp Issues
Troubleshooting guide for WhatsApp-related problems.
Connection Issues
Cannot Connect to Meta
| Issue | Solution |
|---|---|
| OAuth window blocked | Disable popup blocker for Voxvaani domain and retry |
| No businesses found | Set up a WhatsApp Business Account in Meta Business Manager |
| Permission denied | Ensure you have admin access to the Meta Business Manager |
| Connection fails | Disconnect and reconnect your Meta account |
⚠️ Meta's Review Process
Meta’s review process is beyond Voxvaani’s control. Common delays and their resolutions:
- WABA verification: Meta requires business verification (legal business name, address, website, etc.). Processing takes 2-7 business days. Incomplete documentation is the most common reason for rejection.
- Template review: New templates are reviewed manually by Meta. Approval typically takes 24-48 hours but can extend to 5 business days during high volume. Templates with promotional language face stricter scrutiny.
- Phone number verification: Meta sends a verification code via SMS or voice call to your registered number. The code expires in 10 minutes. If you miss it, request a new one.
Pro tips for faster approval:
- Submit templates as “Utility” rather than “Marketing” whenever possible (faster review, lower credit cost)
- Use clear, non-promotional template language (e.g., “Your order #
{{1}}has shipped” instead of “Don’t miss our amazing sale!”) - Ensure your business website matches the information in your Meta Business Manager profile
WABA Verification Issues
If your WhatsApp Business Account (WABA) verification is stuck or rejected:
- Verify your business details in Meta Business Manager exactly match your legal business registration
- Upload clear, legible business documents (Certificate of Incorporation, GST certificate, business license)
- Ensure your business website is live, loads over HTTPS, and clearly displays your business name
- If your WABA is restricted, check the Account Quality section in Meta Business Manager for the specific reason and resolution steps
- Re-verification typically takes 3-5 business days after submitting corrected documents
Template Issues
Templates Not Syncing
| Issue | Solution |
|---|---|
| Templates not appearing | Click Sync Templates on the Templates page |
| Templates stuck in “Pending” | Wait for Meta review (can take 24-48 hours, up to 5 business days) |
| Template rejected | Review Meta’s policy guidelines and create a new template with corrected content |
Template Variables
- Ensure variable names in campaigns match the template exactly —
{{1}},{{2}}, etc. - Template variables are case-sensitive
- Some special characters may not be supported — avoid emojis, HTML tags, or special formatting in variable values
- If a template has header parameters (image, video, document), the media file must be hosted on an HTTPS URL accessible without authentication
Campaign Issues
Messages Not Sending
| Issue | Solution |
|---|---|
| Insufficient WhatsApp balance | Purchase more messages — check cost: marketing=3 credits, utility=1 credit |
| Template not approved | Check template status on the Templates page — only “Approved” templates can be sent |
| Contact opted out | Respect opt-out preferences — cannot send to opted-out contacts |
| Invalid phone number | Verify the contact’s phone number is in E.164 format with country code |
Low Delivery Rate
- Verify contact phone numbers are active WhatsApp users (not all phone numbers have WhatsApp)
- Check Meta rate limits — new WABA numbers (less than 2 weeks old) are throttled. Start with 50-100 messages/day and ramp up.
- Ensure contacts have opted in — messages to non-opted-in users may be blocked
- Check your WABA quality rating (GREEN > YELLOW > RED). RED ratings face severe delivery restrictions.
Campaign Stuck or Paused
- Check campaign status — paused campaigns do not send
- Resume if needed
- Check for balance issues — campaigns pause when balance reaches zero
- Verify the template is still approved (templates can be rejected retroactively by Meta)
Webhook Configuration Issues
If incoming WhatsApp messages are not appearing in the inbox:
- Verify webhook is properly configured in Meta’s WhatsApp settings
- The webhook callback URL must be publicly accessible (HTTPS required)
- Check that the verify token matches between Meta and Voxvaani configuration
- After configuration changes, wait up to 5 minutes for webhook re-registration
- Send yourself a test message from another phone to confirm webhook delivery
Media Message Issues
Media Not Sending or Not Displaying
| Issue | Solution |
|---|---|
| File too large | Images: 16 MB; Videos: 64 MB; Audio: 16 MB; Documents: 16 MB (Meta limits) |
| Unsupported format | Check supported MIME types (JPEG, PNG, MP4, MP3, PDF, etc.) |
| URL not accessible | Media URL must be HTTPS and publicly accessible without authentication |
| Upload timeout | Large files may timeout. Use /whatsapp/upload first, then reference the mediaId in send calls |
Inbox Issues
Messages Not Appearing
- Refresh the inbox page
- Verify your WhatsApp number is active (not disconnected or expired)
- Check webhook configuration (see above)
- Confirm the message was sent to the correct phone number