Kết nối kênh API tùy chỉnh

Kênh API (API Channel) là giải pháp cổng kết nối vạn năng (Universal Custom Channel) của ChatbotX, cho phép bạn tích hợp bất kỳ nền tảng nhắn tin, ứng dụng di động, website hoặc hệ thống phần mềm nghiệp vụ nào vào Workspace ChatbotX. Khác với các kênh tích hợp mặc định như Facebook Messenger, Zalo OA hay Instagram, Kênh API mang lại sự linh hoạt tối đa bằng cách trao quyền kiểm soát kết nối cho doanh nghiệp thông qua chuẩn giao tiếp REST API và Webhook hai chiều. Mọi tin nhắn của khách hàng gửi đến từ hệ thống tùy chỉnh của bạn sẽ được tiếp nhận và xử lý tập trung trong ChatbotX Inbox, kích hoạt tự động các kịch bản Flow Automation, AI Agent thông minh hoặc phân bổ cho nhân viên tư vấn theo ca trực.

Các ứng dụng thực tế của Kênh API

Kênh API mở ra khả năng tự động hóa không giới hạn cho doanh nghiệp với các kịch bản ứng dụng nổi bật:

In-App Chat cho Ứng dụng & Website

Tích hợp khung chat trực tiếp vào ứng dụng di động riêng (E-commerce, Giao hàng, Fintech, Thành viên) hoặc website của bạn. Khách hàng trò chuyện ngay trong app trong khi AI Agent và nhân viên CSKH quản lý tập trung tại ChatbotX Inbox.

Kết nối Nền tảng Nhắn tin Bên thứ ba

Tích hợp các mạng xã hội và ứng dụng nhắn tin chưa có sẵn mặc định như Viber, Telegram Bot chuyên dụng, LINE, WeChat, Discord hoặc hệ thống Live Chat nội bộ của công ty.

Cổng SMS Gateway Hai Chiều

Kết nối với nhà mạng hoặc dịch vụ đầu số SMS (Twilio, SpeedSMS, eSMS). Khi khách hàng phản hồi SMS, tin nhắn sẽ được đẩy vào ChatbotX để AI Agent xử lý và gửi phản hồi tự động qua SMS.

Kết nối WhatsApp Cá nhân / Web

Sử dụng chính số điện thoại cá nhân hiện có của doanh nghiệp để trò chuyện 1:1 với khách hàng thông qua cổng trung gian (như WAHA) mà không phải trả phí duy trì hội thoại của Meta.

Đồng bộ Hệ thống CRM & ERP

Kết nối với các hệ sinh thái doanh nghiệp như Salesforce, HubSpot, Zoho, Odoo để tự động gửi thông báo đơn hàng, cập nhật trạng thái hợp đồng hoặc tiếp nhận yêu cầu hỗ trợ từ khách hàng.

Tích hợp Tự động hóa (n8n, Make, Zapier)

Kết nối ChatbotX với các công cụ workflow như n8n, Make.com hoặc Zapier để xây dựng luồng xử lý thông minh, tra cứu dữ liệu thời gian thực và kích hoạt AI Agent phản hồi tức thì.

Tài liệu kỹ thuật API Reference

Nếu bạn là nhà phát triển muốn tích hợp Kênh API trực tiếp với ứng dụng di động, website riêng hoặc cổng tin nhắn nội bộ của doanh nghiệp, ChatbotX cung cấp trọn bộ 5 API tiêu chuẩn cùng Webhook gửi dữ liệu hai chiều: 👉 Xem tài liệu tương tác đầy đủ: ChatbotX API Reference (API Channel)

Cơ chế xác thực (Authentication)

Mọi yêu cầu gọi đến API Channel đều bắt buộc truyền Channel API Token trong Header:

Authorization: Bearer cbx_api_your_channel_token_here
Content-Type: application/json

1. Xác thực Token và Kiểm tra thông tin kênh (`GET /v1/channels/api/me`)

Dùng để xác thực tính hợp lệ của Channel API Token và lấy thông tin định danh của Inbox kết nối trong Workspace.

