> ## Documentation Index
> Fetch the complete documentation index at: https://documents.xobito.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Message Delivery Issues

> Why messages fail to deliver — and how to fix each reason.

When a message doesn't reach the recipient, Xobito shows a **failed** status along with a reason from Meta. This page explains every reason and what to do about it.

## 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                                   |

<Tip>
  Ticks in chat follow WhatsApp's conventions:

  * **single grey tick** = `sent`
  * **double grey tick** = `delivered`
  * **double blue tick** = `read`
</Tip>

## 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:**

<Steps>
  <Step title="Check the format">
    Number must start with `+` followed by country code and number, no spaces or dashes. Example: `+14155551234`.
  </Step>

  <Step title="Verify the number has WhatsApp">
    Ask the recipient directly, or try messaging them from your personal WhatsApp first.
  </Step>

  <Step title="Update the contact">
    Fix the number in **Contacts → (contact) → Edit**.
  </Step>
</Steps>

### 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:**

<Steps>
  <Step title="Use a template instead">
    Click **Send Template** in the chat and pick an approved template.
  </Step>

  <Step title="Wait for the contact to reply">
    Once they reply to your template, the 24-hour session re-opens and you can send anything for the next 24 hours.
  </Step>
</Steps>

See [Key Concepts → Session Window](/key-concepts#session--24-hour-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:**

<Steps>
  <Step title="Stop sending non-essential campaigns immediately">
    Every failure while in a bad state digs you deeper.
  </Step>

  <Step title="Review recent campaigns">
    Which templates were used? Any spammy copy or untargeted sends?
  </Step>

  <Step title="Clean your contact list">
    Remove contacts who haven't opted in recently.
  </Step>

  <Step title="Let the rating recover">
    Meta re-evaluates every few days. Consistent good sending gets you back to **Green**.
  </Step>
</Steps>

<Warning>
  Ignoring a **Red** rating can lead to Meta suspending your phone number.
</Warning>

### 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:**

<Steps>
  <Step title="Wait for the rolling window to reset">
    The limit rolls forward hour by hour — more capacity frees up through the day.
  </Step>

  <Step title="Request a tier upgrade">
    In Meta Business Manager, request a move to the next tier once you've maintained good quality.
  </Step>
</Steps>

### 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](/troubleshooting/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:

<Steps>
  <Step title="Spread the send">
    Schedule the campaign across a longer window — e.g. 1 hour instead of 5 minutes.
  </Step>

  <Step title="Add a second phone number">
    Load balance across multiple numbers in your WABA.
  </Step>
</Steps>

### 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:**

<Steps>
  <Step title="Open the template">
    Count the `{{n}}` placeholders.
  </Step>

  <Step title="Check your CSV or chat send">
    Make sure each row provides exactly that many values in the right columns.
  </Step>
</Steps>

### 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:**

<Steps>
  <Step title="Make sure the media is public">
    The URL must be reachable without a login.
  </Step>

  <Step title="Check file size">
    Images ≤ 5 MB, video ≤ 16 MB, documents ≤ 100 MB.
  </Step>

  <Step title="Use Xobito's media library">
    Upload the file into Xobito instead of linking an external URL — it's always reachable.
  </Step>
</Steps>

### 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

<Steps>
  <Step title="Open the campaign report">
    Campaigns → click the campaign name.
  </Step>

  <Step title="Click the 'Failed' tab">
    A list of failed recipients with failure reasons is shown.
  </Step>

  <Step title="Download the failure CSV">
    For very large failures, click **Export** to get a CSV you can analyse.
  </Step>
</Steps>

## 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

<Steps>
  <Step title="Open the campaign" />

  <Step title="Click 'Retry failed'">
    Xobito creates a new campaign targeting only the failed recipients. Review and launch.
  </Step>
</Steps>

## 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](mailto: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.

Include the campaign ID, affected phone number, and a screenshot of the error.

## Related

<CardGroup cols={2}>
  <Card title="Template Rejection" icon="file-circle-xmark" href="/troubleshooting/template-rejection">
    Why Meta rejects templates.
  </Card>

  <Card title="Contact Issues" icon="address-book" href="/troubleshooting/contact-issues">
    Duplicate, missing, or malformed contacts.
  </Card>

  <Card title="Common Issues" icon="stethoscope" href="/troubleshooting/common-issues">
    Top 10 general issues.
  </Card>
</CardGroup>