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

# n8n Integration

> Connect ChatbotX with n8n to automate contact data, events, and workflows.

The **n8n** integration lets you move data between ChatbotX and other applications without manual work. You can start a workflow when an event occurs, update a contact, or send another Flow from n8n.

For example, after a customer completes a consultation form in ChatbotX, n8n can receive the information, apply a Tag, update a Custom Field, and send a confirmation Flow.

## How the integration works

In n8n, a **workflow** is a process made of connected steps. The ChatbotX integration uses three main nodes:

| Node                                   | Function                                                                                                               |
| -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| **ChatbotX**                           | Performs Actions such as creating contacts, applying Tags, updating Custom Fields, sending Messages, or sending Flows. |
| **ChatbotX Trigger - Watch Events**    | Receives events from the ChatbotX Webhooks feature.                                                                    |
| **ChatbotX Trigger - Watch Flow Data** | Receives data sent by the **Trigger n8n** block in a ChatbotX Flow.                                                    |

To get started, install the Community Node, connect your ChatbotX workspace with a Credential, select a Trigger, add the required Actions, and test the workflow.

## Install the ChatbotX Community Node

<Note>
  Installing packages from npm is only available on self-hosted n8n instances. Unverified Community Nodes are not available on n8n Cloud.
</Note>

You can install `n8n-nodes-chatbotx` directly from the self-hosted n8n interface without using commands.

<Steps>
  <Step title="Open Community Nodes">
    In n8n, open **Settings > Community Nodes**. Your account must have permission to manage 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="Open Community Nodes settings in n8n" width="2981" height="1169" data-path="images/n8n_community_nodes_settings.png" />
    </Frame>
  </Step>

  <Step title="Enter the package name">
    Click **Install a community node**, then enter `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="Install the ChatbotX community node package in n8n" width="2488" height="1524" data-path="images/n8n_install_chatbotx_community_node.png" />
    </Frame>
  </Step>

  <Step title="Confirm the installation">
    Wait for the **Package installed** message. The **Community nodes** list displays `n8n-nodes-chatbotx`, the installed version, and the three ChatbotX nodes.

    <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="Confirm the ChatbotX community node package is installed in n8n" width="2983" height="1869" data-path="images/n8n_chatbotx_community_node_installed.png" />
    </Frame>
  </Step>

  <Step title="Check the ChatbotX nodes">
    Complete the installation and reload n8n if prompted. Open a workflow, click **+**, and search for `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="Find the three ChatbotX nodes in n8n" width="2978" height="1871" data-path="images/n8n_chatbotx_nodes_search_results.png" />
    </Frame>
  </Step>
</Steps>

## Connect your ChatbotX workspace

A Credential lets n8n access the correct ChatbotX workspace. You only need to create it once and can reuse it in other nodes.

<Steps>
  <Step title="Copy the API Access Token">
    In ChatbotX, open **Settings > Integrations > ChatbotX API Access Token** and copy the workspace token.

    <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="Copy the ChatbotX API access token from Integrations settings" width="3152" height="1225" data-path="images/chatbotx_api_access_token.png" />
    </Frame>
  </Step>

  <Step title="Create a ChatbotX API Credential">
    In a ChatbotX node in n8n, open the **Credential** field and create a new Credential.
  </Step>

  <Step title="Enter the connection details">
    Keep the **API URL** as `https://app.chatbotx.io/api` when using ChatbotX Cloud. Paste the token into **Access Token**, then save and test the connection.

    <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="Configure the ChatbotX API credential in n8n" width="2979" height="1870" data-path="images/n8n_chatbotx_api_credential.png" />
    </Frame>
  </Step>
</Steps>

<Warning>
  The Access Token allows other applications to access your workspace. Do not include it in screenshots, exported workflows, emails, or public documentation.
</Warning>

## Choose the right Trigger

ChatbotX provides two Triggers for different ways of sending data:

<CardGroup cols={2}>
  <Card title="Watch Events">
    Use it with [**Webhooks**](/docs/triggers/webhooks). Copy the Webhook URL from n8n and paste it into a Webhook in ChatbotX.
  </Card>

  <Card title="Watch Flow Data">
    Use it when the **Actions > Triggers > Trigger n8n** block in a Flow sends an Event Name to n8n.
  </Card>
</CardGroup>

## Receive events with Watch Events

**ChatbotX Trigger - Watch Events** is suitable when an Action in a Flow produces an event such as **Tag Applied**, **Tag Removed**, or **Custom Field Changed**. ChatbotX sends data to the n8n Webhook URL when the configured conditions match.

<Warning>
  The Webhook is sent only when the matching Action runs in the Flow's **Perform Action** node. The same type of change made elsewhere in the workspace does not trigger the Webhook. Learn more in [Webhooks](/docs/triggers/webhooks).
</Warning>

### Test with the Test URL

The following example uses **Tag Applied**. Select the same Event and Tag in n8n, ChatbotX Webhooks, and the Flow.

