Sự cố kênh kết nối
Xem dạng Markdown
Trang này tổng hợp các sự cố thường gặp khi kết nối và duy trì các kênh chat (Zalo cá nhân, Facebook Fanpage, WhatsApp, Webchat) trong OmnyBot. Tra nhanh ý nghĩa trạng thái tại [Bảng tra trạng thái](/reference/statuses/).
## Mã QR Zalo hết hạn hoặc không đăng nhập được
**Nguyên nhân:**
- Mỗi phiên đăng nhập QR chỉ dùng một lần và tự hết hạn sau thời gian ngắn (mã lỗi `ZALO_LOGIN_SESSION_NOT_FOUND` hoặc `ZALO_LOGIN_FAILED`).
- Khi khởi tạo QR qua trợ lý Mina, hệ thống giới hạn tối đa **5 lần trong 10 phút** mỗi người dùng để chống lặp yêu cầu.
**Cách xử lý:**
1. Đóng hộp thoại mã QR hiện tại.
2. Vào **Kênh của tôi**, nhấn **Thêm kênh → Zalo cá nhân** để lấy mã QR mới (yêu cầu quyền `nick:connect`).
3. Mở ứng dụng **Zalo** trên điện thoại → **Quét mã QR** và xác nhận đăng nhập ngay.
## Tài khoản Zalo hiện "Mất kết nối" (`DISCONNECTED`)
**Nguyên nhân:**
- Phiên đăng nhập Zalo tạm gián đoạn do mạng, phiên hết hiệu lực, hoặc proxy gắn kèm gặp sự cố (thao tác gửi tin sẽ trả lỗi `ZALO_ACCOUNT_NOT_CONNECTED`).
**Cách xử lý:**
1. Vào **Kênh của tôi**, mở menu của tài khoản đó và chọn **Kết nối lại** (yêu cầu quyền `nick:operate`).
2. Nếu tài khoản đang gắn proxy ở trạng thái **Lỗi (`DEAD`)**, hãy đổi sang proxy **Ổn định (`HEALTHY`)** hoặc tạm gỡ proxy rồi thử kết nối lại.
3. Nếu kết nối lại vẫn thất bại, chọn **Đăng nhập lại** và quét mã QR mới.
## Tài khoản Zalo hiện "Đã chết" (`DIED`)
**Nguyên nhân:**
- Tài khoản Zalo bị khóa hoặc vô hiệu hóa phiên từ phía Zalo. OmnyBot không thể mở khóa thay Zalo.
**Cách xử lý:**
1. Mở ứng dụng **Zalo** trên điện thoại, đăng nhập và làm theo hướng dẫn xác minh/mở khóa của Zalo.
2. Khi tài khoản hoạt động bình thường trở lại trên điện thoại, quay lại OmnyBot và chọn **Đăng nhập lại** bằng mã QR (nút **Kết nối lại** không áp dụng cho trạng thái này).
## Tài khoản Zalo hiện "Đăng nhập nơi khác" (`LOGGED_IN_ELSEWHERE`)
**Nguyên nhân:**
- Có người khác trong nhóm đăng nhập cùng tài khoản Zalo đó trên trình duyệt hoặc thiết bị Zalo Web khác, làm đẩy phiên đang chạy trên OmnyBot.
**Cách xử lý:**
1. Kiểm tra và thống nhất trong đội ngũ không mở song song cùng tài khoản trên Zalo Web khác.
2. Vào **Kênh của tôi**, chọn **Đăng nhập lại** và quét mã QR để khôi phục phiên trên OmnyBot.
## Kênh bị khóa ngoại tuyến do gói dịch vụ (`lockedNicks`)
**Nguyên nhân:**
- Gói dịch vụ của Workspace đã hết hạn (`EXPIRED`) hoặc tổng số kênh vượt quá hạn mức `maxNicks` của gói hiện tại.
**Cách xử lý:**
1. Vào **Cài đặt → Thanh toán → Gói** để gia hạn hoặc nâng cấp gói (xem [Gói và giới hạn](/reference/plans-limits/)).
2. Sau khi gói hoạt động lại, các kênh bị khóa sẽ được mở lại để bạn kết nối tiếp.
## Sự cố Proxy cho tài khoản Zalo
| Triệu chứng / Mã lỗi | Nguyên nhân | Cách xử lý |
| --- | --- | --- |
| Proxy hiện **`DEAD`** | Máy chủ proxy ngừng hoạt động, sai thông tin xác thực hoặc bị chặn. | Kiểm tra lại thông tin `HTTP`/`HTTPS`/`SOCKS5` với nhà cung cấp hoặc gán proxy mới. |
| `ZALO_PROXY_FULL` | Proxy đã đạt số lượng tài khoản tối đa (`maxAccounts`). | Chọn proxy khác còn chỗ trống hoặc thêm proxy mới. |
| `ZALO_PROXY_DUPLICATE` | Địa chỉ proxy này đã tồn tại trong Workspace. | Chọn lại proxy sẵn có trong danh sách thay vì tạo trùng. |
## Sự cố kênh Facebook Fanpage, WhatsApp & Webchat
- **Facebook Fanpage không nhận/gửi được tin:** Kiểm tra lại quyền trang (Page access token có thể đã hết hạn hoặc bị thu hồi trên Facebook Business). Kết nối lại Fanpage tại **Kênh của tôi**.
- **WhatsApp không gửi được tin:** Kiểm tra trạng thái số điện thoại/token kết nối trên WhatsApp Cloud API và đảm bảo cuộc hội thoại vẫn nằm trong khung cửa sổ nhắn tin hợp lệ của Meta.
- **Webchat không hiển thị trên website:** Kiểm tra mục **Tên miền cho phép (`allowedDomains`)** trong cấu hình widget (bật `allowLocalhost` nếu đang thử trên máy cá nhân). Nếu bật xác thực **HMAC (`requireHmac`)**, đảm bảo backend website của bạn ký đúng bằng `hmacSecret` hiện hành.
:::tip[Lỗi khi gửi tin nhắn hoặc đính kèm]
- `ZALO_MEDIA_TOO_LARGE`: Tệp ảnh/video vượt dung lượng cho phép — hãy nén tệp nhỏ hơn trước khi gửi.
- `ZALO_TOO_MANY_PINS`: Hội thoại đã đạt giới hạn tin nhắn ghim — bỏ ghim bớt trước khi ghim mới.
- `ZALO_CONTACT_NOT_REACHABLE`: Khách hàng chặn nhận tin từ người lạ hoặc tài khoản không tồn tại.
:::
Trang này tổng hợp các sự cố thường gặp khi kết nối và duy trì các kênh chat (Zalo cá nhân, Facebook Fanpage, WhatsApp, Webchat) trong OmnyBot. Tra nhanh ý nghĩa trạng thái tại Bảng tra trạng thái.
Mã QR Zalo hết hạn hoặc không đăng nhập được
Phần tiêu đề “Mã QR Zalo hết hạn hoặc không đăng nhập được”Nguyên nhân:
- Mỗi phiên đăng nhập QR chỉ dùng một lần và tự hết hạn sau thời gian ngắn (mã lỗi
ZALO_LOGIN_SESSION_NOT_FOUNDhoặcZALO_LOGIN_FAILED). - Khi khởi tạo QR qua trợ lý Mina, hệ thống giới hạn tối đa 5 lần trong 10 phút mỗi người dùng để chống lặp yêu cầu.
Cách xử lý:
- Đóng hộp thoại mã QR hiện tại.
- Vào Kênh của tôi, nhấn Thêm kênh → Zalo cá nhân để lấy mã QR mới (yêu cầu quyền
nick:connect). - Mở ứng dụng Zalo trên điện thoại → Quét mã QR và xác nhận đăng nhập ngay.
Tài khoản Zalo hiện “Mất kết nối” (DISCONNECTED)
Phần tiêu đề “Tài khoản Zalo hiện “Mất kết nối” (DISCONNECTED)”Nguyên nhân:
- Phiên đăng nhập Zalo tạm gián đoạn do mạng, phiên hết hiệu lực, hoặc proxy gắn kèm gặp sự cố (thao tác gửi tin sẽ trả lỗi
ZALO_ACCOUNT_NOT_CONNECTED).
Cách xử lý:
- Vào Kênh của tôi, mở menu của tài khoản đó và chọn Kết nối lại (yêu cầu quyền
nick:operate). - Nếu tài khoản đang gắn proxy ở trạng thái Lỗi (
DEAD), hãy đổi sang proxy Ổn định (HEALTHY) hoặc tạm gỡ proxy rồi thử kết nối lại. - Nếu kết nối lại vẫn thất bại, chọn Đăng nhập lại và quét mã QR mới.
Tài khoản Zalo hiện “Đã chết” (DIED)
Phần tiêu đề “Tài khoản Zalo hiện “Đã chết” (DIED)”Nguyên nhân:
- Tài khoản Zalo bị khóa hoặc vô hiệu hóa phiên từ phía Zalo. OmnyBot không thể mở khóa thay Zalo.
Cách xử lý:
- Mở ứng dụng Zalo trên điện thoại, đăng nhập và làm theo hướng dẫn xác minh/mở khóa của Zalo.
- Khi tài khoản hoạt động bình thường trở lại trên điện thoại, quay lại OmnyBot và chọn Đăng nhập lại bằng mã QR (nút Kết nối lại không áp dụng cho trạng thái này).
Tài khoản Zalo hiện “Đăng nhập nơi khác” (LOGGED_IN_ELSEWHERE)
Phần tiêu đề “Tài khoản Zalo hiện “Đăng nhập nơi khác” (LOGGED_IN_ELSEWHERE)”Nguyên nhân:
- Có người khác trong nhóm đăng nhập cùng tài khoản Zalo đó trên trình duyệt hoặc thiết bị Zalo Web khác, làm đẩy phiên đang chạy trên OmnyBot.
Cách xử lý:
- Kiểm tra và thống nhất trong đội ngũ không mở song song cùng tài khoản trên Zalo Web khác.
- Vào Kênh của tôi, chọn Đăng nhập lại và quét mã QR để khôi phục phiên trên OmnyBot.
Kênh bị khóa ngoại tuyến do gói dịch vụ (lockedNicks)
Phần tiêu đề “Kênh bị khóa ngoại tuyến do gói dịch vụ (lockedNicks)”Nguyên nhân:
- Gói dịch vụ của Workspace đã hết hạn (
EXPIRED) hoặc tổng số kênh vượt quá hạn mứcmaxNickscủa gói hiện tại.
Cách xử lý:
- Vào Cài đặt → Thanh toán → Gói để gia hạn hoặc nâng cấp gói (xem Gói và giới hạn).
- Sau khi gói hoạt động lại, các kênh bị khóa sẽ được mở lại để bạn kết nối tiếp.
Sự cố Proxy cho tài khoản Zalo
Phần tiêu đề “Sự cố Proxy cho tài khoản Zalo”| Triệu chứng / Mã lỗi | Nguyên nhân | Cách xử lý |
|---|---|---|
Proxy hiện DEAD | Máy chủ proxy ngừng hoạt động, sai thông tin xác thực hoặc bị chặn. | Kiểm tra lại thông tin HTTP/HTTPS/SOCKS5 với nhà cung cấp hoặc gán proxy mới. |
ZALO_PROXY_FULL | Proxy đã đạt số lượng tài khoản tối đa (maxAccounts). | Chọn proxy khác còn chỗ trống hoặc thêm proxy mới. |
ZALO_PROXY_DUPLICATE | Địa chỉ proxy này đã tồn tại trong Workspace. | Chọn lại proxy sẵn có trong danh sách thay vì tạo trùng. |
Sự cố kênh Facebook Fanpage, WhatsApp & Webchat
Phần tiêu đề “Sự cố kênh Facebook Fanpage, WhatsApp & Webchat”- Facebook Fanpage không nhận/gửi được tin: Kiểm tra lại quyền trang (Page access token có thể đã hết hạn hoặc bị thu hồi trên Facebook Business). Kết nối lại Fanpage tại Kênh của tôi.
- WhatsApp không gửi được tin: Kiểm tra trạng thái số điện thoại/token kết nối trên WhatsApp Cloud API và đảm bảo cuộc hội thoại vẫn nằm trong khung cửa sổ nhắn tin hợp lệ của Meta.
- Webchat không hiển thị trên website: Kiểm tra mục Tên miền cho phép (
allowedDomains) trong cấu hình widget (bậtallowLocalhostnếu đang thử trên máy cá nhân). Nếu bật xác thực HMAC (requireHmac), đảm bảo backend website của bạn ký đúng bằnghmacSecrethiện hành.