Message status codes
Every message you send goes through these statuses.| Status | Meaning | What it means for you |
|---|---|---|
sent | Xobito accepted and forwarded to Meta | Wait for delivery |
delivered | Meta confirms phone received it | Message on recipient’s device |
read | Recipient opened the message | |
failed | Delivery failed (see failure reason) | Check phone number, template status, session window |
pending | Awaiting processing | Usually transient |
Why messages fail
Every failed message has a failure reason visible by hovering the red exclamation mark in chat or clicking the row in a campaign report.1. Invalid phone number
Reason text: “Invalid WhatsApp user” or “Number not on WhatsApp”. What it means: The number you sent to is not registered with WhatsApp, or the format is wrong. Fix:Check the format
Number must start with
+ followed by country code and number, no spaces or dashes. Example: +14155551234.Verify the number has WhatsApp
Ask the recipient directly, or try messaging them from your personal WhatsApp first.
2. Recipient doesn’t have WhatsApp
Reason text: “User is not a WhatsApp contact”. Fix: There’s nothing you can do — the person isn’t a WhatsApp user. Remove them from campaigns to avoid repeated failures and wasted attempts.3. Outside the 24-hour session window
Reason text: “Message outside 24-hour window” or “Session not active — template required”. What it means: You tried to send a free-form (non-template) message to a contact who hasn’t messaged you in the last 24 hours. Fix:
See Key Concepts → Session Window.
4. Quality rating issues
Reason text: “Quality rating low — messaging paused” or “Limited sending”. What it means: Meta tracks how often your messages are blocked or reported by recipients. If your quality rating drops to Red, Meta temporarily blocks new sends. Fix:Stop sending non-essential campaigns immediately
Every failure while in a bad state digs you deeper.
5. Messaging tier limit hit
Reason text: “Daily tier limit reached”. What it means: Meta caps daily sends by tier (1k, 10k, 100k, unlimited). You’ve sent your max for the 24-hour period. Fix:Wait for the rolling window to reset
The limit rolls forward hour by hour — more capacity frees up through the day.
6. Template not approved
Reason text: “Template is not approved” or “Template status: REJECTED”. Fix: You can’t send a template until Meta approves it. See Template Rejection.7. Rate limits (per second / per minute)
Reason text: “Rate limit exceeded — retry later”. What it means: WhatsApp has per-second and per-minute caps (usually 80 messages/second per phone number). Very large campaigns can briefly hit them. Fix: Xobito automatically throttles and retries — most rate-limit failures recover on their own. If it happens repeatedly:8. Template parameter count mismatch
Reason text: “Template variable count does not match”. What it means: Your template expects, say, 3 variables ({{1}}, {{2}}, {{3}}) but the campaign or chat provided a different number.
Fix:
9. Media fetch failed
Reason text: “Media not downloadable” or “Media URL returned 4xx”. What it means: For templates with a media header (image, video, PDF), Meta couldn’t download the file from the URL you provided. Fix:10. Business policy violation
Reason text: “Message violates WhatsApp Business policy”. What it means: Content like regulated products (alcohol, weapons, gambling in some countries), misinformation, or adult content was detected. Fix: Remove the offending content. If you believe Meta flagged incorrectly, appeal via Meta Business Manager.11. Recipient blocked your number
Reason text: “User has blocked this business”. Fix: The recipient must unblock you. Consider removing them from contact lists and campaigns.12. Account unverified
Reason text: “Business not verified — sending limited”. What it means: Until your business is verified in Meta Business Manager, you’re limited to low messaging tiers and restricted templates. Fix: Complete business verification in Meta Business Manager. It usually takes a few business days.Viewing failure reasons
For a single chat message
Hover the red exclamation mark next to the message bubble. A tooltip shows the reason.For a campaign
Retrying failed messages
Some failures are transient (rate limits, brief Meta outages). Xobito automatically retries them up to 3 times with back-off. For permanent failures (wrong number, blocked contact), manual retry won’t help. Fix the root cause first.Manual retry in chat
Click the three-dot menu on the failed message → Retry.Retry campaign failures
Monitoring delivery health
Campaign reports show a delivery funnel (sent → delivered → read → failed) with percentages. Watch the delivery rate over time — a sudden drop signals a quality issue or WABA problem. Under Analytics → Delivery, you can see trends across days and phone numbers.When to contact support
Contact support@xobito.com if:- Every single message from a specific phone number fails with no clear reason.
- Your WABA status flips between connected and disconnected repeatedly.
- Failure reason is generic (“unknown error”) and persists.
Related
Template Rejection
Why Meta rejects templates.
Contact Issues
Duplicate, missing, or malformed contacts.
Common Issues
Top 10 general issues.