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

# WhatsApp troubleshooting — common issues and solutions

> Fix common WhatsApp issues — message delivery failures, template rejections, quality rating drops, connection problems, and more.

## Messages not delivering

<AccordionGroup>
  <Accordion title="Check the number format">
    WhatsApp requires numbers in **international format** with country code, no leading zeros, no dashes or spaces:

    * Correct: `14155551234` (US)
    * Correct: `447911123456` (UK)
    * Wrong: `(415) 555-1234`
    * Wrong: `07911 123456`

    In HoopAI, check the contact's phone field and ensure it includes the country code.
  </Accordion>

  <Accordion title="Contact doesn't have WhatsApp">
    Not every phone number has WhatsApp. If the number is a landline or the person hasn't installed WhatsApp, messages will fail. HoopAI will show a delivery failure indicator.
  </Accordion>

  <Accordion title="24-hour window expired">
    If you're sending a free-form message and the [24-hour window](/conversations/whatsapp-24hr-window) has closed, the message will fail. Use an approved template instead.
  </Accordion>

  <Accordion title="Rate limit reached">
    If you've hit your daily sending limit (based on your [tier level](/conversations/whatsapp-templates-advanced#template-rate-limits)), messages will queue or fail. Wait 24 hours or request a tier upgrade by sending more messages with high quality.
  </Accordion>

  <Accordion title="Meta account issue">
    Check your Meta Business Suite for any account restrictions, payment issues, or policy violations that may block sending.
  </Accordion>

  <Accordion title="Number blocked by recipient">
    If a contact has blocked your WhatsApp number, messages will show as sent but never delivered (single gray check mark). You won't receive an explicit "blocked" notification.
  </Accordion>
</AccordionGroup>

## Template rejected

