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

# Tích hợp n8n

> Kết nối ChatbotX với n8n để nhận sự kiện, gửi dữ liệu từ Flow và tự động thực hiện Actions trên contact.

Tích hợp **n8n** giúp bạn chuyển dữ liệu giữa ChatbotX và các ứng dụng khác mà không cần xử lý thủ công. Bạn có thể bắt đầu workflow khi một sự kiện xảy ra, cập nhật contact hoặc gửi một Flow khác từ n8n.

Ví dụ: sau khi khách hoàn tất form tư vấn trong ChatbotX, n8n nhận thông tin, gắn Tag, cập nhật Custom Field và gửi Flow xác nhận cho khách.

## Cách tích hợp hoạt động

Trong n8n, một **workflow** là quy trình gồm nhiều bước được nối với nhau. Tích hợp ChatbotX sử dụng ba node chính:

| Node                                   | Chức năng                                                                                     |
| -------------------------------------- | --------------------------------------------------------------------------------------------- |
| **ChatbotX**                           | Thực hiện Actions như tạo contact, gắn Tag, cập nhật Custom Field, gửi Message hoặc gửi Flow. |
| **ChatbotX Trigger - Watch Events**    | Nhận sự kiện từ tính năng Webhooks của ChatbotX.                                              |
| **ChatbotX Trigger - Watch Flow Data** | Nhận dữ liệu do block **Trigger n8n** gửi từ một Flow ChatbotX.                               |

Để bắt đầu, hãy cài Community Node, kết nối workspace ChatbotX bằng Credential, chọn Trigger, thêm các Actions cần thiết rồi chạy thử workflow.

## Cài ChatbotX Community Node

<Note>
  Cài đặt package từ npm chỉ khả dụng trên n8n self-hosted. Community Node chưa được xác minh không khả dụng trên n8n Cloud.
</Note>

Bạn có thể cài `n8n-nodes-chatbotx` trực tiếp trên giao diện n8n self-hosted mà không cần dùng câu lệnh.

<Steps>
  <Step title="Mở Community Nodes">
    Trong n8n, mở **Settings > Community Nodes**. Tài khoản của bạn cần có quyền quản lý Community Nodes.

    <Frame>
      <img src="https://mintcdn.com/chatbotx/tiTxWbwBXwc-Nw2E/images/n8n_community_nodes_settings.png?fit=max&auto=format&n=tiTxWbwBXwc-Nw2E&q=85&s=fd7df587b1ee376f7da3f75b7827cf6c" alt="N8n Community Nodes Settings" width="2981" height="1169" data-path="images/n8n_community_nodes_settings.png" />
    </Frame>
  </Step>

  <Step title="Nhập tên package">
    Nhấn **Install a community node**, sau đó nhập `n8n-nodes-chatbotx`.

    <Frame>
      <img src="https://mintcdn.com/chatbotx/tiTxWbwBXwc-Nw2E/images/n8n_install_chatbotx_community_node.png?fit=max&auto=format&n=tiTxWbwBXwc-Nw2E&q=85&s=ed321a64eb4bd92c2f3a1a6310173bb2" alt="N8n Install Chatbotx Community Node" width="2488" height="1524" data-path="images/n8n_install_chatbotx_community_node.png" />
    </Frame>
  </Step>

  <Step title="Xác nhận cài đặt thành công">
    Chờ thông báo **Package installed**. Danh sách **Community nodes** hiển thị `n8n-nodes-chatbotx`, phiên bản đã cài và ba node ChatbotX.

    <Frame>
      <img src="https://mintcdn.com/chatbotx/RBR2fuCDVeW0WM-Y/images/n8n_chatbotx_community_node_installed.png?fit=max&auto=format&n=RBR2fuCDVeW0WM-Y&q=85&s=0af30fdfaa97ba8c4bc95a223623e11c" alt="N8n Chatbotx Community Node Installed" width="2983" height="1869" data-path="images/n8n_chatbotx_community_node_installed.png" />
    </Frame>
  </Step>

  <Step title="Kiểm tra các node ChatbotX">
    Hoàn tất cài đặt và tải lại n8n nếu giao diện yêu cầu. Mở một workflow, nhấn dấu **+** và tìm `ChatbotX`.

    <Frame>
      <img src="https://mintcdn.com/chatbotx/tiTxWbwBXwc-Nw2E/images/n8n_chatbotx_nodes_search_results.png?fit=max&auto=format&n=tiTxWbwBXwc-Nw2E&q=85&s=8c98fd133b9d330af220e41af845c618" alt="N8n Chatbotx Nodes Search Results" width="2978" height="1871" data-path="images/n8n_chatbotx_nodes_search_results.png" />
    </Frame>
  </Step>
