Handoff (chuyển người thật) & Telegram notify

Đây là 2 tính năng khách hỏi nhiều nhất về AI Agent: (1) khi nào AI “kêu người thật”, và (2) làm sao AI báo chủ shop qua Telegram khi gặp trường hợp khó.

Cả 2 đều cấu hình trong tab Công cụ của Agent Builder.

1. Handoff — chuyển sang nhân viên thật

Tool human_handoff cho AI khả năng tạm dừng AI + chuyển hội thoại cho 1 nhân viên khi gặp case ngoài phạm vi.

Khi nào AI tự handoff

AI tự quyết định handoff khi:

1. Khách yêu cầu trực tiếp — “cho nói người thật”, “gặp quản lý”, “chuyên viên tư vấn”.
2. Vượt phạm vi knowledge — khách hỏi về hoàn tiền, khiếu nại, kỹ thuật phức tạp mà prompt không cover.
3. Sentiment urgent — nếu bật sentiment_detector + auto_escalate: urgent_only, khách tức giận → AI tự handoff.
4. Keyword routing — cấu hình trong Advanced tab (Multi-Agent routing).

AI KHÔNG handoff chỉ vì khách gửi ảnh

Quan trọng: AI từ chối handoff nếu lý do duy nhất là khách gửi ảnh/file (image_turn_handoff_not_allowed). AI xử lý ảnh như input bình thường. Đây là thiết kế chống lạm dụng — tránh AI handoff liên tục khi khách share ảnh sản phẩm.

9 field cấu hình human_handoff

Bấm bánh răng trên tool human_handoff → mở form:

Field	Ý nghĩa	Lựa chọn
handoff_status	Trạng thái hội thoại khi handoff	Pause (AI nghỉ hoàn toàn) / Kỹ thuật (AI vẫn phụ)
notify_telegram	Có báo Telegram khi handoff không	Bật/tắt (mặc định bật)
auto_assign	Tự phân công nhân viên	none / round_robin (xoay vòng) / least_busy (ít việc nhất)
assign_user_ids	Chỉ phân cho nhân viên cụ thể	List ID nhân viên (rỗng = tất cả)
team_id	Giới hạn 1 team hỗ trợ	ID team
online_only	Chỉ phân nhân viên đang online	Bật/tắt (nếu off → xếp hàng chờ)
max_active_chats	Giới hạn chat cùng lúc / nhân viên	Số (0 = không giới hạn)
active_window_days	Cửa sổ đếm khối lượng công việc	Số ngày
business_hours	Giờ làm việc	JSON: {"enabled":true,"tz":"Asia/Ho_Chi_Minh","days":[1,2,3,4,5],"start":"08:00","end":"18:00"}

Logic phân công (StaffRouter)

Khi AI handoff, hệ thống chọn nhân viên theo thứ tự ưu tiên:

1. Lọc theo assign_user_ids / team_id.
2. Nếu online_only → chỉ nhân viên đang online.
3. Nếu max_active_chats set → loại nhân viên quá tải.
4. Nếu business_hours enabled + ngoài giờ → xếp hàng chờ.
5. Theo auto_assign: round_robin (xoay vòng) hoặc least_busy (ít chat nhất).

least_busy = công bằng

Mặc định least_busy — phân cho nhân viên đang ít chat nhất. Tránh 1 người nhận nhiều, người khác rảnh.

business_hours — ngoài giờ làm gì

Nếu handoff ngoài business_hours:

• Hội thoại vào hàng chờ.
• Khi tới giờ làm → tự phân công.
• AI có thể vẫn trả lời tạm (nếu handoff_status = Kỹ thuật).

2. Telegram notify — báo chủ shop

Có 2 cách AI báo Telegram:

Cách A — Tool telegram_notify (per-agent)

Tool riêng trong tab Công cụ. Cấu hình:

