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

# Kết nối bằng tiện ích trình duyệt

> Dùng phiên Zalo Web đang đăng nhập để thêm nick, không cần quét QR.

> [!WARNING]
>
> Tiện ích đọc cookie đăng nhập, tức là trao **toàn quyền nick** cho Agentme. Chỉ dùng với nick của chính bạn. Xem [Điều khoản và rủi ro](https://agentme-docs.vipcrm.net/terms-and-risks.md).

## Khi nào nên dùng

Dùng khi bạn đã đăng nhập Zalo Web (`chat.zalo.me`) trên trình duyệt và muốn Agentme dùng chung phiên đó. Quét QR riêng cho Agentme sẽ **huỷ phiên web cũ** của bạn, còn tiện ích thì không. Xem thêm [Zalo cá nhân](https://agentme-docs.vipcrm.net/channels/zalo-personal.md).

## Cài tiện ích

1. Trong ứng dụng Agentme, vào Thêm nick, chọn kênh và proxy, rồi chọn "Tiện ích trình duyệt". Tải `agentme-extension.zip` ở bước này.
2. Giải nén. Mở `chrome://extensions` (Chrome, Brave hoặc Edge) và bật Developer mode.
3. Chọn Load unpacked, trỏ tới thư mục vừa giải nén.

Tiện ích được phát hành nội bộ bằng file zip, chưa có trên Chrome Web Store.

## Kết nối nick

1. Trong wizard, bấm "Tạo mã ghép cặp". Mã gồm 8 ký tự, dùng **một lần**, hết hạn sau **10 phút**.
2. Đăng nhập `chat.zalo.me` trên trình duyệt.
3. Mở popup Agentme, nhập mã. Popup liệt kê các miền sẽ đọc. Bấm "Cho phép & gửi" và đồng ý cấp quyền cho trình duyệt.
4. Wizard tự chuyển sang hoàn tất khi Zalo xác nhận phiên (thường vài giây).

## Sau khi kết nối

* **Đóng tab Zalo Web.** Zalo chỉ cho một phiên web nghe tin mỗi nick. Nếu tab còn mở, nick có thể chuyển `yielded`.
* **Không bấm "Đăng xuất"** trên Zalo Web. Việc này huỷ luôn phiên mà Agentme đang dùng và nick chuyển `expired`.
* Popup có nút "Đóng tab Zalo Web giúp tôi".

## Quyền tiện ích xin

| Quyền | Dùng để |
| - | - |
| `cookies` | Đọc cookie của `zalo.me` và các miền con (kể cả HttpOnly) |
| `scripting` | Đọc `localStorage.z_uuid` (imei) và User-Agent tại `chat.zalo.me` |
| `storage` | Chỉ lưu địa chỉ máy chủ Agentme |
| Host `zalo.me`, `*.zalo.me` | Xin lúc bấm "Cho phép & gửi", không xin lúc cài |

Cookie chỉ nằm trong bộ nhớ popup đến khi gửi xong, chỉ được gửi tới địa chỉ Agentme đã cấu hình (https), và không được ghi log.

## Lỗi thường gặp

| Thông báo | Cách xử lý |
| - | - |
| Mã không đúng, hết hạn hoặc đã dùng | Tạo mã mới trong wizard |
| Thử quá nhiều lần | Chờ vài phút (giới hạn 10 lần thử mỗi IP trong 10 phút) |
| Chưa đăng nhập kênh trên trình duyệt này | Đăng nhập `chat.zalo.me` rồi thử lại |
| Nick vào `expired` sau khi kết nối | Cookie bị Zalo từ chối (thường do đã đăng xuất ở web). Kết nối lại |

Nếu dùng bản tự host, đổi địa chỉ máy chủ trong trang Cài đặt của tiện ích (bắt buộc `https`, trừ `localhost`).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.