Quickstart
Dựng bot đầu tiên
Đi hết trang này bạn sẽ có một trợ lý biết dữ liệu của mình, đang trực trên ít nhất một kênh và trả lời được khách thật. Bốn bước đầu không cần viết dòng code nào.
Toàn cảnh 5 bước
| Bước | Làm gì | Ở màn hình nào |
|---|---|---|
| 1 | Tạo tài khoản | /dang-ky |
| 2 | Tạo trợ lý | /dashboard/agents/moi |
| 3 | Nạp kho kiến thức | /dashboard/kien-thuc |
| 4 | Kết nối kênh | /dashboard/kenh |
| 5 | Nhắn thử | /dashboard/hoi-thoai |
Bước 1 — Tạo tài khoản
Vào trang đăng ký và tạo tài khoản bằng email. Hệ thống tự lập một tổ chức cho bạn; mọi thứ sau này — trợ lý, kho kiến thức, kênh, ví tiền, khoá API — đều thuộc về tổ chức đó chứ không thuộc về cá nhân bạn. Nhờ vậy mời đồng nghiệp vào sau này không phải làm lại từ đầu.
Sau khi đăng nhập bạn ở màn hình /dashboard. Ví có sẵn credits dùng thử nên không cần nạp tiền để đi hết hướng dẫn này.
Bước 2 — Tạo trợ lý
Vào /dashboard/agents rồi bấm tạo mới (/dashboard/agents/moi). Biểu mẫu hỏi đúng những thứ quyết định chất lượng trả lời:
| Trường | Nên điền gì |
|---|---|
| Tên trợ lý | Tên nội bộ để bạn phân biệt, ví dụ “Trợ lý bán hàng”. |
| Model | Danh sách lấy từ GET /v1/models. Model đặt tại Việt Nam rẻ nhất và đủ tốt cho hỏi–đáp sản phẩm; câu hỏi phức tạp thì chọn nhóm cao hơn. |
| Chỉ dẫn hệ thống | Nói rõ bot là ai, xưng hô thế nào, được phép hứa gì và khi nào phải chuyển cho người thật. Viết như dặn nhân viên mới. |
| Nhiệt độ | Mặc định 0.3. Càng thấp càng bám sát tài liệu — với chatbot chăm sóc khách hàng thì thấp là tốt. |
| Kho kiến thức | Để trống lúc này, quay lại gắn sau khi làm xong bước 3. |
Bước 3 — Nạp kho kiến thức
Đây là bước quyết định bot trả lời đúng hay bịa. Vào /dashboard/kien-thuc, tạo một kho (đặt tên theo chủ đề, ví dụ “Chính sách & sản phẩm”), rồi mở kho đó ra để thêm tài liệu. Có hai cách nạp:
- Dán link — hệ thống tự tải trang về, bóc phần nội dung và lập chỉ mục.
- Gõ/dán văn bản — hợp với bảng giá, giờ mở cửa, chính sách đổi trả, những thứ không nằm sẵn trên web.
Mỗi tài liệu chạy qua hàng đợi xử lý nên trạng thái sẽ chuyển dần rồi mới hiện số đoạn đã cắt. Tài liệu lỗi (link chết, trang chặn bot) hiện thông báo ngay tại dòng đó và có nút nạp lại — không âm thầm bỏ qua.
Nạp xong, quay lại trợ lý ở bước 2 và chọn kho vừa tạo ở trường Kho kiến thức, rồi lưu.
Bước 4 — Kết nối kênh
Vào /dashboard/kenh, bấm kết nối và chọn loại kênh. Mỗi loại hỏi những thông tin khác nhau vì mỗi nền tảng xác thực một kiểu:
| Loại kênh | Cần chuẩn bị |
|---|---|
| web_widget | Không cần gì — chỉ khai danh sách domain được phép nhúng. |
| telegram | Bot token lấy từ @BotFather. |
| facebook_messenger | Page ID và page access token. |
| instagram_dm | Instagram/Page ID và page access token. |
| Phone number ID, WABA ID và access token. | |
| zalo_oa | Access token và refresh token của Official Account. |
| shopee | Shop ID, access token và refresh token. |
| tiktok_shop | Access token và refresh token của shop. |
Nhanh nhất để thử là Telegram: nhắn cho @BotFather, gõ /newbot, copy token dán vào form. Sau khi lưu, mở trang chi tiết kênh — ở đó có địa chỉ webhook của kênh, và mọi thông tin đăng nhập bạn vừa dán đã được mã hoá trước khi ghi xuống cơ sở dữ liệu.
Cuối cùng nhớ gán trợ lý cho kênh — kênh chưa có trợ lý thì tin nhắn vào vẫn được ghi nhận nhưng bot không trả lời.
Bước 5 — Nhắn thử và soi lại
Nhắn cho bot đúng một câu mà khách hay hỏi nhất. Rồi mở /dashboard/hoi-thoai: bạn thấy nguyên hội thoại, nội dung bot trả lời, tài liệu nào đã được trích dẫn, và hội thoại có bị chuyển cho người thật hay không.
Chi phí thì xem ở /dashboard/vi — từng lần gọi model được ghi lại kèm số token vào/ra và số tiền đã trừ. Nếu con số không như mong đợi, hạ nhiệt độ hoặc đổi sang model rẻ hơn rồi thử lại; đổi model không làm mất dữ liệu hội thoại.
Thêm: đưa bot lên website
Kênh loại web_widget có sẵn một API công khai, gọi được thẳng từ trình duyệt. Chúng tôi chặn theo danh sách allowedOrigins bạn khai lúc tạo kênh, nên hãy điền đúng domain thật của bạn thay vì để trống.
POST https://api.chattudong.com/widget/{channelId}/messages
Content-Type: application/json
{
"sessionId": "khach-ẩn-danh-do-bạn-tự-sinh",
"message": "Shop mở cửa mấy giờ?",
"visitorName": "Khách web"
}Muốn chữ hiện dần như đang gõ thì gọi POST /widget/{channelId}/stream — trả về SSE với các sự kiện meta, delta, done, và kết thúc bằng [DONE]. Ngoài ra có GET /widget/{channelId}/messages?conversationId=… để lấy tin mới khi nhân viên trả lời tay.
Script nhúng dựng sẵn (một thẻ <script> là xong) đang được hoàn thiện. Trong lúc chờ, trang chi tiết kênh trong dashboard hiển thị mã kênh để bạn tự gọi API ở trên.
Tiếp theo
- Gọi model từ backend của bạn: API Reference và SDK & thư viện.
- Đã có sẵn khoá OpenAI/Anthropic riêng: hướng dẫn BYOK — dùng khoá của bạn thì chúng tôi không tính phí model.
- Tự dựng luồng nhận tin từ nền tảng: Webhooks.