Skip to content

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.

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)

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:

  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.

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)

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:

  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)

Section titled “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).
  2. Once active, locked channels become available to reconnect.
Symptom / Error CodeCauseFix
Proxy status is DEADProxy server is unreachable, credentials are invalid, or blocked.Verify HTTP/HTTPS/SOCKS5 credentials with your provider or assign a working proxy.
ZALO_PROXY_FULLProxy has reached its maxAccounts capacity.Choose another proxy with free slots or add a new proxy.
ZALO_PROXY_DUPLICATEThe 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 (enable allowLocalhost for local testing). If HMAC (requireHmac) is enabled, verify your backend signs tokens with the active hmacSecret.