</Steps>

## Kết nối workspace ChatbotX

Credential giúp n8n truy cập đúng workspace ChatbotX. Bạn chỉ cần tạo một lần và có thể dùng lại trong các node khác.

<Steps>
  <Step title="Sao chép API Access Token">
    Trong ChatbotX, mở **Settings > Integrations > ChatbotX API Access Token** và sao chép token của workspace.

    <Frame>
      <img src="https://mintcdn.com/chatbotx/tiTxWbwBXwc-Nw2E/images/chatbotx_api_access_token.png?fit=max&auto=format&n=tiTxWbwBXwc-Nw2E&q=85&s=f95c0103c5da1b3401368f3e7a483839" alt="Chatbotx Api Access Token" width="3152" height="1225" data-path="images/chatbotx_api_access_token.png" />
    </Frame>
  </Step>

  <Step title="Tạo ChatbotX API Credential">
    Trong một node ChatbotX trên n8n, mở trường **Credential** và chọn tạo Credential mới.
  </Step>

  <Step title="Nhập thông tin kết nối">
    Giữ **API URL** là `https://app.chatbotx.io/api` khi bạn dùng ChatbotX Cloud. Dán token vào **Access Token**, sau đó lưu và kiểm tra kết nối.

    <Frame>
      <img src="https://mintcdn.com/chatbotx/tiTxWbwBXwc-Nw2E/images/n8n_chatbotx_api_credential.png?fit=max&auto=format&n=tiTxWbwBXwc-Nw2E&q=85&s=a02c6150844bdafe2def192bf49cea2b" alt="N8n Chatbotx Api Credential" width="2979" height="1870" data-path="images/n8n_chatbotx_api_credential.png" />
    </Frame>
  </Step>
</Steps>

<Warning>
  Access Token cho phép ứng dụng khác truy cập workspace. Không đưa token vào ảnh chụp, workflow export, email hoặc tài liệu công khai.
</Warning>

## Chọn Trigger phù hợp

ChatbotX cung cấp hai Trigger cho hai cách gửi dữ liệu khác nhau:

<CardGroup cols={2}>
  <Card title="Watch Events">
    Dùng với [**Webhooks**](/docs/vi/triggers/webhooks). Bạn sao chép Webhook URL từ n8n và dán vào Webhook trong ChatbotX.
  </Card>

  <Card title="Watch Flow Data">
    Dùng khi block **Actions > Triggers > Trigger n8n** trong Flow chủ động gửi một Event Name sang n8n.
  </Card>
</CardGroup>

## Nhận sự kiện bằng Watch Events

**ChatbotX Trigger - Watch Events** phù hợp khi một Action trong Flow tạo ra sự kiện như **Tag Applied**, **Tag Removed** hoặc **Custom Field Changed**. ChatbotX gửi dữ liệu đến Webhook URL của n8n khi điều kiện đã cấu hình khớp.

<Warning>
  Webhook chỉ được gửi khi Action tương ứng chạy trong node **Perform Action** của Flow. Thay đổi cùng loại ở nơi khác trong workspace không kích hoạt Webhook. Xem thêm tại [Webhooks](/docs/vi/triggers/webhooks).
</Warning>

### Chạy thử bằng Test URL

Ví dụ dưới đây sử dụng **Tag Applied**. Hãy chọn cùng Event và cùng Tag trong n8n, ChatbotX Webhooks và Flow.

