Why messages fail and how to fix them

When a message fails, AIsoule shows a red error indicator. Here are the most common causes and fixes.

Common failure reasons

1. Phone number doesn't have WhatsApp

Error: "Recipient not on WhatsApp" or "Invalid WhatsApp number"

Fix: The number you're trying to reach doesn't have WhatsApp installed. Verify the number is correct and has WhatsApp active.

2. Outside 24-hour window (no template used)

Error: "Message failed to send" or "Outside service window"

Fix: You can only send free-form messages within 24 hours of the customer's last message. Use a template message instead.

3. Template not approved

Error: "Template not found" or "Template status invalid"

Fix: Check Settings → Templates. The template must show "Approved" status. If it's "Pending" or "Rejected", you can't use it.

4. Invalid phone number format

Error: "Invalid parameter" or "Phone number format error"

Fix: Phone numbers must include the country code without + or 00. Example: 919876543210 (India), 14155551234 (US).

5. Account disconnected

Error: "Authentication failed" or "Token expired"

Fix: Go to Settings → WhatsApp Accounts → click "Test Connection". If it fails, reconnect your account or generate a new access token.

6. Messaging limit reached

Error: "Rate limit exceeded" or "Messaging limit reached"

Fix: Meta limits how many unique contacts you can message per day. New accounts start at 250/day and increase with good quality. Wait 24 hours or improve your quality rating.

7. Number blocked by recipient

Error: "Recipient unavailable" or "User blocked"

Fix: The recipient has blocked your business number. You cannot send messages to users who have blocked you.

8. Media too large

Error: "Media size exceeds limit"

Fix: WhatsApp limits: Images (5MB), Videos (16MB), Documents (100MB), Audio (16MB). Compress your file and try again.

How to retry failed messages

In a conversation

Click the retry icon next to the failed message to resend it.

In a campaign

Go to the campaign detail page → click "Retry Failed" to resend to all failed recipients.

Preventing failures

1. Validate phone numbers before importing — ensure they have country codes
2. Use templates for first-time messages
3. Monitor quality rating in Meta Business Suite
4. Don't spam — high block rates will restrict your account
5. Keep access tokens fresh — regenerate if they expire

Still failing?

If messages continue to fail after trying these fixes:

1. Check Meta Platform Status for outages
2. Test your connection in Settings → Accounts → Test Connection
3. Contact our support team via WhatsApp