curl -X GET "https://app.chatbotx.io/api/v1/channels/api/me" \
  -H "Authorization: Bearer cbx_api_your_token_here"

{
  "inboxId": "105",
  "inboxName": "App Mobile Khách Hàng",
  "workspaceId": "42"
}

2. Gửi tin nhắn từ ứng dụng vào ChatbotX (`POST /v1/channels/api/messages`)

Dùng để đẩy tin nhắn của khách hàng từ ứng dụng vào ChatbotX Inbox. Hệ thống sẽ tự động tạo hoặc cập nhật hồ sơ khách hàng (contact) và kích hoạt Flow Automation hoặc AI Agent trả lời. Hỗ trợ đầy đủ tin nhắn văn bản, tệp đính kèm (hình ảnh, âm thanh, video, tệp tài liệu), vị trí địa lý (location) và postbackPayload.

curl -X POST "https://app.chatbotx.io/api/v1/channels/api/messages" \
  -H "Authorization: Bearer cbx_api_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "contact": {
      "sourceId": "user_app_99182",
      "firstName": "Nguyen",
      "lastName": "Van A",
      "email": "vana@example.com",
      "phoneNumber": "+84901234567",
      "avatar": "https://example.com/avatar.jpg"
    },
    "message": {
      "sourceId": "msg_001",
      "text": "Xin chào, tôi cần tư vấn về sản phẩm",
      "contentType": "text",
      "attachments": [
        {
          "url": "https://example.com/san-pham.jpg",
          "fileType": "image",
          "mimeType": "image/jpeg",
          "name": "san-pham.jpg"
        }
      ]
    }
  }'

{
  "accepted": true,
  "messageSourceId": "msg_001"
}

3. Báo hiệu trạng thái đang gõ phím (`POST /v1/channels/api/typing`)

Gửi tín hiệu thông báo cho ChatbotX Inbox biết người dùng đang nhập tin nhắn (hiển thị hiệu ứng “typing…” trên màn hình trực chat của tư vấn viên).

curl -X POST "https://app.chatbotx.io/api/v1/channels/api/typing" \
  -H "Authorization: Bearer cbx_api_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "contact": {
      "sourceId": "user_app_99182"
    },
    "typing": true
  }'

// HTTP 204 No Content - Tiếp nhận thành công

4. Báo hiệu khách hàng đã đọc tin nhắn (`POST /v1/channels/api/read`)

Thông báo cho ChatbotX biết khách hàng đã mở xem các tin nhắn phản hồi được gửi từ AI Agent hoặc nhân viên tư vấn.

curl -X POST "https://app.chatbotx.io/api/v1/channels/api/read" \
  -H "Authorization: Bearer cbx_api_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "contact": {
      "sourceId": "user_app_99182"
    }
  }'

// HTTP 204 No Content - Tiếp nhận thành công

5. Cập nhật trạng thái chuyển phát tin nhắn (`POST /v1/channels/api/delivery-status`)

Báo cáo trạng thái gửi tin nhắn đi (Outbound message) cho ChatbotX khi tin nhắn đã được chuyển đến máy khách (delivered), đã đọc (read) hoặc thất bại (failed).

curl -X POST "https://app.chatbotx.io/api/v1/channels/api/delivery-status" \
  -H "Authorization: Bearer cbx_api_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "messageId": "msg_outbound_88219",
    "status": "delivered",
    "timestamp": "2026-08-28T10:00:00Z"
  }'

// HTTP 204 No Content - Tiếp nhận thành công

Nhận tin nhắn trả lời qua Callback URL (Outbound Webhook)

Khi AI Agent, Flow Automation hoặc nhân viên tư vấn gửi tin nhắn phản hồi trong ChatbotX Inbox, hệ thống sẽ tự động gửi một yêu cầu POST chứa dữ liệu tin nhắn đến địa chỉ Callback URL mà bạn đã cấu hình cho Kênh API. Cấu trúc gói tin Webhook mẫu gửi đến máy chủ của bạn:

