Kết nối HAINIVA AICC với Telegram Bot
Thiết lập Bot Token · Kết nối kênh · Định tuyến · Kiểm tra hoạt động
Phiên bản 1.0 · Dành cho Tenant Admin
Telegram Bot được kết nối ở trạng thái Active; tin nhắn được đưa đến Queue, Agent hoặc AI Agent theo cấu hình; người dùng Telegram được ghi nhận trong Contacts.
01. Tổng quan
Tài liệu này hướng dẫn toàn bộ quy trình kết nối một Telegram Bot với HAINIVA AICC: tạo bot trên Telegram, nhập Bot Token vào hệ thống, cấu hình định tuyến và kiểm tra tin nhắn thực tế.
Đối tượng sử dụng
- Tenant Admin hoặc người có quyền quản trị Channels.
- Nhân sự kỹ thuật triển khai kênh nhắn tin.
- Quản lý vận hành cần kiểm tra luồng Queue/AI Agent.
Phạm vi tài liệu
- Có: tạo bot, kết nối token, routing, kiểm thử.
- Không bao gồm: thiết kế system prompt chi tiết.
- Không bao gồm: cấu hình nhân sự và SLA của Queue.
Luồng thiết lập
- Tạo bot trên @BotFather
- Lấy Bot Token
- Kết nối vào Channels
- Cấu hình Routing
- Gửi tin nhắn kiểm tra
Điều kiện trước khi bắt đầu
- Có tài khoản Telegram để tạo bot thông qua tài khoản chính thức @BotFather.
- Có quyền Tenant Admin trên HAINIVA AICC để truy cập Organization → Channels.
- Đã có Queue/Agent hoặc AI Agent loại Chat được xuất bản, tùy phương án định tuyến.
- Đã xác định kênh hoạt động theo giờ làm việc hay 24/7.
Bot Token tương đương thông tin đăng nhập của bot. Không đưa token thật vào tài liệu, ảnh chụp màn hình, nhóm chat công khai hoặc kho mã nguồn.
02. Tạo bot và lấy Bot Token
Chọn đúng nhánh theo tình trạng bot hiện tại. Toàn bộ phần này được thực hiện trong ứng dụng Telegram — chưa cần đăng nhập HAINIVA AICC.
- Chưa có bot — tạo bot mới
- Đã có bot — lấy lại Bot Token
Bước 1 — Tìm @BotFather
Mở Telegram và tìm tài khoản @BotFather có dấu xác minh.
Hình 1. Tìm đúng tài khoản @BotFather trên Telegram.
Bước 2 — Khởi động BotFather
Mở cuộc trò chuyện và gửi lệnh /start.
Hình 2. Danh sách lệnh quản lý bot của @BotFather.
Bước 3 — Gửi lệnh /newbot
BotFather bắt đầu quy trình tạo bot mới.
Hình 3. BotFather yêu cầu nhập tên hiển thị của bot.
Bước 4 — Nhập tên hiển thị
Ví dụ: "Trung tâm Anh ngữ ABC". Tên này có thể thay đổi sau.
Tên hiển thị nên giúp khách hàng nhận biết đúng thương hiệu hoặc mục đích của bot.
Bước 5 — Nhập username
Username phải duy nhất trên Telegram và kết thúc bằng "bot", ví dụ: abc_center_bot.
Hình 4. BotFather yêu cầu username kết thúc bằng "bot".
Bước 6 — Sao chép Bot Token
Khi username hợp lệ, BotFather trả về token để kết nối với HAINIVA AICC.
Hình 5. Bot Token do BotFather cấp. Token thật trong ảnh phải được che.
Bạn đã có username của bot và Bot Token. Lưu token ở nơi an toàn để sử dụng tại bước kết nối kênh.
- Mở chat với @BotFather, gửi lệnh
/mybots. - BotFather liệt kê danh sách bot đang có — chọn đúng bot cần kết nối vào AICC.
- Bấm nút API Token trong menu hiện ra.
- BotFather trả về đúng Bot Token hiện tại của bot đó — copy dùng ở Bước 2, không cần tạo bot mới.
Bot Token có toàn quyền điều khiển bot — bất kỳ ai có token này đều gửi/nhận tin nhắn được thay bot. Không dán token vào nơi công khai (chat nhóm, file chia sẻ, ảnh chụp màn hình gửi qua kênh không bảo mật). Nếu nghi ngờ lộ token, quay lại chat với @BotFather và gửi lệnh /revoke để cấp token mới.
03. Kết nối Bot Token vào HAINIVA AICC
Bước 1 — Mở danh sách Channels
Đăng nhập AICC Admin, chọn Organization → Channels → Messaging.
Bước 2 — Chọn Connect Telegram Bot
Trong danh sách kênh Messaging, bấm "+ Connect Telegram Bot".
Hình 6. Khu vực Organization → Channels → Messaging.
Bước 3 — Nhập thông tin kênh
Điền Display name và dán Bot Token đã lấy từ BotFather.
- Display name: tên nội bộ để nhận biết kênh trong AICC; không hiển thị cho người dùng Telegram.
- Bot Token: dán chính xác token, không thêm khoảng trắng ở đầu hoặc cuối.
Hình 7. Modal Connect Telegram Bot gồm Display name và Bot Token.
Bước 4 — Bấm Connect
HAINIVA AICC kiểm tra token. Nếu hợp lệ, kênh được lưu và chuyển sang trạng thái Active.
Hình 8. Telegram Bot hiển thị trạng thái Active sau khi kết nối thành công.
Kênh Telegram Bot xuất hiện trong danh sách Messaging và có trạng thái Active. Tiếp theo cần cấu hình routing; Active chưa đồng nghĩa với việc bot đã trả lời đúng luồng.
04. Cấu hình định tuyến tin nhắn
Tại kênh Telegram Bot đang Active, bấm Configure để xác định tin nhắn sẽ được chuyển đến Queue, Agent hay AI Agent.
Bước 1 — Chọn Direction
Chọn hướng xử lý phù hợp với nghiệp vụ của kênh.
- Blended: hỗ trợ cả luồng nhận và phản hồi tin nhắn; phù hợp với mô hình tư vấn kết hợp AI và người thật.
- Inbound only: chỉ tiếp nhận hội thoại đến.
- Outbound only: chỉ dùng khi tổ chức đã xác định rõ luồng chủ động phù hợp.
Bước 2 — Chọn Workspace
Giới hạn danh sách đích đến theo workspace nếu tổ chức có nhiều bộ phận.
Bước 3 — Chọn Route to
Xác định nơi tiếp nhận và xử lý cuộc trò chuyện.
Hình 9. Cấu hình Direction, Workspace và Route to.
Ý nghĩa các lựa chọn Route to
| Lựa chọn | Khi nên dùng | Kết quả |
|---|---|---|
| Queue | Nhiều tư vấn viên cùng xử lý theo hàng đợi. | Hội thoại được phân phối theo chiến lược của Queue. |
| Agent | Chỉ định một tư vấn viên cụ thể. | Tin nhắn đến trực tiếp agent đã chọn. |
| AI agent | Muốn AI Agent loại Chat phản hồi tự động. | AI xử lý theo system prompt và cấu hình đã xuất bản. |
| Sticky | Muốn ưu tiên giữ khách với agent từng xử lý. | Hệ thống ưu tiên agent cũ; có thể fallback sang Queue. |
| IVR Menu | Tổ chức đã thiết kế menu điều hướng tương ứng. | Người dùng được dẫn qua menu trước khi vào đích xử lý. |
Bước 4 — Cấu hình tin nhắn chào mừng
Nhập Welcome message nếu muốn gửi thông báo đầu tiên khi một contact mở hội thoại mới.
Bước 5 — Chọn thời gian tiếp nhận
Follow business hours hoặc Always active (24/7).
Hình 10. Khu vực Welcome message và thời gian tiếp nhận contact.
Bước 6 — Lưu cấu hình
Bấm Save routing ở cuối bảng để áp dụng.
Direction: Blended → Route to: AI agent → chọn đúng AI Agent loại Chat đã publish → Position: AI answers first → When to accept contacts: Always active (24/7).
Mỗi tin nhắn Telegram mới đã có đích xử lý rõ ràng. Nếu không lưu routing, bot có thể Active nhưng hội thoại không đến đúng Queue/Agent/AI Agent.
05. Kiểm tra kết nối end-to-end
Bước 1 — Mở bot trên Telegram
Tìm đúng username đã tạo ở Bước 1 và bấm Start.
Hình 11. Mở đúng bot và bấm Start.
Bước 2 — Gửi tin nhắn thử
Ví dụ: "Xin chào" hoặc một câu hỏi nghiệp vụ đơn giản.
Hình 12. Gửi tin nhắn kiểm tra từ Telegram.
Bước 3 — Kiểm tra tại AICC
Xác nhận kết quả theo phương án Route to đã chọn.
- Queue/Agent: hội thoại xuất hiện trên Agent Desktop để tư vấn viên tiếp nhận và trả lời.
- AI agent: bot trả lời trên Telegram theo system prompt của AI Agent loại Chat.
Bước 4 — Kiểm tra contact
Vào Customers → Contacts và xác nhận người dùng Telegram được tạo/ghi nhận cùng timeline tương tác.
Checklist nghiệm thu
| Hạng mục | Kết quả mong đợi | Đánh dấu |
|---|---|---|
| Trạng thái kênh | Telegram Bot hiển thị Active. | ☐ Đạt |
| Routing | Đã chọn đúng Queue/Agent/AI Agent và bấm Save routing. | ☐ Đạt |
| Tin nhắn đến | Tin nhắn Telegram xuất hiện đúng đích xử lý. | ☐ Đạt |
| Tin nhắn trả lời | Người dùng nhận được phản hồi trên Telegram. | ☐ Đạt |
| Contact | Contact và timeline được ghi nhận trong Customers → Contacts. | ☐ Đạt |
06. Xử lý lỗi thường gặp
| Hiện tượng | Nguyên nhân cần kiểm tra | Cách xử lý |
|---|---|---|
| Không kết nối được token | Token sai, bị thu hồi hoặc có khoảng trắng thừa. | Sao chép lại token từ BotFather; xóa khoảng trắng; tạo token mới nếu token cũ đã lộ. |
| Kênh Active nhưng không có phản hồi | Chưa Save routing; chưa chọn đích; AI Agent chưa publish. | Mở Configure, kiểm tra Route to, trạng thái AI Agent và lưu lại routing. |
| Chỉ hoạt động trong một số khung giờ | Đang chọn Follow business hours. | Kiểm tra lịch trong Routing hoặc đổi sang Always active (24/7) nếu nghiệp vụ yêu cầu. |
| Tin nhắn không vào Agent Desktop | Direction/Queue/Agent chưa đúng hoặc Queue chưa có người xử lý. | Kiểm tra Blended/Inbound, đích Route to và thành viên của Queue. |
| Không thấy contact mới | Chưa bấm Start, đang thử sai bot hoặc chưa phát sinh tin nhắn mới. | Mở đúng username, bấm Start, gửi tin nhắn và kiểm tra lại Customers → Contacts. |