Hermes Agent với Zalo: Zalo Bot, Zalo OA, ZNS

Chọn đúng "cửa" Zalo

Ghi chú: trang gói Zalo Bot ghi giới hạn tin nhắn theo tháng, phần câu hỏi thường gặp lại ghi theo ngày; bảng giá Zalo OA chưa nói rõ gói miễn phí và gói Tiêu chuẩn có dùng được Open API hay không. Hãy kiểm tra lại với Zalo trước khi đăng ký.

Nguồn: Zalo Bot – gói dịch vụ · Zalo OA – bảng giá · ZBS – bảng giá

Cách 1 — Zalo Bot trả lời khách bằng agent cskh

Luồng: khách nhắn bot Zalo → cầu nối trên VPS hỏi Zalo "có tin mới không" (cách long polling, không cần tên miền, không mở cổng) → hỏi agent cskh qua API nội bộ → gửi câu trả lời.

1.1. Chuẩn bị

• Agent cskh đã tắt công cụ chạy lệnh/file/trình duyệt (Phần 8), có kỹ năng bảng giá – FAQ – kịch bản (Phần 3).
• Đã bật API nội bộ và agent cskh có API_SERVER_KEY riêng (Phần 4 – Cách C).
• Tài khoản Zalo cá nhân đã xác thực (để tạo bot).

1.2. Tạo bot

1. Trong app Zalo, tìm OA Zalo Bot Manager → Tạo bot. Tên bot phải bắt đầu bằng "Bot", vd Bot Aduca Shop.
2. Zalo gửi thông tin bot và Bot Token (dạng 12345689:abc-xyz) vào tin nhắn Zalo của bạn. Token không tự hết hạn; muốn đổi thì vào Zalo Bot Creator → cài đặt → đặt lại.
3. Copy token vào trình quản lý mật khẩu, sau đó xoá tin nhắn chứa token trong Zalo.

Nguồn: Tạo Bot · Bot Token

1.3. Khai báo bí mật cho cầu nối (tài khoản hermes)

mkdir -p ~/.config && (umask 077; touch ~/.config/zalo-bridge.env)
read -rsp "Dán ZALO_BOT_TOKEN rồi Enter (chữ không hiện): " V; echo; echo "ZALO_BOT_TOKEN=$V" >> ~/.config/zalo-bridge.env; unset V
grep '^API_SERVER_KEY=' ~/.hermes/profiles/cskh/.env | sed 's/^API_SERVER_KEY=/CSKH_API_KEY=/' >> ~/.config/zalo-bridge.env
echo "GIOI_THIEU=Dạ em là trợ lý tự động của <tên shop>, nhân viên sẽ hỗ trợ thêm khi cần ạ." >> ~/.config/zalo-bridge.env
T=$(grep '^ZALO_BOT_TOKEN=' ~/.config/zalo-bridge.env | cut -d= -f2-); curl -s -X POST "https://bot-api.zaloplatforms.com/bot$T/getMe"; echo; unset T   # thấy "ok":true là token đúng

1.4. Tạo cầu nối và chạy 24/7

mkdir -p ~/zalo-bridge && cat > ~/zalo-bridge/cau_noi.py <<'EOF'
#!/usr/bin/env python3
"""Cầu nối Zalo Bot → Hermes (agent cskh), kiểu tự hỏi tin mới (long polling). Aduca viết, dùng tự do.
Không cần tên miền: cầu nối tự hỏi Zalo có tin mới không, hỏi agent cskh qua API nội bộ rồi trả lời."""
import json, os, re, time, urllib.request

E = dict(l.strip().split('=', 1) for l in open(os.path.expanduser('~/.config/zalo-bridge.env')) if '=' in l and not l.startswith('#'))
Z = 'https://bot-api.zaloplatforms.com/bot' + E['ZALO_BOT_TOKEN'] + '/'
HERMES = 'http://127.0.0.1:8642/p/cskh/v1/chat/completions'
KHACH = os.path.expanduser('~/zalo-bridge/khach-de-lai-sdt.txt')
SDT = re.compile(r'(?:\+?84|0)(?:\d[\s.-]?){8,10}')
lan_cuoi = {}

