Description

Chatwoot for n8n

Native Chatwoot nodes for n8n. Run your customer support operation — contacts, conversations, messages, attributes, labels, agents, teams, and inboxes — directly from n8n workflows, without hand-building HTTP requests or pasting API tokens into every workflow.

This package ships three building blocks:

• Chatwoot Trigger — receive ten real-time events and manage the webhook registration automatically.
• Chatwoot — a toolbox of 75 actions across eight resources.
• Chatwoot API — a reusable credential that works with Chatwoot Cloud and self-hosted installations.

What you can do with it

• Respond in real time. Trigger workflows the moment a conversation is created, a message arrives, or a status changes.
• Move data without code. Create and update contacts, conversations, messages, and custom attributes using plain n8n controls — no endpoint paths, no HTTP verbs, no JSON plumbing.
• Keep conversations organized. Assign conversations, set status and priority, apply and remove labels, mute and read-state changes.
• Automate lead enrichment. Read and write custom attributes with automatic type conversion (text, number, currency, percent, checkbox, date, link, and list).
• Filter conversations by activity. Select conversations by lastactivityat with a relative (“last N days”) or absolute date range — no Code nodes required.
• Connect once, reuse everywhere. Store your Chatwoot credentials a single time and share them across every workflow.

What makes it different

• Simplified output by default. Common API envelopes such as payload and data.payload are stripped, and lists produce one n8n item per entity.
• Transparent under the hood. Every action shows the resolved operation, and an optional Include API Details output exposes the resolved calls without your base URL or token.
• Safe attribute and label updates. Set Custom Attribute and Add/Remove Labels preserve the rest of the record instead of overwriting it, because the Chatwoot API replaces full lists. The only full-object operations — Replace Custom Attributes and Replace Labels — are named explicitly and marked as advanced.
• Actionable errors. Failures include the HTTP code, endpoint, Chatwoot message, and a suggestion when available — never your token.

Getting started

1. Install

In n8n, open Settings → Community Nodes, choose Install, and enter:

n8n-nodes-chatwoot-for-n8n

If you were using an earlier trigger-only version, update the package to 0.2.0 or newer and restart n8n if your installation does not reload automatically.

After installing, search for Chatwoot when adding a node. Both Chatwoot and Chatwoot Trigger should appear.

2. Create the credential once

In Chatwoot:

1. Open your avatar and go to Profile Settings.
2. Copy your personal Access Token.
3. Look at your dashboard URL. In /app/accounts/1/, the Account ID is 1.

In n8n:

1. Open Credentials → Create Credential → Chatwoot API.
2. In Base URL, enter https://app.chatwoot.com or the root of your self-hosted instance, without /api at the end.
3. Paste the token and fill in the Account ID.
4. Leave Verify Webhook Signatures enabled and Ignore SSL Issues disabled.
5. Save.

3. Build your first workflow

1. Add a Chatwoot Trigger (or any trigger) and activate the workflow.
2. Add a Chatwoot node, select your credential, and pick a Resource and Operation.
3. Map fields from previous nodes using expressions such as {{$json.conversation.id}}.
4. Execute the node.

The trigger needs a public HTTPS URL reachable by Chatwoot; it cannot deliver events to localhost.

Available actions

| Resource | Actions | Highlights |
| —————– | ——- | ——————————————————————————- |
| Contact (Lead) | 20 | create, exact search, upsert, update, block, attributes, labels, inbox, merge |
| Conversation | 22 | create, list, status, priority, assignment, attributes, labels, mute, delete |
| Message | 7 | list, send, private note, incoming, WhatsApp template, status, delete |
| Custom Attribute | 5 | list, get, create, update, and delete definitions |
| Label | 5 | list, get, create, update, delete |
| Agent | 4 | list, invite, update, remove |
| Team | 9 | CRUD and member administration |
| Inbox | 3 | list, get, and update common settings |

The complete catalog with method, route, and behavior is in Actions.

Compatibility

• Node.js 22 or newer
• n8n 2.x (built against n8n-workflow 2.16.0 and @n8n/node-cli 0.44.3)
• TypeScript 5.9.3
• Chatwoot 4.17.0 as the API and source reference
• Chatwoot Cloud and self-hosted via a configurable base URL

Triggers have been confirmed on a real installation. Actions carry automated tests with realistic responses and full route-coverage checks. Before automating production data, test the operations you need against your real account, since permissions, channels, and self-hosted versions can vary.

For developers

npm install
npm run format:check
npm run typecheck
npm run lint
npm run test
npm run build
npm pack

npm run dev starts the official n8n community-node development environment.

Additional documentation:

• Actions and semantics
• Research and decisions
• Testing
• Verification results

License: MIT. Icons are original generic drawings; see icons/ASSET-NOTICE.md.