{
  "event": "message:created",
  "messageId": "msg_outbound_88219",
  "conversationId": "conv_5501",
  "contact": {
    "sourceId": "user_app_99182",
    "name": "Nguyen Van A"
  },
  "message": {
    "text": "Chào bạn, đơn hàng của bạn đã được xác nhận thành công!",
    "contentType": "text",
    "attachments": []
  },
  "timestamp": "2026-08-28T10:00:00Z"
}

Hướng dẫn cài đặt và tích hợp WhatsApp cá nhân qua WAHA ChatbotX Dashboard

Bạn có thể kết nối số điện thoại WhatsApp cá nhân của mình vào ChatbotX thông qua các bước hướng dẫn dưới đây:

Phần 1: Hướng dẫn cài đặt WAHA ChatbotX Dashboard

WAHA (WhatsApp HTTP API) là giải pháp cổng kết nối độc lập mã nguồn mở. Phiên bản WAHA ChatbotX Dashboard được tối ưu hóa đặc biệt với giao diện Dashboard trực quan, tích hợp sẵn cơ chế đồng bộ và Webhook định tuyến chuyên biệt cho ChatbotX.

Yêu cầu hệ thống:

Máy tính cá nhân (Windows, macOS) hoặc máy chủ VPS Linux (Ubuntu 20.04+, Debian 11+).
Đã cài đặt sẵn Docker và Docker Compose.

Các bước triển khai chi tiết:

Tải mã nguồn cấu hình: Mở cửa sổ dòng lệnh (Terminal hoặc PowerShell) và tải repository:
git clone https://github.com/craybull/waha-chatbotx-dashboard.git cd waha-chatbotx-dashboard
Kiểm tra tệp cấu hình docker-compose.chatbotx.yaml: Tệp cấu hình đã được thiết lập sẵn mọi biến môi trường tối ưu cho ChatbotX (bao gồm engine WebJS, cổng dịch vụ 3000, đường dẫn lưu trữ phiên và dashboard tích hợp).
Khởi chạy dịch vụ ngầm với Docker Compose: Chạy lệnh sau để tải container và khởi động hệ thống:
docker compose -f docker-compose.chatbotx.yaml up -d
Truy cập giao diện quản trị: Sau khi container khởi chạy thành công, mở trình duyệt web và truy cập địa chỉ:
- Nếu chạy trên máy cá nhân: http://localhost:3000/dashboard
- Nếu chạy trên máy chủ VPS: https://<ten-mien-cua-ban>/dashboard

🔐 Thông tin đăng nhập mặc định (HTTP Basic Auth):

Username: admin

Password: Abcd@1234

(Bạn có thể tùy chỉnh tên đăng nhập và mật khẩu này trong tệp docker-compose.chatbotx.yaml trước khi khởi chạy).

Giao diện Dashboard hiển thị đầy đủ các khu vực thao tác gồm: Thanh danh sách Đa tài khoản ở trên cùng, Khung kết nối WhatsApp (Step 1 ở cột trái), Tạo kênh ChatbotX (Step 2 ở góc trên bên phải) và Kích hoạt Token (Step 3 ở góc dưới bên phải).

Phần 2: Hướng dẫn tạo Kênh API và Tích hợp WhatsApp cá nhân

Để kết nối số WhatsApp của bạn với ChatbotX, hãy thực hiện theo các bước sau:

Bước 1: Kết nối tài khoản WhatsApp (Step 1 trên Dashboard)

Tại khung Step 1: Connect WhatsApp Account ở cột bên trái Dashboard, bạn chọn 1 trong 2 phương thức kết nối:

Cách 1: Quét mã QR Code (Khuyên dùng):
1. Mở ứng dụng WhatsApp trên điện thoại của bạn.
2. Vào Cài đặt (Settings) > chọn Thiết bị liên kết (Linked Devices).
3. Bấm Liên kết thiết bị (Link a Device) và hướng camera quét mã QR hiển thị trên màn hình máy tính.