<AccordionGroup>
  <Accordion title="Content violates WhatsApp policies">
    Templates cannot contain:

    * Misleading or deceptive content
    * References to prohibited products (alcohol, tobacco, weapons, adult content, gambling)
    * Requests for sensitive personal data
    * Threatening or abusive language

    Review [Meta's commerce policy](https://www.whatsapp.com/legal/commerce-policy/) and rewrite your template.
  </Accordion>

  <Accordion title="Wrong category selected">
    If you submit a promotional message as "utility", Meta will reject it. Choose the correct category:

    * **Marketing** — promotions, offers, re-engagement
    * **Utility** — transactional updates, confirmations, reminders
    * **Authentication** — OTPs and verification codes
  </Accordion>

  <Accordion title="Missing or invalid variables">
    Ensure all dynamic content uses proper syntax: `{{1}}`, `{{2}}`, etc. Provide realistic sample values when submitting.
  </Accordion>

  <Accordion title="Too similar to a previously rejected template">
    Don't resubmit the same template with minor word changes. Make meaningful changes to address the rejection reason.
  </Accordion>

  <Accordion title="Template is too vague">
    Meta may reject templates that are too generic or don't clearly communicate their purpose. Be specific about what the message is for.
  </Accordion>
</AccordionGroup>

See the [advanced templates guide](/conversations/whatsapp-templates-advanced) for detailed rejection reasons and fixes.

## Quality rating dropped

<AccordionGroup>
  <Accordion title="High block rate">
    If many recipients block your number after receiving messages, your quality drops. Fix:

    * Only message contacts who have opted in
    * Reduce message frequency
    * Make content more relevant and valuable
    * Include clear opt-out instructions
  </Accordion>

  <Accordion title="High report rate">
    Recipients reporting your messages as spam damages quality. Common causes:

    * Messaging contacts who don't recognize your brand
    * Sending too frequently
    * Content that feels spammy or irrelevant
  </Accordion>

  <Accordion title="How to recover">
    1. **Pause** all marketing campaigns immediately
    2. **Review** which templates have low quality ratings
    3. **Delete** poorly performing templates
    4. **Reduce volume** — only send to your most engaged contacts
    5. **Wait** — quality ratings recover over 7 days of improved behavior
    6. **Resume gradually** — slowly increase volume while monitoring quality
  </Accordion>

  <Accordion title="Template paused by Meta">
    If a specific template's quality drops to Red, Meta may **pause** it for 3-6 hours. If quality doesn't improve, the template is **disabled**. Create a new, improved template to replace it.
  </Accordion>
</AccordionGroup>

## Can't connect WhatsApp

<AccordionGroup>
  <Accordion title="Meta Business account not verified">
    WhatsApp Business API requires a **verified** Meta Business account. Go to [Meta Business Suite](https://business.facebook.com/) > **Settings > Business verification** to start or check the status.

    Verification requires:

    * Business registration documents
    * Utility bill or bank statement matching the business name
    * Typically takes 1-5 business days
  </Accordion>

  <Accordion title="Phone number already registered">
    If your number is already connected to the WhatsApp Business API through another platform, you must disconnect it there first. A number can only be registered with one Cloud API provider at a time (unless using [coexistence](/conversations/whatsapp-coexistence) with the WhatsApp Business App).
  </Accordion>

  <Accordion title="Verification code not received">
    During setup, you'll receive an SMS or voice call with a verification code. If it doesn't arrive:

    * Make sure the phone number can receive SMS or calls
    * Try the voice call option instead of SMS
    * Check if the number has any call/SMS blocking enabled
    * Wait 5 minutes and retry
  </Accordion>

  <Accordion title="Business Manager permissions">
    The Meta user connecting WhatsApp must have **Admin** access to the Meta Business account. Check permissions in Meta Business Suite > Settings > People.
  </Accordion>

  <Accordion title="Two-step verification blocking connection">
    If two-step verification (2FA PIN) was previously set on the WhatsApp account, you'll need to enter or reset the PIN during API registration. If you don't know the PIN, you'll need to wait 7 days for the PIN to reset, or use the email address associated with the 2FA to reset it.
  </Accordion>
</AccordionGroup>

## Contacts not receiving messages

<AccordionGroup>
  <Accordion title="Opt-in requirements">
    WhatsApp requires that contacts **opt in** to receive business messages. If a contact hasn't opted in, you should not send them messages — and if recipients report you, your quality rating suffers.

    Valid opt-in methods:

    * Contact messages you first on WhatsApp
    * Contact fills out a form with WhatsApp consent checkbox
    * Contact opts in via SMS or email
    * In-person or phone verbal consent (with documentation)
  </Accordion>

  <Accordion title="DND / do-not-disturb settings">
    Check if the contact has been marked as DND (Do Not Disturb) in HoopAI. Go to the contact record and check their communication preferences.
  </Accordion>

  <Accordion title="Invalid phone number">
    The contact's number may be formatted incorrectly, disconnected, or not a mobile number. Verify the number includes the correct country code and is a valid mobile number.
  </Accordion>
</AccordionGroup>

## WhatsApp number disconnected

<AccordionGroup>
  <Accordion title="Policy violation">
    Meta may disconnect your number if you violate WhatsApp's business policies. Common violations:

    * Sending spam or unsolicited messages
    * Consistently low quality rating
    * Using WhatsApp for prohibited use cases

    **To reactivate**: Review the violation notice in Meta Business Suite, address the issue, and submit an appeal.
  </Accordion>

  <Accordion title="Payment failure">
    If your Meta payment method fails, API access may be suspended. Update your payment method in Meta Business Suite.
  </Accordion>

  <Accordion title="Accidental disconnection">
    If you accidentally disconnected the number in HoopAI or Meta Business Suite, reconnect by going through the WhatsApp setup flow again in **Settings > WhatsApp**.
  </Accordion>
</AccordionGroup>

## Webhook errors

<AccordionGroup>
  <Accordion title="Webhook not receiving events">
    If HoopAI isn't receiving inbound WhatsApp messages:

    1. Check that the webhook URL is correctly configured in Meta Business Suite
    2. Verify the webhook verification token matches
    3. Check for any firewall or network issues blocking Meta's webhook calls
    4. Review Meta's webhook status in the App Dashboard
  </Accordion>

  <Accordion title="Duplicate messages">
    If you're receiving duplicate messages, check for:

    * Multiple webhook subscriptions pointing to the same endpoint
    * Retry logic processing the same event twice
    * Multiple connected WhatsApp numbers receiving the same message
  </Accordion>
</AccordionGroup>

## Media not loading

<AccordionGroup>
  <Accordion title="File size limits">
    | Media type                 | Max size                           |
    | -------------------------- | ---------------------------------- |
    | Images (JPEG, PNG)         | 5 MB                               |
    | Videos (MP4)               | 16 MB                              |
    | Audio (AAC, MP3, OGG, AMR) | 16 MB                              |
    | Documents (PDF, DOC, etc.) | 100 MB                             |
    | Stickers (WebP)            | 500 KB (static), 100 KB (animated) |

    If your file exceeds these limits, compress it before sending.
  </Accordion>

  <Accordion title="Unsupported format">
    WhatsApp supports specific file formats:

    * **Images**: JPEG, PNG (not HEIC, TIFF, BMP)
    * **Videos**: MP4 with H.264 codec and AAC audio (not MOV, AVI, MKV)
    * **Audio**: AAC, MP3, MP4 audio, OGG with Opus codec, AMR
    * **Documents**: PDF, DOC, DOCX, PPT, PPTX, XLS, XLSX, TXT

    Convert unsupported formats before sending.
  </Accordion>

  <Accordion title="Media URL expired">
    When receiving media from customers, WhatsApp provides a temporary download URL that expires after a period. HoopAI automatically downloads and stores media, but if there's a delay, the URL may expire. Contact support if media attachments appear broken.
  </Accordion>
</AccordionGroup>

## Two-factor verification issues

<AccordionGroup>
  <Accordion title="What is WhatsApp 2FA?">
    WhatsApp two-step verification is a 6-digit PIN that protects your WhatsApp Business account from unauthorized registration. It's separate from your Meta Business account password.
  </Accordion>

  <Accordion title="Forgot the 2FA PIN">
    If you set a 2FA PIN and forgot it:

    1. If you associated an email address, use it to reset the PIN
    2. If no email was set, you must wait **7 days** before you can re-register the number without the PIN
    3. During the 7-day waiting period, the number cannot be registered on any platform
  </Accordion>

  <Accordion title="Managing the 2FA PIN">
    You can update or disable the 2FA PIN in Meta Business Suite under your WhatsApp account settings. We recommend keeping it enabled and storing the PIN securely.
  </Accordion>
</AccordionGroup>

## Migrating WhatsApp number between accounts

<AccordionGroup>
  <Accordion title="Moving to a new Meta Business account">
    To migrate your WhatsApp number to a different Meta Business account:

    1. **Request migration** from the new Meta Business account
    2. **Approve migration** from the current account
    3. The number will be disconnected from the old account and connected to the new one
    4. **Message history** does not transfer — only the number registration moves

    <Warning>
      During migration, there may be a brief period where the number cannot send or receive messages. Plan migrations during low-traffic periods.
    </Warning>
  </Accordion>

  <Accordion title="Moving between HoopAI accounts">
    To move a WhatsApp number between HoopAI accounts:

    1. Disconnect the number from the current account
    2. Connect it to the new account using the standard setup flow
    3. Re-verify the number if prompted
  </Accordion>

  <Accordion title="Risks of migration">
    * Template approvals do **not** transfer — you'll need to recreate and resubmit templates
    * Quality rating and tier level **do** transfer with the phone number
    * Active conversations may be interrupted during the transition
  </Accordion>
</AccordionGroup>

## Reference tables

### Supported file types

| Type     | Formats                                   | Max size                           |
| -------- | ----------------------------------------- | ---------------------------------- |
| Image    | JPEG, PNG                                 | 5 MB                               |
| Video    | MP4 (H.264, AAC)                          | 16 MB                              |
| Audio    | AAC, MP3, OGG (Opus), AMR, MP4 audio      | 16 MB                              |
| Document | PDF, DOC, DOCX, PPT, PPTX, XLS, XLSX, TXT | 100 MB                             |
| Sticker  | WebP                                      | 500 KB (static), 100 KB (animated) |

### Message limits

| Limit                        | Value                            |
| ---------------------------- | -------------------------------- |
| Text message length          | 4,096 characters                 |
| Caption length (on media)    | 1,024 characters                 |
| Template body length         | 1,024 characters                 |
| Template header length       | 60 characters                    |
| Quick reply button text      | 20 characters per button         |
| CTA button text              | 20 characters per button         |
| Maximum buttons per template | 3 quick reply OR 2 CTA           |
| Maximum list items           | 10 sections, 10 rows per section |

### Error codes

| Error    | Meaning                                  | Fix                                           |
| -------- | ---------------------------------------- | --------------------------------------------- |
| `131047` | Re-engagement message outside window     | Use an approved template                      |
| `131026` | Message undeliverable                    | Check number format and WhatsApp registration |
| `130429` | Rate limit hit                           | Wait and retry, or request tier upgrade       |
| `132000` | Template parameter count mismatch        | Check variable mapping in workflow            |
| `132012` | Template not found                       | Verify template name and language code        |
| `133010` | Phone number not registered              | Number isn't registered on WhatsApp           |
| `368`    | Temporarily blocked for policy violation | Review Meta policy notice and appeal          |

## Frequently asked questions

<AccordionGroup>
  <Accordion title="How do I check my current WhatsApp sending tier?">
    In Meta Business Suite, go to **WhatsApp Manager > Phone numbers**. Your current tier and quality rating are displayed next to each number.
  </Accordion>

  <Accordion title="Can I recover a permanently banned number?">
    Permanent bans are rare and typically result from severe policy violations. You can submit an appeal through Meta Business Suite, but success isn't guaranteed. It's often faster to register a new number and rebuild your quality.
  </Accordion>

  <Accordion title="Why do some messages show one check mark but never two?">
    One check mark means the message was sent from HoopAI to WhatsApp's servers. Two check marks mean it was delivered to the recipient's phone. If it stays at one check, the recipient's phone may be off, they may have no internet, or they may have blocked you.
  </Accordion>

  <Accordion title="How long does Meta take to review a template appeal?">
    Template appeals typically take 24-48 hours. In some cases, it may take up to 5 business days.
  </Accordion>

  <Accordion title="Can I use the same template on multiple WhatsApp numbers?">
    Templates are tied to a **WhatsApp Business Account (WABA)**, not a specific phone number. If your numbers are under the same WABA, they share the same templates. Different WABAs require separate template submissions.
  </Accordion>
</AccordionGroup>