<Steps>
  <Step title="Thêm Watch Events">
    Tạo workflow mới trong n8n, thêm **ChatbotX Trigger - Watch Events**, chọn Credential và chọn Event **Tag Applied**.
  </Step>

  <Step title="Sao chép Test URL">
    Mở **Webhook URLs**, chọn **Test URL** và sao chép địa chỉ hiển thị.

    <Frame>
      <img src="https://mintcdn.com/chatbotx/tiTxWbwBXwc-Nw2E/images/n8n_watch_events_test_url.png?fit=max&auto=format&n=tiTxWbwBXwc-Nw2E&q=85&s=e09817b134474d5c668f719db968a968" alt="N8n Watch Events Test Url" width="2983" height="1872" data-path="images/n8n_watch_events_test_url.png" />
    </Frame>
  </Step>

  <Step title="Tạo Webhook trong ChatbotX">
    Trong ChatbotX, mở **Webhooks**, tạo Webhook mới và chọn **Tag Applied**. Chọn Tag cần theo dõi và dán Test URL vào trường **URL**.

    <Frame>
      <img src="https://mintcdn.com/chatbotx/tiTxWbwBXwc-Nw2E/images/chatbotx_webhook_n8n_test_url.png?fit=max&auto=format&n=tiTxWbwBXwc-Nw2E&q=85&s=ac355709227b0c9e4dc7938737d52828" alt="Chatbotx Webhook N8n Test Url" width="3187" height="1252" data-path="images/chatbotx_webhook_n8n_test_url.png" />
    </Frame>
  </Step>

  <Step title="Bật chế độ chờ dữ liệu">
    Lưu và bật Webhook trong ChatbotX. Quay lại n8n rồi nhấn **Execute step** để n8n chờ sự kiện thử.
  </Step>

  <Step title="Thêm Action khớp trong Flow">
    Trong Flow ChatbotX, thêm node **Perform Action** và chọn Action gắn đúng Tag đã cấu hình trong Webhook. Kết nối node vào nhánh cần chạy.

    <Frame>
      <img src="https://mintcdn.com/chatbotx/tiTxWbwBXwc-Nw2E/images/chatbotx_flow_matching_webhook_action.png?fit=max&auto=format&n=tiTxWbwBXwc-Nw2E&q=85&s=8c67466cfd2bcad51f956f1fee0484ed" alt="Chatbotx Flow Matching Webhook Action" width="3191" height="1823" data-path="images/chatbotx_flow_matching_webhook_action.png" />
    </Frame>
  </Step>

  <Step title="Chạy Flow và kiểm tra dữ liệu">
    Chạy Flow với một contact test. Khi n8n nhận sự kiện, dữ liệu contact xuất hiện trong phần **OUTPUT**.
  </Step>
</Steps>

<Note>
  Test URL chỉ hoạt động khi n8n đang chờ dữ liệu sau khi bạn nhấn **Execute step**.
</Note>

### Bật workflow bằng Production URL

Sau khi Test URL nhận dữ liệu thành công, chuyển sang Production URL để workflow hoạt động liên tục.

<Steps>
  <Step title="Sao chép Production URL">
    Trong **Webhook URLs**, chọn **Production URL** và sao chép địa chỉ hiển thị.

    <Frame>
      <img src="https://mintcdn.com/chatbotx/tiTxWbwBXwc-Nw2E/images/n8n_watch_events_production_url.png?fit=max&auto=format&n=tiTxWbwBXwc-Nw2E&q=85&s=ee1bc54f8afc47c481c3591c4e75405f" alt="N8n Watch Events Production Url" width="2874" height="1770" data-path="images/n8n_watch_events_production_url.png" />
    </Frame>
  </Step>

  <Step title="Cập nhật Webhook trong ChatbotX">
    Mở Webhook đã tạo, thay Test URL bằng Production URL rồi kiểm tra lại Event và Tag.
  </Step>

  <Step title="Bật Webhook">
    Nhấn **Save** và bảo đảm Webhook đang được bật trong danh sách Webhooks.
  </Step>

  <Step title="Publish workflow n8n">
    Quay lại n8n và nhấn **Publish**. Chạy lại Flow rồi mở **Executions** để kiểm tra lần chạy mới nhất.
  </Step>
</Steps>

<Warning>
  Không dùng Test URL cho workflow đang hoạt động. Production URL chỉ nhận dữ liệu khi workflow n8n đã được Publish.
</Warning>

## Gửi dữ liệu từ Flow bằng Watch Flow Data

**ChatbotX Trigger - Watch Flow Data** phù hợp khi bạn muốn chọn chính xác vị trí gửi dữ liệu trong Flow. Ví dụ: chỉ gửi sang n8n sau khi khách hoàn tất form tư vấn.

### Thiết lập Trigger trong n8n