<Steps>
  <Step title="Add Watch Events">
    Create a workflow in n8n, add **ChatbotX Trigger - Watch Events**, select a Credential, and choose the **Tag Applied** Event.
  </Step>

  <Step title="Copy the Test URL">
    Open **Webhook URLs**, select **Test URL**, and copy the displayed address.

    <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="Copy the Watch Events test webhook URL in n8n" width="2983" height="1872" data-path="images/n8n_watch_events_test_url.png" />
    </Frame>
  </Step>

  <Step title="Create a Webhook in ChatbotX">
    In ChatbotX, open **Webhooks**, create a Webhook, and select **Tag Applied**. Select the Tag you want to watch and paste the Test URL into the **URL** field.

    <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="Configure a matching ChatbotX webhook with the n8n test URL" width="3187" height="1252" data-path="images/chatbotx_webhook_n8n_test_url.png" />
    </Frame>
  </Step>

  <Step title="Start listening for data">
    Save and enable the Webhook in ChatbotX. Return to n8n and click **Execute step** so n8n can wait for a test event.
  </Step>

  <Step title="Add the matching Action to a Flow">
    In the ChatbotX Flow, add a **Perform Action** node and select the Action that applies the Tag configured in the Webhook. Connect the node to the branch where it should run.

    <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="Add a matching Tag Applied action in ChatbotX Flow Builder" width="3191" height="1823" data-path="images/chatbotx_flow_matching_webhook_action.png" />
    </Frame>
  </Step>

  <Step title="Run the Flow and check the data">
    Run the Flow with a test contact. When n8n receives the event, the contact data appears in **OUTPUT**.
  </Step>
</Steps>

<Note>
  The Test URL works only while n8n is waiting for data after you click **Execute step**.
</Note>

### Activate the workflow with the Production URL

After the Test URL receives data successfully, switch to the Production URL so the workflow can run continuously.

<Steps>
  <Step title="Copy the Production URL">
    In **Webhook URLs**, select **Production URL** and copy the displayed address.

    <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="Copy the Watch Events production webhook URL in n8n" width="2874" height="1770" data-path="images/n8n_watch_events_production_url.png" />
    </Frame>
  </Step>

  <Step title="Update the Webhook in ChatbotX">
    Open the Webhook you created, replace the Test URL with the Production URL, and verify the Event and Tag.
  </Step>

  <Step title="Enable the Webhook">
    Click **Save** and make sure the Webhook is enabled in the Webhooks list.
  </Step>

  <Step title="Publish the n8n workflow">
    Return to n8n and click **Publish**. Run the Flow again, then open **Executions** to check the latest run.
  </Step>
</Steps>

<Warning>
  Do not use the Test URL for an active workflow. The Production URL receives data only after the n8n workflow is Published.
</Warning>

## Send data from a Flow with Watch Flow Data

**ChatbotX Trigger - Watch Flow Data** is suitable when you want to choose the exact point where a Flow sends data. For example, send data to n8n only after a customer completes a consultation form.

### Set up the Trigger in n8n

