Chuyển đến nội dung chính
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

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:

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

​
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

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

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

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

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

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

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

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

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

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

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:

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

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