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

# n8n

> Trigger n8n workflows from BubblaV chatbot events and automate conversations with community nodes

## Overview

The n8n integration lets you connect BubblaV to [n8n](https://n8n.io) workflows. Start automations when conversations happen and run chatbot actions — send messages, tag conversations, update customers, create tickets — from any workflow.

<Info>
  The n8n integration requires a **Pro plan or higher**.
</Info>

### What You Can Do

<CardGroup cols={2}>
  <Card title="15 Triggers" icon="play">
    Start workflows when conversations begin, messages arrive, leads are captured, meetings are booked, and more.
  </Card>

  <Card title="6 Actions" icon="paper-plane">
    Send messages and greetings, create tickets, update customers, and tag conversations.
  </Card>

  <Card title="3 Searches" icon="search">
    Look up conversations, customers, and analytics data inside workflows.
  </Card>

  <Card title="400+ Integrations" icon="grid">
    Connect BubblaV to everything n8n supports — Slack, Notion, Airtable, HubSpot, and more.
  </Card>
</CardGroup>

***

## Prerequisites

1. **BubblaV account**: Pro plan or higher
2. **n8n instance**: self-hosted or n8n Cloud with community nodes enabled
3. **Website**: at least one website configured in BubblaV

***

## Setup

<Steps>
  <Step title="Create an API key">
    In BubblaV, open your website → **Settings** → **API keys** → **Create key**. Copy the key (it starts with `bubblav_mcp_`).
  </Step>

  <Step title="Install the community node">
    In n8n, go to **Settings** → **Community Nodes** → **Install**, enter `@bubblav/n8n-nodes-bubblav`, and confirm.
  </Step>

  <Step title="Create credentials">
    Add a **BubblaV API** credential in n8n and paste your API key. Leave **Base URL** as `https://www.bubblav.com`.
  </Step>

  <Step title="Build your workflow">
    Add a **BubblaV Trigger** to start on events, or the **BubblaV** node to run actions.
  </Step>
</Steps>

<Info>
  Each API key is bound to a single website. To automate another website, create another key and another credential. Deactivating a key revokes access immediately.
</Info>

***

## Triggers

The **BubblaV Trigger** node fires instantly via webhooks — no polling. Select one or more events:

### Conversation Events

| Event                  | Description                                  |
| ---------------------- | -------------------------------------------- |
| `conversation.created` | A visitor starts a new chat                  |
| `message.created`      | Any message is sent in a conversation        |
| `handoff.requested`    | AI escalates or the visitor requests a human |
| `conversation.closed`  | A conversation is closed or resolved         |
| `conversation.rated`   | A visitor rates a conversation               |

### Lead & Visitor Events

| Event                  | Description                              |
| ---------------------- | ---------------------------------------- |
| `lead.captured`        | A visitor submits contact information    |
| `visitor.first_visit`  | A new visitor arrives for the first time |
| `visitor.return_visit` | A known visitor returns to your site     |
| `link.clicked`         | A visitor clicks a link in the chat      |

### Booking Events

| Event                                         | Description                          |
| --------------------------------------------- | ------------------------------------ |
| `calendly.booked` / `calcom.booked`           | A meeting is booked through the chat |
| `calendly.cancelled` / `calcom.cancelled`     | A meeting is cancelled               |
| `calendly.rescheduled` / `calcom.rescheduled` | A meeting is moved to a new time     |

<Info>
  Deliveries arrive as bare JSON event payloads. All selected events share one webhook URL — use a Switch node on payload fields (for example `id`, `visitor_id`) to branch per event.
</Info>

***

## Actions

| Action                     | Description                                                                                                                         |
| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| **Send Message**           | Send a message to an existing conversation, or start a new conversation by targeting a visitor. Sender type: bot, agent, or system. |
| **Send Greeting**          | Send a transient greeting to a visitor — only shown while the visitor is online.                                                    |
| **Tag Conversation**       | Add tags to a conversation, or replace all existing tags.                                                                           |
| **Update Customer**        | Update visitor name, email, phone, company, or custom fields.                                                                       |
| **Create Ticket**          | Create a support ticket from a conversation (Zendesk if connected, internal otherwise).                                             |
| **Ask Chatbot a Question** | Ask your AI chatbot a question and get an answer from your knowledge base.                                                          |

## Searches

| Search                | Description                                                                   |
| --------------------- | ----------------------------------------------------------------------------- |
| **Find Conversation** | Look up conversations by ID, visitor ID, or visitor email (up to 50 results). |
| **Find Customer**     | Look up customers by visitor ID or email.                                     |
| **Get Analytics**     | Conversation and message analytics for the last 24 hours, 7, 30, or 90 days.  |

***

## Troubleshooting

| Issue                     | Solution                                                                                                                                            |
| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| **401 Unauthorized**      | API key is invalid or deactivated. Create a new key in Dashboard → Settings → API keys.                                                             |
| **Trigger not firing**    | Confirm the workflow is **Active**, and check that your n8n instance is reachable from the internet (webhook deliveries come from BubblaV servers). |
| **Send Greeting fails**   | Greetings are real-time only — the visitor must be online.                                                                                          |
| **Credential test fails** | Check the API key was copied in full and the Base URL has no trailing path.                                                                         |

***

## Resources

* [npm package](https://www.npmjs.com/package/@bubblav/n8n-nodes-bubblav)
* [Source code](https://github.com/bubblav-org/n8n-nodes-bubblav)
* [n8n community nodes docs](https://docs.n8n.io/integrations/community-nodes/)