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

# Whatsapp troubleshooting

> Fix common WhatsApp channel issues — missing replies, delivery failures, webhook problems, session-state issues, and template rejections.

Before debugging, have these ready: your **business number**, the **channel status** in your [OpenCX dashboard](https://platform.open.cx), and a **recent message** if available.

<Tip>
  Looking for setup steps? See [Create WhatsApp Agent](/whatsapp/connect-whatsapp). For routing logic, see [WhatsApp Flow](/whatsapp/messaging-rules). For reply window and templates, see [Messaging Rules](/whatsapp/whatsapp-rules).
</Tip>

## Common Troubleshooting Scenarios

| Symptom                                                                | Likely cause                                                           | What to do                                                                                                                                                                                                                                                        |
| ---------------------------------------------------------------------- | ---------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **No AI reply**                                                        | Autopilot or per-number AI toggle is off                               | Check both: org-level [Autopilot](https://platform.open.cx/settings/autopilot) **and** the per-number toggle on [Channels → WhatsApp](https://platform.open.cx/channels/whatsapp).                                                                                |
| **Message not in inbox**                                               | Webhook subscription missing                                           | Go to [Channels → WhatsApp](https://platform.open.cx/channels/whatsapp) and click **Subscribe to webhooks** if the warning appears next to the number.                                                                                                            |
| **Outbound message fails**                                             | Delivery error from the platform                                       | Check the [error logs](https://platform.open.cx/channels/whatsapp/error-logs) for details. Common causes: invalid recipient number, rate limits, or account restrictions.                                                                                         |
| **Template not sent**                                                  | Template not approved or parameters missing                            | Verify the template is approved under [Channels → WhatsApp](https://platform.open.cx/channels/whatsapp) → **View templates**. Check that all required parameters are filled.                                                                                      |
| **Message shows as sent in OpenCX but the customer never receives it** | Meta accepted the request but did not deliver it                       | Check the [error logs](https://platform.open.cx/channels/whatsapp/error-logs) first. If you see send success without a corresponding delivery signal, review the template category, recent message volume, and any Meta account restrictions in Business Manager. |
| **AI stops replying after a human handled the conversation**           | The WhatsApp session is still open or handed off in the helpdesk layer | If you use Zendesk Sunshine, make sure the conversation is fully ended in Zendesk, not only marked solved. When testing, start with a fresh customer message after the prior session has closed.                                                                  |

<Info>
  If messages are not arriving in your dashboard, the problem is almost always the **webhook subscription** — not a platform outage.
</Info>

## Frequently Asked Questions

<AccordionGroup>
  <Accordion title="Why do WhatsApp messages fail even though the template is approved?" icon="rectangle-list">
    Approval is required, but it is not the only delivery check. Meta can still limit or suppress delivery based on template category, conversation health, recipient behavior, or account restrictions. If a template is business-critical, prefer a utility-style template where appropriate and check delivery logs after each send.
  </Accordion>

  <Accordion title="Why did the AI reply in OpenCX but not on the customer's phone?" icon="triangle-exclamation">
    That usually means OpenCX generated the reply, but WhatsApp did not complete delivery. Treat this as a delivery issue first, not an AI issue. Check the WhatsApp logs and your Meta Business Manager status before changing prompts or Autopilot settings.
  </Accordion>
</AccordionGroup>

## Limits

| Area                        | Detail                                                                           |
| --------------------------- | -------------------------------------------------------------------------------- |
| **Inbound delivery**        | **Instant** via webhook.                                                         |
| **AI reply**                | Typically **seconds** after a short debounce delay.                              |
| **Session auto-resolution** | Approximately **12 hours** of inactivity (org-level overrides possible).         |
| **Reply window**            | **24 hours** from last customer message. After that, only templates can be sent. |

## Error Logs

View delivery errors and API failures at **[Channels → WhatsApp → Logs](https://platform.open.cx/channels/whatsapp/error-logs)**. Filter by date range, business number, error type, or recipient phone number.

***

## Related Documentation

<CardGroup cols={2}>
  <Card title="Create WhatsApp Agent" icon="plug" href="/whatsapp/connect-whatsapp">
    Re-check OAuth, number registration, and webhook subscription.
  </Card>

  <Card title="WhatsApp Flow" icon="route" href="/whatsapp/messaging-rules">
    Re-check session matching and delivery path.
  </Card>

  <Card title="Messaging Rules" icon="scale-balanced" href="/whatsapp/whatsapp-rules">
    Reply window expired? Check template requirements.
  </Card>

  <Card title="Autopilot And Topics" icon="sliders" href="/handoff/topics">
    Verify channel-level Autopilot and topic rules.
  </Card>
</CardGroup>