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

# Inbound Webhooks

> Nhận dữ liệu JSON từ các hệ thống bên ngoài để tìm hoặc tạo liên hệ, cập nhật trường tùy chỉnh và kích hoạt các hành động tự động trong ChatbotX.

**Inbound Webhooks (Webhook tiếp nhận dữ liệu)** cho phép các ứng dụng bên thứ ba như Website, nền tảng thương mại điện tử (Shopify, WooCommerce), CRM, cổng thanh toán hoặc hệ thống quản lý nội bộ gửi dữ liệu thời gian thực trực tiếp vào Workspace ChatbotX mà không cần thông qua các công cụ trung gian như Zapier hay Make.

Khi một hệ thống bên ngoài gửi một HTTP `POST` request chứa dữ liệu JSON đến đường dẫn Webhook URL của bạn, ChatbotX sẽ tự động đối soát để tìm hoặc tạo mới liên hệ, lưu các giá trị trích xuất vào trường tương ứng và kích hoạt các hành động tự động hóa tiếp theo (như gắn thẻ hoặc chạy kịch bản chăm sóc).

![Inbound Webhooks Tools Card](https://mintcdn.com/chatbotx/dHddCrlyPo0xda94/images/inbound_webhooks_tools_card.png?fit=max\&auto=format\&n=dHddCrlyPo0xda94\&q=85\&s=eb7f9036e1ad518b6ae13c62ac37eeb6)

Vị trí thẻ Inbound Webhooks trong danh mục Tools

## Phân biệt các cơ chế Webhook trong ChatbotX

Để lựa chọn đúng công cụ cho nhu cầu tự động hóa của bạn, hãy phân biệt 3 cơ chế webhook có sẵn trong ChatbotX:

| Tính năng | Vị trí | Chiều dữ liệu | Tình huống sử dụng phổ biến |
| - | - | - | - |
| **Inbound Webhooks** | **Tools > Inbound Webhooks** | Hệ thống ngoài → ChatbotX | Thu thập khách hàng tiềm năng từ Form website, nhận thông báo đơn hàng mới từ Shopify/WooCommerce, xác nhận thanh toán thành công và đồng bộ dữ liệu từ CRM. |
| **Outbound Webhooks** | **Triggers > Webhooks** | ChatbotX → Hệ thống ngoài | Đẩy thông tin liên hệ sang CRM ngoài, báo cho phần mềm kho khi có đơn hàng được gán thẻ, hoặc gửi thông báo sang hệ thống vận chuyển. |
| **External API Request** | **Flow Builder (Khối Action)** | Hai chiều (Đồng bộ) | Tra cứu trạng thái đơn hàng trực tiếp, lấy tỷ giá tiền tệ theo thời gian thực hoặc kiểm tra mã giảm giá ngay trong lúc khách đang nhắn tin với bot. |

## Nguyên lý hoạt động và quy tắc cốt lõi

### 1. Giao thức yêu cầu (Request Protocol)

Hệ thống gửi phải phát một HTTP request với phương thức `POST`, định dạng dữ liệu JSON chuẩn (`Content-Type: application/json`) tới endpoint Webhook URL đã được cấp.

### 2. Quy tắc định danh liên hệ (Thứ tự ưu tiên tìm kiếm)

ChatbotX sẽ tìm kiếm liên hệ sẵn có trong hộp thư (inbox) được chỉ định theo 4 cấp độ ưu tiên:

1. **Channel User ID** (ví dụ: `Messenger PSID`, số điện thoại WhatsApp hoặc Telegram User ID)
2. **Số điện thoại (Phone)** (khuyến nghị chuẩn quốc tế E.164, ví dụ `+84901234567`)
3. **Email** (ví dụ: `alex.johnson@example.com`)
4. **Họ và tên (Full name)** (ví dụ: `Alex Johnson`)

Nếu tìm thấy liên hệ trùng khớp, ChatbotX sẽ cập nhật thông tin vào hồ sơ của liên hệ đó. Nếu không tìm thấy ai trùng khớp, hệ thống sẽ tự động tạo một liên hệ mới thuộc hộp thư tương ứng.

### 3. Trình tự xử lý dữ liệu

Khi có request gửi đến Webhook, ChatbotX xử lý tuần tự theo quy trình:

```mermaid theme={null}
graph TD
    A["1. Nhận JSON Request"] --> B["2. Định tuyến đến Inbox mục tiêu"]
    B --> C["3. Tìm hoặc Tạo mới liên hệ"]
    C --> D["4. Ghi dữ liệu vào các trường liên hệ"]
    D --> E["5. Chạy các hành động trong 'After saving data'"]
```

## Hướng dẫn thiết lập từng bước

**1. Truy cập Inbound Webhooks và tạo webhook mới**

Từ thanh menu bên trái, nhấp vào mục **Tools**, sau đó chọn thẻ **Inbound Webhooks**.

Tại bảng điều khiển Inbound Webhooks, nhấp vào nút xanh **+ Create Inbound webhook** ở góc trên bên phải.

![Danh sách Inbound Webhooks](https://mintcdn.com/chatbotx/dHddCrlyPo0xda94/images/inbound_webhooks_dashboard_list.png?fit=max\&auto=format\&n=dHddCrlyPo0xda94\&q=85\&s=de2eb8e889782b87890c7814f806f476)

Bảng điều khiển danh sách Inbound Webhooks và các tùy chọn quản lý

Đặt tên cho Webhook thể hiện rõ mục đích tích hợp (ví dụ: `New Order Follow-up` hoặc `Thu thập Lead Website`).

**2. Dán và nạp dữ liệu mẫu (Sample JSON)**

Lấy một mẫu dữ liệu JSON thực tế từ hệ thống mà bạn muốn kết nối (ví dụ: payload thông báo đơn hàng của nền tảng web). Dán đoạn mã này vào khung **Sample JSON**.

Nhấp nút **Format JSON** để hệ thống tự động căn chỉnh thụt lề chuẩn, sau đó nhấp **Load sample JSON**.

![Webhook URL và Sample JSON](https://mintcdn.com/chatbotx/dHddCrlyPo0xda94/images/inbound_webhooks_url_and_sample_json.png?fit=max\&auto=format\&n=dHddCrlyPo0xda94\&q=85\&s=7f616ed462fd47357dea3ecf4cea191a)

Quản lý Webhook URL và bộ soạn thảo dữ liệu mẫu Sample JSON

> [!NOTE]
>
> Việc nạp Sample JSON chỉ nhằm giúp hệ thống phân tích cấu trúc cây dữ liệu, hỗ trợ bạn chọn trường qua nút **Browse** trực quan mà không cần phải tự gõ cú pháp JSONPath.

**3. Cấu hình tìm hoặc tạo liên hệ (Find or create contact)**

Tại thẻ **Find or create contact**, chọn cách định tuyến cuộc trò chuyện vào hộp thư:

* **Specific inbox**: Chỉ định cố định một kênh và hộp thư duy nhất (ví dụ: `BotX AI · Messenger` hoặc kênh WhatsApp chính thức).
* **From payload**: Lấy mã định danh hộp thư động từ một trường trong request thông qua cú pháp JSONPath.

![Find or Create Contact](https://mintcdn.com/chatbotx/dHddCrlyPo0xda94/images/inbound_webhooks_find_or_create_contact.png?fit=max\&auto=format\&n=dHddCrlyPo0xda94\&q=85\&s=6a0cd112c82ffdfb4a676afbf1c15690)

Cấu hình hộp thư và 4 tiêu chí định danh liên hệ kèm xem trước giá trị thực tế

Điền ít nhất một tiêu chí định danh. Bạn có thể gõ trực tiếp đường dẫn hoặc nhấn nút **Browse** bên cạnh mỗi trường để mở modal chọn trực quan:

![Modal Browse trường định danh](https://mintcdn.com/chatbotx/dHddCrlyPo0xda94/images/inbound_webhooks_browse_contact_modal.png?fit=max\&auto=format\&n=dHddCrlyPo0xda94\&q=85\&s=6772771239f526a3dd8b4ce2cd906ebb)

Cửa sổ Browse hiển thị phân cấp JSON và dòng Result xem trước

Trong cửa sổ **Browse**:

* Sử dụng thanh tìm kiếm để lọc nhanh theo tên khóa (key), đường dẫn (path) hoặc giá trị (value).
* Nhấp vào thuộc tính mong muốn trong cây cấu trúc (ví dụ: `id` trong mục `customer`).
* Quan sát dòng **Result** để kiểm tra giá trị thực tế trích xuất được (ví dụ: `Result: CUST-98241` hoặc `Result: +84901234567`).
* Nhấn nút xanh **Use path** để áp dụng đường dẫn vào trường cấu hình.

**4. Ánh xạ dữ liệu nhận được vào các trường liên hệ (Save incoming data)**

Tại mục **Save incoming data**, thiết lập các giá trị bạn muốn trích xuất và lưu vào trường hồ sơ khách hàng:

![Save Incoming Data](https://mintcdn.com/chatbotx/dHddCrlyPo0xda94/images/inbound_webhooks_save_incoming_data.png?fit=max\&auto=format\&n=dHddCrlyPo0xda94\&q=85\&s=ed202f8a8dee14b861f44fa1a234ed25)

Bảng ánh xạ các trường dữ liệu từ payload sang Contact Fields

Đối với mỗi trường cần lưu:

1. Nhấn nút **+ Add field**.
2. Tại cột **Contact field**, chọn trường hồ sơ đích (ví dụ: `order_id`, `order_status`, `order_total`, `shipping_address`, `tracking_code`).
3. Tại cột **JSON path**, nhấn nút **Browse** để nhấp chọn trường tương ứng trong cấu trúc JSON mẫu.
4. Kiểm tra dòng giá trị xem trước hiển thị ngay dưới ô nhập liệu để đảm bảo khớp dữ liệu mong muốn.

![Modal Browse ánh xạ trường](https://mintcdn.com/chatbotx/dHddCrlyPo0xda94/images/inbound_webhooks_browse_mapping_modal.png?fit=max\&auto=format\&n=dHddCrlyPo0xda94\&q=85\&s=400897204c6d450cfd86fdd9ece42dbd)

Cửa sổ Browse chọn thuộc tính đơn hàng vào trường tùy chỉnh

> [!TIP]
>
> Hãy đảm bảo kiểu dữ liệu của trường tùy chỉnh trong ChatbotX khớp với định dạng giá trị nhận về (ví dụ: dùng trường Number cho tổng tiền đơn hàng, trường Text cho mã đơn/địa chỉ, và trường Date cho mốc thời gian).

**5. Thiết lập hành động tự động sau khi lưu (After saving data)**

Tại mục **After saving data**, thiết lập các hành động mà ChatbotX sẽ tự động thực thi ngay sau khi dữ liệu của liên hệ được lưu thành công:

![Cấu hình After Saving Data](https://mintcdn.com/chatbotx/dHddCrlyPo0xda94/images/inbound_webhooks_after_saving_data.png?fit=max\&auto=format\&n=dHddCrlyPo0xda94\&q=85\&s=a4e020f8f47370211c6d4ba99191265c)

Cấu hình các hành động tự động hóa sau khi lưu dữ liệu thành công

Nhấn **+ Add Action** để thêm một hoặc nhiều hành động tự động hóa:

* **Add Tag**: Gắn thẻ phân loại khách hàng (ví dụ: `hot-lead`, `new_order`, `paid_customer`).
* **Remove Tag**: Gỡ các thẻ cũ không còn phù hợp (ví dụ: gỡ thẻ `unpaid` hoặc `abandoned_cart`).
* **Set Custom Field**: Gán hoặc cập nhật giá trị cố định vào một trường tùy chỉnh khác.
* **Clear Custom Field**: Xóa trắng dữ liệu của một trường tùy chỉnh khi cần đặt lại trạng thái.
* **Start Another Flow**: Kích hoạt một kịch bản Flow tự động (chào đón, xác nhận thông tin đơn hàng, nhắc hẹn...). Flow này có thể sử dụng ngay các biến dữ liệu vừa được cập nhật từ webhook.
* **Transfer Conversation to Human**: Tự động chuyển cuộc trò chuyện sang chế độ chờ nhân viên hỗ trợ trong Hộp thư (Live Chat).

**6. Lưu, kích hoạt và tích hợp Webhook**

Kiểm tra lại toàn bộ thông tin và nhấn nút **Save** ở góc dưới cùng để lưu cấu hình.

Gạt công tắc **Active** ở góc trên bên phải để kích hoạt Webhook.

> [!WARNING]
>
> Trước khi bật Active, hệ thống yêu cầu bạn phải chọn hộp thư tiếp nhận (Inbox), điền ít nhất một trường định danh liên hệ và cấu hình ít nhất một dòng ánh xạ dữ liệu.

Nhấn nút **Copy** bên cạnh ô **Webhook URL** để sao chép địa chỉ endpoint:

```text theme={null}
https://app.chatbotx.io/api/hooks/{unique_token}
```

Dán đường dẫn này vào mục cấu hình Webhook của hệ thống bên ngoài (ví dụ: Webhook cài đặt trong Shopify, WooCommerce, hoặc phần mềm CRM của bạn).

## Bảo mật và cấp lại mã Webhook (Regenerate)

Đường dẫn Webhook URL chứa một token xác thực bảo mật duy nhất cho phép đẩy dữ liệu trực tiếp vào workspace của bạn:

* **Ẩn/Hiện mã**: Mặc định token được che dưới dạng dấu chấm tròn. Nhấp vào biểu tượng con mắt để xem toàn bộ đường link.
* **Tạo lại mã (Regenerate)**: Trong trường hợp đường dẫn Webhook của bạn bị lộ hoặc nghi ngờ có rủi ro bảo mật, hãy nhấp vào nút **Regenerate** để hệ thống hủy token cũ và cấp ngay một đường link Webhook URL hoàn toàn mới.

> [!WARNING]
>
> Khi bạn nhấn Regenerate, đường dẫn Webhook cũ sẽ bị vô hiệu hóa ngay lập tức. Mọi hệ thống bên ngoài đang gửi dữ liệu tới đường link cũ sẽ bị lỗi cho đến khi bạn cập nhật lại URL mới.

## Theo dõi thống kê và nhật ký (Analytics)

ChatbotX cung cấp giao diện báo cáo chuyên biệt cho từng Inbound Webhook:

1. Nhấp vào nút **View analytics** ở góc trên bên phải của màn hình cấu hình Webhook, hoặc chọn **View analytics** từ menu 3 chấm (`...`) tại danh sách Webhooks.
2. Trang **Analytics** hiển thị:
   * **Total requests received**: Tổng số lượng request hợp lệ đã tiếp nhận kể từ ngày khởi tạo (không tính trùng lặp).
   * **Nhật ký phân phối (Requests log)**: Danh sách chi tiết các lần phân phối dữ liệu gần nhất (lưu trữ lịch sử trong 30 ngày).
   * **Nút Refresh**: Nhấp để làm mới và cập nhật log request mới nhất.

![Giao diện Webhook Analytics](https://mintcdn.com/chatbotx/dHddCrlyPo0xda94/images/inbound_webhooks_analytics_view.png?fit=max\&auto=format\&n=dHddCrlyPo0xda94\&q=85\&s=2d392da86dde7335c93f4017c799cf39)

Giao diện trang Analytics theo dõi số lượng request và nhật ký tiếp nhận

## Bảng tra cứu cú pháp JSONPath

ChatbotX hỗ trợ đầy đủ cú pháp JSONPath tiêu chuẩn bao gồm dot notation và bracket notation:

| Dạng cú pháp | Ví dụ mẫu | Mục đích sử dụng |
| - | - | - |
| **Dấu chấm tiêu chuẩn (Dot Notation)** | `$.customer.phone` | Trỏ vào thuộc tính `phone` nằm trong đối tượng `customer`. |
| **Chỉ mục mảng (Array Index)** | `$.order.items[0].name` | Lấy tên `name` của sản phẩm đầu tiên trong mảng danh sách `items`. |
| **Ngoặc vuông (Bracket Notation)** | `$["customer-data"]["email"]` | Trỏ vào các thuộc tính có chứa ký tự đặc biệt, dấu gạch ngang hoặc khoảng trắng. |
| **Phân cấp nhiều tầng** | `$.order.shipping.address.city` | Truy xuất dữ liệu trong các đối tượng lồng ghép sâu. |

## Câu hỏi thường gặp

> [accordion] Tôi có bắt buộc phải cung cấp cả Email và Số điện thoại không?
>
> Không. Bạn chỉ cần thiết lập ít nhất một trường định danh trong số **Channel user ID**, **Phone**, **Email**, hoặc **Full name**. Request gửi đến phải chứa giá trị hợp lệ tại đường dẫn JSONPath tương ứng.

> [accordion] Khách hàng chưa có trong hệ thống thì ChatbotX xử lý như thế nào?
>
> ChatbotX sẽ tự động tạo một liên hệ mới thuộc Inbox đã chọn, ghi nhận đầy đủ các trường dữ liệu được ánh xạ, sau đó thực hiện các hành động trong mục **After saving data**.

> [accordion] Flow được kích hoạt qua 'Start Another Flow' có dùng được dữ liệu vừa gửi không?
>
> Có. Dữ liệu từ Webhook được ghi vào các trường tùy chỉnh (Custom Fields) của liên hệ **trước khi** Flow được khởi chạy. Do đó, các khối tin nhắn trong Flow có thể thoải mái gọi các biến như `{{order_id}}`, `{{order_total}}`, hay `{{shipping_address}}`.

> [accordion] Tôi có thể tạo nhiều Inbound Webhook cho các nguồn khác nhau không?
>
> Hoàn toàn được. Bạn có thể tạo nhiều Inbound Webhook riêng biệt cho từng nền tảng (ví dụ: một Webhook cho Shopify, một cho Landing Page và một cho CRM ngoài). Mỗi Webhook sẽ có URL riêng, cấu hình ánh xạ và hành động tự động độc lập.

> [accordion] Làm thế nào để kiểm tra nếu dữ liệu không được lưu vào liên hệ?
>
> Hãy mở trang **Analytics** của Webhook để xác nhận xem ChatbotX đã nhận được request hay chưa. Đồng thời đối chiếu cấu trúc JSON thực tế mà bên ngoài gửi có khớp với đường dẫn JSONPath đã cấu hình hay không, và kiểm tra kiểu dữ liệu của Custom Field có phù hợp không.


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