Ngay sau khi quét thành công, Dashboard sẽ tự động nhận diện và chuyển sang thẻ trạng thái màu xanh Connected Online hiển thị tên đại diện và số điện thoại của bạn.

Cách 2: Nhận mã số ghép nối (Phone Pairing Code):
1. Chọn tab Phone Pairing Code nếu camera điện thoại khó quét mã.
2. Nhập số điện thoại WhatsApp của bạn theo định dạng quốc tế (bao gồm mã quốc gia, bỏ số 0 ở đầu).
3. Bấm Get Code để nhận mã 8 chữ số, sau đó mở WhatsApp trên điện thoại > Linked Devices > Link with phone number > nhập mã 8 chữ số để xác thực.

Waha Dashboard Step 1 Phone Pairing Code

Bước 2: Tạo Kênh API trên ChatbotX (Step 2 trên Dashboard)

Tại khung Step 2: Create Channel on ChatbotX ở góc trên cột bên phải của Dashboard WAHA:

Bấm nút Open ChatbotX để mở nhanh trang tạo kênh trong tab mới, đồng thời sao chép 2 thông tin đã được Dashboard tạo sẵn:
- Name (Tên kênh): Tên gợi ý đã được Dashboard tự động đồng bộ theo hồ sơ WhatsApp của bạn.
- Callback URL: Đường dẫn Webhook nhận tin nhắn riêng biệt đã được tạo sẵn cho số điện thoại này.

Trên ChatbotX, vào Settings > Channels > chọn API > bấm nút Add API ở góc trên bên phải.

Trong cửa sổ pop-up Add API, bạn dán Tên kênh và Callback URL vừa sao chép từ Dashboard WAHA vào các ô tương ứng:

💡 Lưu ý quan trọng: Kênh API được thiết kế chuyên biệt cho việc thiết lập kênh trò chuyện giao tiếp hai chiều (Callback URL dùng để nhận tin nhắn phản hồi từ bot hoặc nhân viên CSKH). Nếu nhu cầu của bạn chỉ là gửi tin nhắn thông báo một chiều từ server bên ngoài hoặc thao tác dữ liệu hệ thống (như quản lý liên hệ, kích hoạt Flow tự động), bạn không cần tạo Kênh API. Thay vào đó, hãy tham khảo trực tiếp bộ tài liệu REST API tổng quan của ChatbotX tại:
👉 API Overview - ChatbotX Documentation

Bấm nút Create màu xanh để tạo kênh và sao chép chuỗi Channel API Token (dạng cbx_api_...) vừa được tạo.

Bước 3: Lưu Token và Kích hoạt Kênh (Step 3 trên Dashboard)

Tại khung Step 3: Link ChatbotX Channel ở góc dưới cột bên phải của Dashboard WAHA:

Dán mã Channel API Token vừa sao chép từ ChatbotX vào ô ChatbotX API Token.
Tích chọn ô Forward WhatsApp group messages to ChatbotX nếu bạn muốn bot xử lý cả tin nhắn trong các nhóm chat WhatsApp.
Bấm nút Save & Activate Channel để hoàn tất.

Khi liên kết thành công, huy hiệu góc trên sẽ chuyển sang màu xanh Linked & Active. Kể từ thời điểm này, mọi tin nhắn của khách hàng gửi đến số WhatsApp sẽ tự động đồng bộ vào ChatbotX Inbox.

Bước 4: Gửi tin nhắn thử nghiệm (Test Outbound Message)

Bạn có thể kiểm tra tốc độ gửi tin nhắn trực tiếp ngay trên Dashboard:

Tại khung Test Outbound Message (ở góc dưới cột bên trái), nhập số điện thoại người nhận (kèm mã quốc gia).
Nhập nội dung tin nhắn và bấm Send Test Message.
Người nhận sẽ lập tức nhận được tin nhắn trực tiếp từ số WhatsApp vừa kết nối.

Quản lý Đa tài khoản WhatsApp

Nếu doanh nghiệp của bạn có nhiều số điện thoại WhatsApp cho từng bộ phận (CSKH, Kinh doanh Hà Nội, Chi nhánh TP.HCM):