def goi(url, data, headers=None, timeout=60):
    h = {'Content-Type': 'application/json', **(headers or {})}
    with urllib.request.urlopen(urllib.request.Request(url, json.dumps(data).encode(), h), timeout=timeout) as r:
        return json.load(r)

def zalo(ham, **data):  # không in URL ra nhật ký vì URL chứa token
    return goi(Z + ham, data, timeout=45)

def hoi_cskh(phien, noi_dung):
    try:
        j = goi(HERMES, {'model': 'cskh', 'messages': [{'role': 'user', 'content': noi_dung}]},
                {'Authorization': 'Bearer ' + E['CSKH_API_KEY'], 'X-Hermes-Session-Id': phien}, timeout=90)
        return j['choices'][0]['message']['content'].strip()
    except Exception as e:
        print('Loi goi Hermes:', type(e).__name__, flush=True)
        return 'Dạ shop đã nhận tin nhắn, nhân viên sẽ phản hồi anh/chị sớm nhất ạ!'

def xu_ly(u):
    msg = (u or {}).get('message') or {}
    chat = msg.get('chat') or {}
    if chat.get('chat_type') != 'PRIVATE' or (msg.get('from') or {}).get('is_bot'):
        return
    cid = chat.get('id')
    if u.get('event_name') != 'message.text.received':
        zalo('sendMessage', chat_id=cid, text='Dạ hiện em chỉ đọc được tin nhắn chữ, anh/chị nhắn giúp em bằng chữ nhé ạ.')
        return
    text = msg.get('text', '')
    if SDT.search(text):
        with open(KHACH, 'a') as f:
            f.write(time.strftime('%d/%m %H:%M') + ' | Zalo | ' + (msg.get('from') or {}).get('display_name', '') + ' | ' + text[:300].replace('\n', ' ') + '\n')
    try:
        zalo('sendChatAction', chat_id=cid, action='typing')
    except Exception:
        pass
    tra_loi = hoi_cskh('zalo-' + cid, text)
    if time.time() - lan_cuoi.get(cid, 0) > 86400:
        tra_loi = E.get('GIOI_THIEU', 'Dạ em là trợ lý tự động của shop.') + '\n' + tra_loi
    lan_cuoi[cid] = time.time()
    zalo('sendMessage', chat_id=cid, text=tra_loi[:2000])

while True:
    try:
        j = zalo('getUpdates', timeout='30')
        kq = j.get('result') if j.get('ok') else None
        for u in (kq if isinstance(kq, list) else [kq] if kq else []):
            xu_ly(u)
    except Exception as e:
        print('Loi:', type(e).__name__, flush=True)
        time.sleep(5)
EOF

mkdir -p ~/.config/systemd/user && cat > ~/.config/systemd/user/zalo-bridge.service <<'EOF'
[Unit]
Description=Cau noi Zalo Bot - Hermes
After=network-online.target
[Service]
ExecStart=/usr/bin/python3 %h/zalo-bridge/cau_noi.py
Restart=always
RestartSec=5
[Install]
WantedBy=default.target
EOF
systemctl --user daemon-reload && systemctl --user enable --now zalo-bridge
systemctl --user status zalo-bridge --no-pager

Nhắn thử bot từ Zalo. Xem nhật ký: journalctl --user -u zalo-bridge -n 50. Tạm tắt: systemctl --user stop zalo-bridge.

1.5. Báo bạn khi khách để lại số điện thoại

Dùng cùng mẫu script canh gác ở Phần 5 – D6, đổi đường dẫn file thành ~/zalo-bridge/khach-de-lai-sdt.txt và tên lịch thành "Khách Zalo".

Cầu nối xử lý những gì