<Steps>
  <Step title="Add Watch Flow Data">
    Create a workflow and add **ChatbotX Trigger - Watch Flow Data**.
  </Step>

  <Step title="Enter the Event Name">
    Select a Credential and enter an Event Name, such as `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="Configure an event name in the ChatbotX Watch Flow Data trigger" width="2876" height="1775" data-path="images/n8n_watch_flow_data_event_name.png" />
    </Frame>
  </Step>

  <Step title="Start listening for data">
    Click **Execute step** so n8n can wait for test data from the ChatbotX Flow.
  </Step>
</Steps>

### Send an Event from a ChatbotX Flow

<Steps>
  <Step title="Open the Flow to connect">
    In ChatbotX, open the Flow that will send data and select the relevant message node.
  </Step>

  <Step title="Add the Trigger n8n block">
    Click **Create**, then select **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="Add the Trigger n8n action block in ChatbotX Flow Builder" width="3188" height="1825" data-path="images/chatbotx_flow_add_trigger_n8n.png" />
    </Frame>
  </Step>

  <Step title="Match the Event Name with n8n">
    Click **Edit** on the **Trigger n8n** block, add `n8n_event` to **Events**, then click **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="Match the Trigger n8n event name with the n8n workflow" width="3187" height="1822" data-path="images/chatbotx_trigger_n8n_event_name.png" />
    </Frame>
  </Step>

  <Step title="Run the Flow">
    Run the Flow with a test contact. n8n displays the received data in **OUTPUT**.
  </Step>

  <Step title="Publish both Flows">
    When the test data is correct, Publish the ChatbotX Flow and the n8n workflow.
  </Step>
</Steps>

<Note>
  The **Trigger n8n** block does not have a Webhook URL field. The Event Name connects the ChatbotX Flow to **Watch Flow Data**, so it must match exactly on both sides.
</Note>

## Perform Actions in ChatbotX

The **ChatbotX** node runs after a Trigger and performs work in your workspace using data received from the previous step.

### Manage contacts

| Action                   | Function                                                      |
| ------------------------ | ------------------------------------------------------------- |
| **Create**               | Creates a contact.                                            |
| **Create or Update**     | Updates an existing contact or creates a new one.             |
| **Get**                  | Retrieves a contact by Identifier.                            |
| **List**                 | Lists contacts and filters them by keyword.                   |
| **Find by Custom Field** | Finds a contact whose Custom Field matches the entered value. |
| **Delete**               | Deletes a contact from the workspace.                         |

### Update Tags and Custom Fields

| Action                  | Function                                     |
| ----------------------- | -------------------------------------------- |
| **Add Tags**            | Adds one or more Tags to a contact.          |
| **Remove Tags**         | Removes Tags from a contact.                 |
| **Set Custom Fields**   | Updates one or more Custom Fields.           |
| **Delete Custom Field** | Deletes a Custom Field value from a contact. |

### Send content

| Action           | Function                             |
| ---------------- | ------------------------------------ |
| **Send Message** | Sends a text message to a contact.   |
| **Send Flow**    | Sends a Published Flow to a contact. |

<Warning>
  **Delete** permanently removes a contact. Run this Action only with a test contact while testing your workflow.
</Warning>

### Use an Identifier

The **Identifier** tells the node which contact to update. You can enter it directly or drag a field from **INPUT** into this field.

| Input value            | Value used by the node   |
| ---------------------- | ------------------------ |
| `11590944070189061`    | `id:11590944070189061`   |
| `user@example.com`     | `email:user@example.com` |
| `+84 908-123-456`      | `phone:+84908123456`     |
| `id:11590944070189061` | Kept unchanged           |

<Steps>
  <Step title="Open the INPUT data">
    Open the Action you want to configure and find `contact.id`, `contact.email`, or `contact.phoneNumber` in **INPUT**.
  </Step>

  <Step title="Drag the field into Identifier">
    Drag the field you want to use into **Identifier**. n8n automatically creates an expression for that field.
  </Step>

  <Step title="Check the Result value">
    Open **Expression** mode and verify that **Result** displays the contact you want to process.
  </Step>
</Steps>

### Make an advanced ChatbotX API call

Select **Custom > API Call** when the Action you need is not available in the list. You can select a method, enter an API path, and send JSON data using the current Credential.

Read the [**API Overview**](/docs/api-reference/api-overview) before using this feature.

## Build an example workflow

The following example receives a contact from a Flow, applies a Tag, updates a Custom Field, and sends a confirmation Flow:

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

<Steps>
  <Step title="Receive data from the Flow">
    Configure **Watch Flow Data** with the Event Name `n8n_event`, then send the Event from the **Trigger n8n** block.
  </Step>

  <Step title="Add a Tag to the contact">
    Add a **ChatbotX** node, select **Contact > Add Tags**, drag `contact.id` into **Identifier**, and select a test Tag.
  </Step>

  <Step title="Update a Custom Field">
    Add another node, select **Contact > Set Custom Fields**, map the same Identifier, and select a test Custom Field.
  </Step>

  <Step title="Send the confirmation Flow">
    Add a **Contact > Send Flow** node, then select a Published Flow and the appropriate Inbox.
  </Step>

  <Step title="Test the workflow">
    Run each node and verify that every step returns a successful result.
  </Step>

  <Step title="Publish the workflow">
    Click **Publish**, run the ChatbotX Flow again, and open **Executions** to review the complete result.
  </Step>
</Steps>

<Note>
  The contact must have a previous conversation to receive a Message or Flow. The Flow you send must be Published.
</Note>

## Troubleshoot common issues

| Issue                                    | What to check                                                                                                                                    |
| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| Package not found                        | Verify that you are using self-hosted n8n and entered `n8n-nodes-chatbotx` correctly. Unverified Community Nodes are not available on n8n Cloud. |
| Credential connection fails              | Copy the API URL and Access Token again from the correct ChatbotX workspace.                                                                     |
| Watch Events does not receive test data  | Click **Execute step**, use the Test URL, enable the Webhook, and run the matching Action in the Flow.                                           |
| Watch Events does not run after Publish  | Use the Production URL, enable the Webhook, and verify that the n8n workflow is Published.                                                       |
| Watch Flow Data does not receive data    | Verify that the Event Name in n8n exactly matches the Event Name in the **Trigger n8n** block.                                                   |
| Action runs on the wrong contact         | Open **Expression > Result** and check the Identifier for each item.                                                                             |
| Send Message or Send Flow fails          | Verify that the contact has a conversation, the Flow is Published, and the correct Inbox is selected.                                            |
| Self-hosted Production URL does not work | Make sure n8n has a public HTTPS URL that ChatbotX can reach.                                                                                    |

<Note>
  When a workflow does not run, check these items in order: Credential, Trigger, INPUT data, Identifier, Webhook status, and Published status.
</Note>