Trên thanh danh sách tài khoản ở đầu trang Dashboard, bấm nút Add Account (+).
Nhập tên định danh cho số mới (ví dụ: sales_hn, hotline_hcm).
Lặp lại quy trình quét mã và tạo Kênh API trên ChatbotX tương ứng cho từng số.

Câu hỏi thường gặp (FAQ)

Kênh API có giới hạn số lượng tin nhắn gửi và nhận không?

ChatbotX không đặt giới hạn số lượng tin nhắn trên Kênh API. Tốc độ và số lượng tin nhắn xử lý phụ thuộc vào gói đăng ký Workspace của bạn và năng lực hạ tầng server webhook do bạn vận hành.

Tôi có thể kết nối nhiều số WhatsApp cá nhân vào một Workspace không?

Có. Bạn có thể kết nối không giới hạn số lượng tài khoản WhatsApp. Mỗi số điện thoại sẽ tương ứng với một Kênh API riêng biệt trên ChatbotX để bạn dễ dàng phân loại và quản lý hội thoại.

Khi nào tôi nên dùng WhatsApp cá nhân và khi nào nên dùng WhatsApp Cloud API chính thức?

Dùng WhatsApp cá nhân (qua Gateway WAHA): Phù hợp khi bạn muốn dùng lại chính số điện thoại hiện tại của mình để trò chuyện 1:1 với khách hàng, tiết kiệm chi phí hội thoại của Meta và chia sẻ một số cho nhiều nhân viên cùng trực chat.
Dùng WhatsApp Cloud API chính thức: Phù hợp khi bạn cần gửi tin nhắn quảng cáo hàng loạt (Broadcasts) cho hàng chục nghìn khách hàng, sử dụng các mẫu Template được Meta duyệt, hoặc cần đăng ký dấu tích xanh doanh nghiệp chính chủ.

Nếu điện thoại của tôi mất mạng thì hệ thống có nhận được tin nhắn không?

WhatsApp hoạt động theo cơ chế Thiết bị liên kết (Linked Devices). Sau khi đã ghép nối thành công, hệ thống máy chủ Gateway sẽ duy trì phiên hoạt động độc lập và tiếp nhận tin nhắn từ khách hàng ngay cả khi điện thoại của bạn tạm thời tắt nguồn hoặc mất mạng.

Bắt đầu

Tự động hóa

AI Agents

Liên hệ

Inbox

Remarketing

Triggers

Công cụ

Kênh

Tích hợp

Các ứng dụng thực tế của Kênh API

In-App Chat cho Ứng dụng & Website

Kết nối Nền tảng Nhắn tin Bên thứ ba

Cổng SMS Gateway Hai Chiều

Kết nối WhatsApp Cá nhân / Web

Đồng bộ Hệ thống CRM & ERP

Tích hợp Tự động hóa (n8n, Make, Zapier)

Tài liệu kỹ thuật API Reference

Cơ chế xác thực (Authentication)

1. Xác thực Token và Kiểm tra thông tin kênh (`GET /v1/channels/api/me`)

2. Gửi tin nhắn từ ứng dụng vào ChatbotX (`POST /v1/channels/api/messages`)

3. Báo hiệu trạng thái đang gõ phím (`POST /v1/channels/api/typing`)

4. Báo hiệu khách hàng đã đọc tin nhắn (`POST /v1/channels/api/read`)

5. Cập nhật trạng thái chuyển phát tin nhắn (`POST /v1/channels/api/delivery-status`)

Nhận tin nhắn trả lời qua Callback URL (Outbound Webhook)

Hướng dẫn cài đặt và tích hợp WhatsApp cá nhân qua WAHA ChatbotX Dashboard

Phần 1: Hướng dẫn cài đặt WAHA ChatbotX Dashboard

Yêu cầu hệ thống:

Các bước triển khai chi tiết:

Phần 2: Hướng dẫn tạo Kênh API và Tích hợp WhatsApp cá nhân

