> ## Documentation Index
> Fetch the complete documentation index at: https://chatbotx.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

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

> Tìm hiểu Kênh API trên ChatbotX, các ứng dụng thực tế để kết nối ứng dụng tùy chỉnh, CRM, SMS, WhatsApp cá nhân và tài liệu API Reference.

**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.

<Frame>
  <img src="https://mintcdn.com/chatbotx/GTs_ufUQ5A9YTRLS/images/add_api_channel_settings_overview.png?fit=max&auto=format&n=GTs_ufUQ5A9YTRLS&q=85&s=38edee78e75ce50dc2c7558c4842606e" alt="Add Api Channel Settings Overview" width="3057" height="1823" data-path="images/add_api_channel_settings_overview.png" />
</Frame>

## 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:

<CardGroup cols={2}>
  <Card title="In-App Chat cho Ứng dụng & Website" icon="mobile-screen-button">
    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.
  </Card>

  <Card title="Kết nối Nền tảng Nhắn tin Bên thứ ba" icon="comments">
    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.
  </Card>

  <Card title="Cổng SMS Gateway Hai Chiều" icon="comment-sms">
    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.
  </Card>

  <Card title="Kết nối WhatsApp Cá nhân / Web" icon="whatsapp">
    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.
  </Card>

  <Card title="Đồng bộ Hệ thống CRM & ERP" icon="network-wired">
    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.
  </Card>

  <Card title="Tích hợp Tự động hóa (n8n, Make, Zapier)" icon="diagram-project">
    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ì.
  </Card>
</CardGroup>

## 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)**](https://app.chatbotx.io/api#tag/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:

```http theme={null}
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.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://app.chatbotx.io/api/v1/channels/api/me" \
    -H "Authorization: Bearer cbx_api_your_token_here"
  ```

  ```json Response (200 OK) theme={null}
  {
    "inboxId": "105",
    "inboxName": "App Mobile Khách Hàng",
    "workspaceId": "42"
  }
  ```
</CodeGroup>

### 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`.

<CodeGroup>
  ```bash cURL theme={null}
  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"
          }
        ]
      }
    }'
  ```

  ```json Response (202 Accepted) theme={null}
  {
    "accepted": true,
    "messageSourceId": "msg_001"
  }
  ```
</CodeGroup>

### 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).

<CodeGroup>
  ```bash cURL theme={null}
  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
    }'
  ```

  ```json Response (204 No Content) theme={null}
  // HTTP 204 No Content - Tiếp nhận thành công
  ```
</CodeGroup>

### 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.

<CodeGroup>
  ```bash cURL theme={null}
  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"
      }
    }'
  ```

  ```json Response (204 No Content) theme={null}
  // HTTP 204 No Content - Tiếp nhận thành công
  ```
</CodeGroup>

### 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`).

<CodeGroup>
  ```bash cURL theme={null}
  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"
    }'
  ```

  ```json Response (204 No Content) theme={null}
  // HTTP 204 No Content - Tiếp nhận thành công
  ```
</CodeGroup>

### 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:

