Hướng dẫnMarketing

Kết nối Zalo Bot

Thêm nhiều bot Zalo Bot Platform bằng Bot Token, bộ chọn bot, nhận tin cá nhân/nhóm qua webhook và trạng thái kết nối.

Zalo Bot là một kênh Zalo hoạt động trên Zalo Bot Platform (khác Zalo OA và tài khoản cá nhân). Bot stateless: định danh và xác thực bằng Bot Token riêng, không cần phiên socket. Một doanh nghiệp tạo được nhiều bot cùng lúc, mỗi bot một Bot Token — giống các bot trên Telegram.

Thông tin cần có

Một Zalo bot được khoá theo bot id do Zalo trả về, và cần đúng một thứ:

Trường	Dùng để
`Bot Token`	Xác thực và gọi API của bot. Do Zalo Bot Creator gửi cho bạn.

Không chia sẻ Bot Token

Bot Token là thông tin xác thực. Hệ thống lưu nó mã hoá và không bao giờ trả lại qua API. Không dán token vào chat, tài liệu hay ảnh chụp màn hình. Nếu token bị lộ, reset nó trong Zalo Bot Creator.

Thêm bot

Trong khung chat Zalo Bot, bấm Thêm bot, dán Bot Token và bấm Kết nối. Hệ thống gọi getMe để kiểm tra token trước khi lưu:

Token hợp lệ → tạo connection mới với account_ref là bot id, trạng thái đã kết nối.
Token sai hoặc hết hạn → báo lỗi rõ ràng, không tạo connection.

Reset token không tạo bot trùng

Bạn có thể thêm lại cùng một bot bằng token mới sau khi reset trong Zalo Bot Creator. Connection được nhận theo (tenant, bot id) nên token mới cập nhật bot cũ thay vì tạo bản trùng.

Bộ chọn bot và hội thoại

Đầu cột trái có bộ chọn bot để đổi bot đang xem mà không mở thêm trang:

Bộ chọn ghi bot đang chọn vào địa chỉ (?bot=<connectionId>), nên refresh và nút Back giữ đúng bot.
Danh sách hội thoại chỉ hiện thread của bot đang chọn — hội thoại của các bot không trộn vào nhau.
Tab Tất cả / Cá nhân / Nhóm lọc hội thoại cá nhân và nhóm, giống kênh Zalo User.

Luồng tin nhắn

Giống Zalo OA, bot hoạt động theo webhook (không có phiên socket):

Khách nhắn cho bot (cá nhân hoặc nhóm).
Zalo gọi webhook của hệ thống tại /api/public/zalo-bot/webhook/<connectionId> kèm header X-Bot-Api-Secret-Token.
Hệ thống xác thực secret (sai → 403), parse sự kiện, rồi dispatch workflow đã bind.
Phản hồi được gửi lại qua API của chính bot đó, tới đúng chat.id.

Webhook URL được đăng ký tự động khi bạn kết nối bot, dựng từ biến cấu hình PUBLIC_BASE_URL. Mỗi bot có một connection id riêng trong URL.

Cá nhân và nhóm

Hệ thống nhận sự kiện message.text.received (chỉ tin văn bản ở v1):

Tin riêng (PRIVATE) → hội thoại cá nhân.
Tin nhóm (GROUP) → hội thoại nhóm.

Nhóm là bản beta của Zalo

Bot chỉ nhận tin nhóm khi được reply hoặc @mention. Việc mời bot vào nhóm và giới hạn số nhóm do Zalo Bot Creator quản lý.

Chống trùng và im lặng

Cùng một msg_id bị Zalo gửi lại (retry) sẽ không trả lời lần hai.
Binding đang tắt, hoặc bot chưa kết nối → hệ thống không phản hồi và không báo lỗi.

Gửi tay

Bạn có thể trả lời thủ công trong hội thoại của một bot. Tin gửi đi qua token của chính bot đó, được lưu vào hội thoại và đồng bộ realtime như các kênh khác — không ảnh hưởng Zalo User hay OA.

Trạng thái và kết nối lại

Mỗi bot hiện trạng thái ở bộ chọn:

Đã kết nối — webhook đã đăng ký và Zalo verify thành công.
Lỗi kết nối — kèm banner nêu lý do (ví dụ webhook không truy cập được, token đã chết).

Với bot đang lỗi, bấm Kết nối lại để hệ thống kiểm tra token và đăng ký lại webhook. Nếu vẫn lỗi, banner giữ nguyên lý do để bạn xử lý.

Webhook cần URL HTTPS công khai

Ở môi trường chạy thật, PUBLIC_BASE_URL phải là HTTPS công khai thì Zalo mới verify được webhook. Nếu đang phát triển cục bộ, hãy dùng một tunnel và đặt PUBLIC_BASE_URL tương ứng.

Gán workflow vào bot

Như mọi kết nối Zalo, bot chỉ chạy khi có Workflow binding đang bật. Việc gán và bật/tắt được làm riêng cho từng bot, nên mỗi bot chạy kịch bản của riêng nó. Xem Workflow & Kịch bản AI.

Giới hạn ở phiên bản này

Chỉ hỗ trợ tin văn bản; chưa gửi/nhận ảnh, sticker, voice.
Nhóm còn ở mức beta (chỉ nhận khi được reply hoặc @mention).
Chưa hỗ trợ xoá/ngắt kết nối bot hay định dạng rich text.