<Steps>
  <Step title="Thêm Watch Flow Data">
    Tạo workflow mới và thêm **ChatbotX Trigger - Watch Flow Data**.
  </Step>

  <Step title="Nhập Event Name">
    Chọn Credential và nhập Event Name, ví dụ `n8n_event`.

    <Frame>
      <img src="https://mintcdn.com/chatbotx/tiTxWbwBXwc-Nw2E/images/n8n_watch_flow_data_event_name.png?fit=max&auto=format&n=tiTxWbwBXwc-Nw2E&q=85&s=a3b4859f92eb9318a83aecd32d7a0417" alt="N8n Watch Flow Data Event Name" width="2876" height="1775" data-path="images/n8n_watch_flow_data_event_name.png" />
    </Frame>
  </Step>

  <Step title="Bật chế độ chờ dữ liệu">
    Nhấn **Execute step** để n8n chờ dữ liệu thử từ Flow ChatbotX.
  </Step>
</Steps>

### Gửi Event từ Flow ChatbotX

<Steps>
  <Step title="Mở Flow cần kết nối">
    Trong ChatbotX, mở Flow cần gửi dữ liệu và chọn message node phù hợp.
  </Step>

  <Step title="Thêm block Trigger n8n">
    Nhấn **Create**, sau đó chọn **Actions > Triggers > Trigger n8n**.

    <Frame>
      <img src="https://mintcdn.com/chatbotx/tiTxWbwBXwc-Nw2E/images/chatbotx_flow_add_trigger_n8n.png?fit=max&auto=format&n=tiTxWbwBXwc-Nw2E&q=85&s=8d26d2f8435eef9dfd1ba1d056e94692" alt="Chatbotx Flow Add Trigger N8n" width="3188" height="1825" data-path="images/chatbotx_flow_add_trigger_n8n.png" />
    </Frame>
  </Step>

  <Step title="Nhập Event Name giống n8n">
    Nhấn **Edit** trên block **Trigger n8n**, thêm `n8n_event` vào **Events** rồi nhấn **Save**.

    <Frame>
      <img src="https://mintcdn.com/chatbotx/tiTxWbwBXwc-Nw2E/images/chatbotx_trigger_n8n_event_name.png?fit=max&auto=format&n=tiTxWbwBXwc-Nw2E&q=85&s=42a854daa804a9a86216d322bb4b6595" alt="Chatbotx Trigger N8n Event Name" width="3187" height="1822" data-path="images/chatbotx_trigger_n8n_event_name.png" />
    </Frame>
  </Step>

  <Step title="Chạy Flow">
    Chạy Flow với một contact test. n8n hiển thị dữ liệu nhận được trong **OUTPUT**.
  </Step>

  <Step title="Publish hai Flow">
    Khi dữ liệu thử chính xác, Publish Flow ChatbotX và workflow n8n.
  </Step>
</Steps>

<Note>
  Block **Trigger n8n** không có trường Webhook URL. Event Name kết nối Flow ChatbotX với **Watch Flow Data**, vì vậy hai bên phải giống nhau hoàn toàn.
</Note>

## Thực hiện Actions trong ChatbotX

Node **ChatbotX** chạy sau Trigger và thực hiện công việc trong workspace bằng dữ liệu nhận được từ bước trước.

### Quản lý contact

| Action                   | Chức năng                                             |
| ------------------------ | ----------------------------------------------------- |
| **Create**               | Tạo contact mới.                                      |
| **Create or Update**     | Cập nhật contact hiện có hoặc tạo contact mới.        |
| **Get**                  | Lấy thông tin một contact theo Identifier.            |
| **List**                 | Liệt kê contact và lọc theo từ khóa.                  |
| **Find by Custom Field** | Tìm contact có Custom Field khớp với giá trị đã nhập. |
| **Delete**               | Xóa contact khỏi workspace.                           |

### Cập nhật Tags và Custom Fields

| Action                  | Chức năng                              |
| ----------------------- | -------------------------------------- |
| **Add Tags**            | Thêm một hoặc nhiều Tags cho contact.  |
| **Remove Tags**         | Gỡ Tags khỏi contact.                  |
| **Set Custom Fields**   | Cập nhật một hoặc nhiều Custom Fields. |
| **Delete Custom Field** | Xóa giá trị Custom Field khỏi contact. |

### Gửi nội dung

| Action           | Chức năng                            |
| ---------------- | ------------------------------------ |
| **Send Message** | Gửi tin nhắn văn bản cho contact.    |
| **Send Flow**    | Gửi một Flow đã Publish cho contact. |

<Warning>
  **Delete** xóa contact vĩnh viễn. Chỉ chạy Action này với contact test khi bạn đang kiểm tra workflow.
</Warning>

### Sử dụng Identifier

**Identifier** cho node biết contact nào cần được cập nhật. Bạn có thể nhập trực tiếp hoặc kéo field từ phần **INPUT** vào trường này.

