# Channel Connection Issues

This guide covers common issues when connecting and maintaining messaging channels (Personal Zalo, Facebook Fanpage, WhatsApp, Webchat) in OmnyBot. For a full status lookup, see [Status Reference](/reference/statuses/).

## Zalo QR Code Expired or Login Failed

**Cause:**
- Each QR login session is single-use and expires shortly after generation (`ZALO_LOGIN_SESSION_NOT_FOUND` or `ZALO_LOGIN_FAILED`).
- Starting QR logins via the Mina assistant is rate-limited to **5 attempts per 10 minutes** per user.

**Fix:**
1. Close the expired QR dialog.
2. Go to **My Channels** and click **Add Channel → Personal Zalo** to generate a fresh QR code (requires `nick:connect`).
3. Scan immediately from the **Zalo** mobile app (**Scan QR**) and confirm login.

## Zalo Account Shows "Disconnected" (`DISCONNECTED`)

**Cause:**
- The Zalo session was temporarily interrupted due to network drops, session expiry, or a failing sticky proxy (sending returns `ZALO_ACCOUNT_NOT_CONNECTED`).

**Fix:**
1. Go to **My Channels**, open the account menu, and click **Reconnect** (requires `nick:operate`).
2. If the account uses a proxy marked **`DEAD`**, switch to a **`HEALTHY`** proxy or detach the broken proxy before reconnecting.
3. If Reconnect fails, choose **Re-login** and scan a new QR code.

## Zalo Account Shows "Died" (`DIED`)

**Cause:**
- The Zalo account has been locked or invalidated on Zalo's side. OmnyBot cannot unlock Zalo accounts directly.

**Fix:**
1. Open the **Zalo** mobile app, sign in to the account, and follow Zalo's verification or appeal process.
2. Once the account works again on mobile, return to OmnyBot and click **Re-login** with a QR code (**Reconnect** does not work for `DIED` accounts).

## Zalo Account Shows "Logged in Elsewhere" (`LOGGED_IN_ELSEWHERE`)

**Cause:**
- Someone signed into the same Zalo account on another browser or Zalo Web session, kicking out OmnyBot's active session.

**Fix:**
1. Coordinate with your team so the account is not opened concurrently on another Zalo Web tab/device.
2. Go to **My Channels**, click **Re-login**, and scan the QR code to restore the session.

## Channel Locked Offline by Billing (`lockedNicks`)

**Cause:**
- The workspace subscription expired (`EXPIRED`) or the number of connected channels exceeds your plan's `maxNicks` cap.

**Fix:**
1. Go to **Settings → Billing → Plans** to renew or upgrade (see [Plans & Limits](/reference/plans-limits/)).
2. Once active, locked channels become available to reconnect.

## Zalo Proxy Issues

| Symptom / Error Code | Cause | Fix |
| --- | --- | --- |
| Proxy status is **`DEAD`** | Proxy server is unreachable, credentials are invalid, or blocked. | Verify `HTTP`/`HTTPS`/`SOCKS5` credentials with your provider or assign a working proxy. |
| `ZALO_PROXY_FULL` | Proxy has reached its `maxAccounts` capacity. | Choose another proxy with free slots or add a new proxy. |
| `ZALO_PROXY_DUPLICATE` | The same proxy endpoint already exists in the workspace. | Select the existing proxy from the list instead of adding a duplicate. |

## Facebook Fanpage, WhatsApp & Webchat Issues

- **Facebook Fanpage not sending/receiving:** The Page access token may have expired or permissions were revoked in Facebook Business. Reconnect the Fanpage under **My Channels**.
- **WhatsApp delivery failing:** Verify your WhatsApp Cloud API phone number/token status and ensure the conversation is within Meta's messaging window.
- **Webchat widget not appearing on your site:** Check **Allowed Domains (`allowedDomains`)** in widget settings (enable `allowLocalhost` for local testing). If **HMAC (`requireHmac`)** is enabled, verify your backend signs tokens with the active `hmacSecret`.

:::tip[Common messaging errors]
- `ZALO_MEDIA_TOO_LARGE`: Image/video exceeds the upload size limit — compress the file before sending.
- `ZALO_TOO_MANY_PINS`: Conversation reached the pinned message limit — unpin an older message first.
- `ZALO_CONTACT_NOT_REACHABLE`: Recipient blocks messages from strangers or the account is unreachable.
:::