• Chỉ trả lời chat 1-1; bỏ qua nhóm (tính năng nhóm của Zalo Bot đang thử nghiệm, bot chỉ nhận tin được nhắc tên).
• Tin ảnh, sticker, giọng nói: trả lời lịch sự đề nghị nhắn chữ.
• Một số người dùng thuộc nhóm đặc biệt (trẻ em…) Zalo không gửi nội dung tin cho bot, vì lý do pháp lý — cầu nối trả lời câu mặc định.
• Câu trả lời cắt ở 2.000 ký tự (giới hạn của Zalo); giới thiệu là trợ lý tự động khi khách nhắn lần đầu trong 24 giờ.
• Không in đường dẫn chứa token ra nhật ký.

Nguồn: Gọi API · getUpdates · sendMessage · Webhook · Nhóm (beta)

Cách 2 — Zalo OA cho doanh nghiệp nhiều khách

Zalo Official Account là kênh chính thức, không giới hạn 50 người như Zalo Bot, nhưng thiết lập phức tạp hơn. Những điều cần biết trước khi nhờ kỹ thuật viên (hoặc agent Tổng) dựng cầu nối:

Cầu nối OA có cấu trúc giống cầu nối Fanpage ở Phần 5 (nhận webhook, kiểm chữ ký, trả lời nhanh, xử lý sau, hỏi agent cskh). Gợi ý: nhắn agent Tổng trong Termius "Đọc tài liệu Zalo OA webhook và tin tư vấn, viết cầu nối dựa trên ~/meta-bridge/cau_noi.py, có lưu refresh token an toàn", rồi đọc kỹ và chạy thử trước khi dùng thật.

Nguồn: OA Webhook · Sự kiện tin nhắn · Gửi tin tư vấn · Điều kiện 7 ngày · 48 giờ · Xác thực · Bảng giá OA

Tin mẫu ZBS (ZNS): thông báo đơn hàng, lịch hẹn

ZBS Template Message (trước đây gọi là ZNS) gửi được theo số điện thoại, dùng cho tin giao dịch và hậu mãi, mẫu phải được Zalo duyệt trước. Cần OA, ứng dụng Zalo và tài khoản ZBS để thanh toán. Agent giúp soạn mẫu để nộp duyệt:

Soạn 3 mẫu ZBS loại giao dịch cho <shop>: xác nhận đơn hàng, thông báo giao hàng, nhắc thanh toán.
Mỗi mẫu có biến <ten_khach>, <ma_don>, <thoi_gian>, <so_tien>; nội dung đúng tính chất giao dịch, không quảng cáo, dưới 400 ký tự.

Nguồn: Tổng quan tin nhắn – ZBS · Bảng giá

Vì sao Aduca không khuyên dùng Zalo cá nhân

Một số hướng dẫn trên mạng dùng thư viện không chính thức (giả lập Zalo Web, vd zca-js) để bot trả lời bằng tài khoản Zalo cá nhân. Chính tác giả thư viện cảnh báo việc này trái chính sách của Zalo và tài khoản có thể bị khoá. Ngoài ra mỗi tài khoản chỉ giữ được một phiên web, mở Zalo trên trình duyệt là bot ngắt.

Mất số Zalo bán hàng là mất toàn bộ khách và lịch sử trò chuyện — rủi ro không đáng. Hãy dùng Zalo Bot hoặc Zalo OA. Nếu vẫn thử nghiệm, chỉ dùng số phụ và không gửi tin hàng loạt.

Nguồn: zca-js README – cảnh báo

Pháp lý cần nhớ