| Giá trị đầu vào        | Giá trị node sử dụng     |
| ---------------------- | ------------------------ |
| `11590944070189061`    | `id:11590944070189061`   |
| `user@example.com`     | `email:user@example.com` |
| `+84 908-123-456`      | `phone:+84908123456`     |
| `id:11590944070189061` | Giữ nguyên               |

<Steps>
  <Step title="Mở dữ liệu INPUT">
    Mở Action cần cấu hình và tìm `contact.id`, `contact.email` hoặc `contact.phoneNumber` trong phần **INPUT**.
  </Step>

  <Step title="Kéo field vào Identifier">
    Kéo field cần dùng vào trường **Identifier**. n8n tự tạo expression cho field đó.
  </Step>

  <Step title="Kiểm tra giá trị Result">
    Mở chế độ **Expression** và kiểm tra **Result** đang hiển thị đúng contact cần xử lý.
  </Step>
</Steps>

### Gọi ChatbotX API nâng cao

Chọn **Custom > API Call** khi Action bạn cần chưa có trong danh sách. Bạn có thể chọn phương thức, nhập đường dẫn API và gửi dữ liệu JSON bằng Credential hiện tại.

Xem [**API Overview**](/docs/api-reference/api-overview) trước khi sử dụng tính năng này.

## Tạo workflow mẫu

Ví dụ sau nhận contact từ Flow, gắn Tag, cập nhật Custom Field rồi gửi một Flow xác nhận:

`Watch Flow Data > Add Tags > Set Custom Fields > Send Flow`

<Steps>
  <Step title="Nhận dữ liệu từ Flow">
    Cấu hình **Watch Flow Data** với Event Name `n8n_event`, sau đó gửi Event từ block **Trigger n8n**.
  </Step>

  <Step title="Thêm Tag cho contact">
    Thêm node **ChatbotX**, chọn **Contact > Add Tags**, kéo `contact.id` vào **Identifier** và chọn Tag test.
  </Step>

  <Step title="Cập nhật Custom Field">
    Thêm node mới, chọn **Contact > Set Custom Fields**, ánh xạ cùng Identifier và chọn Custom Field test.
  </Step>

  <Step title="Gửi Flow xác nhận">
    Thêm node **Contact > Send Flow**, chọn Flow đã Publish và Inbox phù hợp.
  </Step>

  <Step title="Kiểm tra workflow">
    Chạy từng node và xác nhận mỗi bước trả về kết quả thành công.
  </Step>

  <Step title="Publish workflow">
    Nhấn **Publish**, chạy lại Flow ChatbotX và mở **Executions** để kiểm tra toàn bộ kết quả.
  </Step>
</Steps>

<Note>
  Contact cần có hội thoại trước đó để nhận Message hoặc Flow. Flow được gửi phải ở trạng thái Published.
</Note>

## Xử lý lỗi thường gặp

| Vấn đề                                     | Cách kiểm tra                                                                                                                                 |
| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------- |
| Không tìm thấy package                     | Xác nhận bạn đang dùng n8n self-hosted và đã nhập đúng `n8n-nodes-chatbotx`. Community Node chưa được xác minh không khả dụng trên n8n Cloud. |
| Credential kết nối thất bại                | Sao chép lại API URL và Access Token từ đúng workspace ChatbotX.                                                                              |
| Watch Events không nhận dữ liệu thử        | Nhấn **Execute step**, dùng Test URL, bật Webhook và chạy Action khớp trong Flow.                                                             |
| Watch Events không chạy sau khi Publish    | Dùng Production URL, bật Webhook và kiểm tra workflow n8n đã Published.                                                                       |
| Watch Flow Data không nhận dữ liệu         | Kiểm tra Event Name ở n8n và block **Trigger n8n** giống nhau hoàn toàn.                                                                      |
| Action chạy sai contact                    | Mở **Expression > Result** và kiểm tra Identifier của từng item.                                                                              |
| Send Message hoặc Send Flow thất bại       | Kiểm tra contact đã có hội thoại, Flow đã Published và Inbox phù hợp.                                                                         |
| Production URL self-hosted không hoạt động | Bảo đảm n8n có URL HTTPS công khai để ChatbotX gửi dữ liệu đến.                                                                               |

<Note>
  Khi workflow không chạy, hãy kiểm tra theo thứ tự: Credential, Trigger, dữ liệu INPUT, Identifier, trạng thái Webhook và trạng thái Published.
</Note>