Channel Connection Issues
View as Markdown
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.
:::
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.
Zalo QR Code Expired or Login Failed
Section titled “Zalo QR Code Expired or Login Failed”Cause:
- Each QR login session is single-use and expires shortly after generation (
ZALO_LOGIN_SESSION_NOT_FOUNDorZALO_LOGIN_FAILED). - Starting QR logins via the Mina assistant is rate-limited to 5 attempts per 10 minutes per user.
Fix:
- Close the expired QR dialog.
- Go to My Channels and click Add Channel → Personal Zalo to generate a fresh QR code (requires
nick:connect). - Scan immediately from the Zalo mobile app (Scan QR) and confirm login.
Zalo Account Shows “Disconnected” (DISCONNECTED)
Section titled “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:
- Go to My Channels, open the account menu, and click Reconnect (requires
nick:operate). - If the account uses a proxy marked
DEAD, switch to aHEALTHYproxy or detach the broken proxy before reconnecting. - If Reconnect fails, choose Re-login and scan a new QR code.
Zalo Account Shows “Died” (DIED)
Section titled “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:
- Open the Zalo mobile app, sign in to the account, and follow Zalo’s verification or appeal process.
- Once the account works again on mobile, return to OmnyBot and click Re-login with a QR code (Reconnect does not work for
DIEDaccounts).
Zalo Account Shows “Logged in Elsewhere” (LOGGED_IN_ELSEWHERE)
Section titled “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:
- Coordinate with your team so the account is not opened concurrently on another Zalo Web tab/device.
- Go to My Channels, click Re-login, and scan the QR code to restore the session.
Channel Locked Offline by Billing (lockedNicks)
Section titled “Channel Locked Offline by Billing (lockedNicks)”Cause:
- The workspace subscription expired (
EXPIRED) or the number of connected channels exceeds your plan’smaxNickscap.
Fix:
- Go to Settings → Billing → Plans to renew or upgrade (see Plans & Limits).
- Once active, locked channels become available to reconnect.
Zalo Proxy Issues
Section titled “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
Section titled “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 (enableallowLocalhostfor local testing). If HMAC (requireHmac) is enabled, verify your backend signs tokens with the activehmacSecret.