• Luật Bảo vệ dữ liệu cá nhân số 91/2025/QH15 (hiệu lực 01/01/2026) và Nghị định 356/2025/NĐ-CP: cần sự đồng ý của khách khi thu thập, xử lý số điện thoại, nội dung trò chuyện; khách có quyền yêu cầu xem, xoá dữ liệu.
• Nghị định 91/2020/NĐ-CP về chống tin nhắn rác: không gửi tin quảng cáo cho người chưa đồng ý. Bộ Công an đang lấy ý kiến dự thảo nghị định thay thế, mở rộng phạm vi sang ứng dụng nhắn tin OTT.
• Nói rõ khách đang trò chuyện với trợ lý tự động, có cách gặp nhân viên thật.
• Thông tin khách gửi tới nhà cung cấp model AI: chọn nhà cung cấp có cam kết không dùng dữ liệu API để huấn luyện, ghi rõ trong chính sách quyền riêng tư của bạn.

Đây là tóm tắt tham khảo của Aduca, không phải tư vấn pháp lý.

Nguồn: Luật 91/2025/QH15 · Nghị định 356/2025 · Nghị định 91/2020

Tài liệu liên quan

• Hermes Agent · AI AgentCài đặt Hermes Agent trên VPS an toànTừng bước: VPS bảo mật, cài Hermes, kết nối model AI, bot Telegram chỉ nghe lời bạn, chạy 24/7, sao lưu tự động, Google Sheets/Drive.
• AI AgentAI Agent là gì? Khác gì ChatGPT, chatbot, phần mềm tự động hoáAI Agent là gì, hoạt động ra sao, khác ChatGPT, chatbot và phần mềm tự động hoá thế nào; 1 ngày làm việc của Agent và 20 việc giao được ngay.
• Hermes Agent · AI AgentHermes Agent là gì? AI Agent biết tự học của Nous ResearchHermes Agent là gì: AI Agent mã nguồn mở của Nous Research biết tự học kỹ năng, nhớ bạn qua nhiều phiên, chạy 24/7 trên VPS; 7 điểm khác biệt, chi phí.
• Hermes Agent · AI AgentHướng dẫn sử dụng Hermes Agent hằng ngàyChat qua Telegram, lệnh gạch chéo, tính cách SOUL.md, trí nhớ, kỹ năng tự học, đổi model, kiểm soát chi phí và bảng lệnh hay dùng.

Xem tất cả tài liệu hướng dẫn →

Nguồn tham khảo

Thông tin kỹ thuật trong bài lấy từ các tài liệu dưới đây (đã ghi nguồn ngay dưới từng mục). Phần diễn giải, ví dụ và quy trình là của Aduca.

• Zalo Platforms – Tạo Bot
• Zalo Platforms – Bot Token
• Zalo Platforms – Gọi API Bot
• Zalo Bot – getUpdates (loại trừ với webhook)
• Zalo Bot – sendMessage (tối đa 2.000 ký tự)
• Zalo Bot – sendChatAction
• Zalo Bot – Webhook (X-Bot-Api-Secret-Token, sự kiện)
• Zalo Bot – Nhóm (beta)
• Zalo Bot Platform – Gói dịch vụ
• Zalo OA – Webhook (phản hồi trong 2 giây)
• Zalo OA – Sự kiện người dùng gửi tin nhắn
• Zalo OA – Gửi tin tư vấn
• Zalo OA – Điều kiện gửi tin tư vấn (7 ngày)
• Zalo OA – Tổng quan tin nhắn (48 giờ, ZBS)
• Zalo OA – Xác thực, access token 25 giờ
• Zalo OA – Bảng giá gói (từ 01/06/2026)
• ZBS Template Message (ZNS) – Bảng giá
• zca-js (không chính thức) – cảnh báo của tác giả
• Luật Bảo vệ dữ liệu cá nhân số 91/2025/QH15
• Nghị định 356/2025/NĐ-CP
• Nghị định 91/2020/NĐ-CP về chống tin nhắn rác
• Hermes – API Server
• Hermes – Cron (no-agent script)
• Aduca – Agent Zalo với OpenClaw

Lịch sử cập nhật

• 02/10/2026 — Bản đầu: Zalo Bot Platform, Zalo OA (bảng giá 06/2026), ZBS Template Message.

Miễn trừ trách nhiệm