```json theme={null}
{
  "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:

1. **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:
   ```bash theme={null}
   git clone https://github.com/craybull/waha-chatbotx-dashboard.git
   cd waha-chatbotx-dashboard
   ```
2. **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).
3. **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:
   ```bash theme={null}
   docker compose -f docker-compose.chatbotx.yaml up -d
   ```
4. **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.

<Frame>
  <img src="https://mintcdn.com/chatbotx/Ky6Dp0JpSbn--cT0/images/waha_dashboard_step1_qr_code_scan.png?fit=max&auto=format&n=Ky6Dp0JpSbn--cT0&q=85&s=3061881e2099129083e78fdf89c5d27b" alt="Waha Dashboard Step1 Qr Code Scan" width="1897" height="1693" data-path="images/waha_dashboard_step1_qr_code_scan.png" />
</Frame>

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.

<Frame>
  <img src="https://mintcdn.com/chatbotx/Ky6Dp0JpSbn--cT0/images/waha_dashboard_step1_phone_pairing_code.png?fit=max&auto=format&n=Ky6Dp0JpSbn--cT0&q=85&s=9ae286b704aeac759d153d04cc043b3f" alt="Waha Dashboard Step 1 Phone Pairing Code" width="1910" height="1707" data-path="images/waha_dashboard_step1_phone_pairing_code.png" />
</Frame>

#### 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:

1. 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.

<Frame>
  <img src="https://mintcdn.com/chatbotx/Ky6Dp0JpSbn--cT0/images/waha_dashboard_step2_callback_url_copy.png?fit=max&auto=format&n=Ky6Dp0JpSbn--cT0&q=85&s=b6237dd2f4a789e3861b773e83b11ba4" alt="Waha Dashboard Step 2 Callback Url Copy" width="797" height="533" data-path="images/waha_dashboard_step2_callback_url_copy.png" />
</Frame>

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

<Frame>
  <img src="https://mintcdn.com/chatbotx/GTs_ufUQ5A9YTRLS/images/add_api_channel_settings_overview.png?fit=max&auto=format&n=GTs_ufUQ5A9YTRLS&q=85&s=38edee78e75ce50dc2c7558c4842606e" alt="Add Api Channel Settings Overview" width="3057" height="1823" data-path="images/add_api_channel_settings_overview.png" />
</Frame>

3. 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:<br />👉 [**API Overview - ChatbotX Documentation**](https://chatbotx.io/docs/api-reference/api-overview)

<Frame>
  <img src="https://mintcdn.com/chatbotx/GTs_ufUQ5A9YTRLS/images/add_api_channel_modal_setup_form.png?fit=max&auto=format&n=GTs_ufUQ5A9YTRLS&q=85&s=f4059fe6952ba1cd6040056751d70331" alt="Api Channel Modal Setup Form" width="3053" height="1818" data-path="images/add_api_channel_modal_setup_form.png" />
</Frame>

4. 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.

<Frame>
  <img src="https://mintcdn.com/chatbotx/GTs_ufUQ5A9YTRLS/images/api_channel_created_token.png?fit=max&auto=format&n=GTs_ufUQ5A9YTRLS&q=85&s=f046671dac8e3ec45379786fa7354cd7" alt="Api Channel Created Token" width="3055" height="1816" data-path="images/api_channel_created_token.png" />
</Frame>

#### 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:

1. Dán mã **Channel API Token** vừa sao chép từ ChatbotX vào ô **ChatbotX API Token**.
2. 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.
3. Bấm nút **Save & Activate Channel** để hoàn tất.

<Frame>
  <img src="https://mintcdn.com/chatbotx/Ky6Dp0JpSbn--cT0/images/waha_dashboard_step3_activate_token.png?fit=max&auto=format&n=Ky6Dp0JpSbn--cT0&q=85&s=188878211a5b00af5870c9044f92032b" alt="Waha Dashboard Step 3 Activate Token" width="776" height="785" data-path="images/waha_dashboard_step3_activate_token.png" />
</Frame>

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:

1. 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).
2. Nhập nội dung tin nhắn và bấm **Send Test Message**.
3. 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.

<Frame>
  <img src="https://mintcdn.com/chatbotx/Ky6Dp0JpSbn--cT0/images/waha_dashboard_test_outbound_message.png?fit=max&auto=format&n=Ky6Dp0JpSbn--cT0&q=85&s=64fb86a23b8e4276e377b1bfbe667b96" alt="Waha Dashboard Test Outbound Message" width="1372" height="616" data-path="images/waha_dashboard_test_outbound_message.png" />
</Frame>

#### 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):

1. Trên thanh danh sách tài khoản ở đầu trang Dashboard, bấm nút **Add Account** (`+`).
2. Nhập tên định danh cho số mới (ví dụ: `sales_hn`, `hotline_hcm`).
3. 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)

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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ủ.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.