Bước 1: Kết nối tài khoản WhatsApp (Step 1 trên Dashboard)

Bước 2: Tạo Kênh API trên ChatbotX (Step 2 trên Dashboard)

Bước 3: Lưu Token và Kích hoạt Kênh (Step 3 trên Dashboard)

Bước 4: Gửi tin nhắn thử nghiệm (Test Outbound Message)

Quản lý Đa tài khoản WhatsApp

Câu hỏi thường gặp (FAQ)

​Các ứng dụng thực tế của Kênh API

In-App Chat cho Ứng dụng & Website

Kết nối Nền tảng Nhắn tin Bên thứ ba

Cổng SMS Gateway Hai Chiều

Kết nối WhatsApp Cá nhân / Web

Đồng bộ Hệ thống CRM & ERP

Tích hợp Tự động hóa (n8n, Make, Zapier)

​Tài liệu kỹ thuật API Reference

​Cơ chế xác thực (Authentication)

​1. Xác thực Token và Kiểm tra thông tin kênh (GET /v1/channels/api/me)

​2. Gửi tin nhắn từ ứng dụng vào ChatbotX (POST /v1/channels/api/messages)

​3. Báo hiệu trạng thái đang gõ phím (POST /v1/channels/api/typing)

​4. Báo hiệu khách hàng đã đọc tin nhắn (POST /v1/channels/api/read)

​5. Cập nhật trạng thái chuyển phát tin nhắn (POST /v1/channels/api/delivery-status)

​Nhận tin nhắn trả lời qua Callback URL (Outbound Webhook)

​Hướng dẫn cài đặt và tích hợp WhatsApp cá nhân qua WAHA ChatbotX Dashboard

​Phần 1: Hướng dẫn cài đặt WAHA ChatbotX Dashboard

​Yêu cầu hệ thống:

​Các bước triển khai chi tiết:

​Phần 2: Hướng dẫn tạo Kênh API và Tích hợp WhatsApp cá nhân

​Bước 1: Kết nối tài khoản WhatsApp (Step 1 trên Dashboard)

​Bước 2: Tạo Kênh API trên ChatbotX (Step 2 trên Dashboard)

​Bước 3: Lưu Token và Kích hoạt Kênh (Step 3 trên Dashboard)

​Bước 4: Gửi tin nhắn thử nghiệm (Test Outbound Message)

​Quản lý Đa tài khoản WhatsApp

​Câu hỏi thường gặp (FAQ)

Các ứng dụng thực tế của Kênh API

Tài liệu kỹ thuật API Reference

Cơ chế xác thực (Authentication)

1. Xác thực Token và Kiểm tra thông tin kênh (`GET /v1/channels/api/me`)

2. Gửi tin nhắn từ ứng dụng vào ChatbotX (`POST /v1/channels/api/messages`)

3. Báo hiệu trạng thái đang gõ phím (`POST /v1/channels/api/typing`)

4. Báo hiệu khách hàng đã đọc tin nhắn (`POST /v1/channels/api/read`)

5. Cập nhật trạng thái chuyển phát tin nhắn (`POST /v1/channels/api/delivery-status`)

Nhận tin nhắn trả lời qua Callback URL (Outbound Webhook)

Hướng dẫn cài đặt và tích hợp WhatsApp cá nhân qua WAHA ChatbotX Dashboard

Phần 1: Hướng dẫn cài đặt WAHA ChatbotX Dashboard

Yêu cầu hệ thống:

Các bước triển khai chi tiết:

Phần 2: Hướng dẫn tạo Kênh API và Tích hợp WhatsApp cá nhân

Bước 1: Kết nối tài khoản WhatsApp (Step 1 trên Dashboard)

Bước 2: Tạo Kênh API trên ChatbotX (Step 2 trên Dashboard)

Bước 3: Lưu Token và Kích hoạt Kênh (Step 3 trên Dashboard)

Bước 4: Gửi tin nhắn thử nghiệm (Test Outbound Message)

Quản lý Đa tài khoản WhatsApp

Câu hỏi thường gặp (FAQ)