Field	Ý nghĩa
bot_token	Token từ @BotFather (secret)
chat_id	Chat ID nhận thông báo (cá nhân hoặc group)
pause_patterns	Từ khoá khách nói → AI báo “tạm dừng” (vd “nhờ kỹ thuật”, “chuyên viên”)
done_patterns	Từ khoá khách nói → AI báo “xong” (vd “ok rồi”, “cảm ơn”)
kythuat_patterns	Từ khoá → AI báo “cần kỹ thuật”

Tool này có sẵn pattern tiếng Việt: “nhờ bạn kỹ thuật”, “chuyên viên sẽ liên hệ”…

Cách B — Flag notify_telegram trong human_handoff

Đơn giản hơn: bật notify_telegram: true trong tool human_handoff → mỗi lần handoff tự báo Telegram (dùng bot_token/chat_id của telegram_notify).

Cách B đủ cho đa số shop

Đa số shop chỉ cần: bật human_handoff + notify_telegram: true → mỗi khi AI chuyển người thật, bạn nhận alert Telegram. Không cần config pattern phức tạp.

3. Setup Telegram Bot (4 bước qua @BotFather)

Trước khi cấu hình, cần tạo Telegram Bot:

1. Mở Telegram → tìm @BotFather → /newbot.
2. Đặt tên + username bot → BotFather trả bot_token.
3. Tạo group (hoặc chat riêng với bot) → thêm bot vào → gửi 1 tin nhắn.
4. Lấy chat_id — dùng @userinfobot hoặc API getUpdates.

Sau đó cấu hình ở 2 nơi:

Trong Agent Builder (per-agent)

Tab Công cụ → tool telegram_notify → dán bot_token + chat_id.

Trong trang Integrations (account-level)

/app/integrations → Telegram Notify → bấm kết nối → modal hướng dẫn 4 bước → dán token + chat_id.

Test message khi kết nối

Khi kết nối ở Integrations, bot tự gửi test message “✅ Connected to AI Support Platform” — nếu bạn nhận được ở Telegram = setup OK.

4. Multi-Agent routing (Advanced tab)

Trong tab Nâng cao, section Định tuyến Đa Agent cho phép nhiều Agent chuyên biệt + tự chuyển giữa chúng:

Cấu hình	Ý nghĩa
role	default / triage (điều phối) / specialist (chuyên gia)
preferred_agent	Agent đích mặc định khi handoff
specialization	Phạm vi chuyên môn
route_keywords	Từ khoá khách nói → chuyển Agent tương ứng
handoff_condition	Điều kiện handoff ([HANDOFF:agent_id:lý do])

Thứ tự ưu tiên routing

1. Handoff [HANDOFF:agent_id:reason] — chuyển trực tiếp.
2. Triage — Agent điều phối phân luồng.
3. Keyword — khớp route_keywords.
4. Default fallback — Agent mặc định.

Multi-Agent cho shop lớn

Shop nhỏ (1 ngành, 1 Agent) không cần. Bắt đầu cần khi: shop đa ngành (Agent bán hàng + Agent kỹ thuật), hoặc nhiều team hỗ trợ.

5. Alert qua Email / Webhook (tab Cảnh báo)

Ngoài Telegram, tab Cảnh báo cho phép alert qua:

Kênh	Khi nào
Telegram	Mặc định
Email	Cấu hình trong alert rule
Webhook	Gọi URL hệ thống ngoài

Mỗi alert rule chọn 1 kênh. Kết hợp với human_handoff để nhận thông báo đa kênh.

Workflow đề xuất

Setup tối thiểu hiệu quả

1. Tạo Telegram Bot (4 bước @BotFather).
2. Cấu hình ở Integrations page.
3. Bật tool human_handoff + notify_telegram: true.
4. auto_assign: least_busy, business_hours theo giờ shop.
5. Test: chat với AI → nói “cho gặp người thật” → kiểm tra Telegram nhận alert.

Bước tiếp theo

• Agent Builder tổng quan — 10 tab.
• Tools tổng quan — 40 tools AI.
• AI gửi ảnh trong chat — cú pháp [IMAGE:url].
• Hội thoại — chat how-to — operator nhận handoff.
• Phân công chat (round-robin) — auto_assign.