Chatwoot

Communication CRM

v0.9.0

Last updated Sep 26, 2026

n8n community node for Chatwoot - customer engagement platform for managing conversations, messages, and contacts

13 Weekly Downloads

120 Monthly Downloads

View on NPM GitHub Repository

Included Nodes

Chatwoot

Chatwoot Trigger

Description

n8n-nodes-chatwoot

![npm version](https://www.npmjs.com/package/@renatoascencio/n8n-nodes-chatwoot)
![npm downloads](https://www.npmjs.com/package/@renatoascencio/n8n-nodes-chatwoot)
![License: MIT](https://opensource.org/licenses/MIT)
![n8n community node](https://docs.n8n.io/integrations/community-nodes/)

Chatwoot Logo

A comprehensive n8n community node for Chatwoot – the open-source customer engagement platform. Automate your customer support workflows with full access to conversations, messages, contacts, agents, teams, and more.

n8n is a fair-code licensed workflow automation platform.

—

Highlights

39 Resources – Comprehensive coverage of Application, Platform, and Public APIs
260+ Operations – Complete CRUD operations for all resources, verified against Chatwoot 4.13–4.18
3 API Types – Application API (v1 + v2), Platform API, and Public API support
AI Agent Tool – The Chatwoot node can be attached as a tool to n8n’s AI Agent node
Trigger Node – Account webhooks or a manually-configured Agent Bot/API Channel URL, with HMAC signature verification, 12 event types, and delivery filters
Automatic Retries – Exponential backoff on 429/502/503/504, honoring Retry-After
Reports v2 – Full coverage of /api/v2/reports, /livereports, /summaryreports
WhatsApp Templates & Attachments – template_params for template messages, binary attachments and voice notes for regular messages
Dynamic Dropdowns – Auto-populated lists for agents, teams, inboxes, and labels
Smart Pagination – Automatic handling with “Return All” option
Reports & Analytics – Access conversation and agent statistics
Help Center – Manage portals, categories, and articles
Detailed Error Messages – Chatwoot’s own error message and description, not a generic one

Screenshots

Taken in n8n 2.40.7 with the example workflows in examples/workflows (sample data is fictional and pinned, so you can open them without a Chatwoot server).

WhatsApp auto-triage — the trigger filters incoming messages, then the node labels the conversation and replies:

!WhatsApp auto-triage workflow

—

Screenshots
Installation
Configuration
Nodes

– Chatwoot Node
– Chatwoot Trigger

Resources & Operations
Trigger Reference
Using the Chatwoot Node as an AI Agent Tool
Using with Evolution API (WhatsApp)
Compatibility
Usage Examples
Troubleshooting
Development
Release Process
Contributing
License

—

Installation

> n8n 3.0 (October 2026): unverified community packages are disabled by default
> (N8NUNVERIFIEDPACKAGES_ENABLED defaults to false, down from true on 2.x). Until this
> package is verified by n8n, set N8NUNVERIFIEDPACKAGES_ENABLED=true on your n8n instance to
> keep installing or updating it — otherwise the install fails and n8n 3.0 also refuses to load an
> already-installed unverified package. This has no effect on n8n 2.x.

Community Nodes (Recommended)

1. Go to Settings > Community Nodes in your n8n instance
2. Select Install
3. Enter @renatoascencio/n8n-nodes-chatwoot
4. Accept the risks and select Install

Manual Installation

For self-hosted n8n
cd ~/.n8n/nodes
npm install @renatoascencio/n8n-nodes-chatwoot
Restart n8n

Docker

Add to your docker-compose.yml:

environment:
  - N8NCUSTOMEXTENSIONS=@renatoascencio/n8n-nodes-chatwoot

Or install in a running container:

docker exec -it n8n npm install -g @renatoascencio/n8n-nodes-chatwoot
docker restart n8n

—

Configuration

This node supports three types of credentials for different API access levels:

1. Chatwoot API (Application API)

Used for most operations – managing conversations, contacts, messages, teams, etc.

1. In n8n, go to Credentials > Add Credential
2. Search for Chatwoot API
3. Fill in the required fields:

Getting Your API Access Token:
1. Log in to Chatwoot
2. Click your profile icon (bottom left)
3. Go to Profile Settings
4. Scroll to Access Token
5. Copy or regenerate your token

2. Chatwoot Platform API

Used for platform-level operations – managing accounts, platform users, and account agent bots. Requires super admin access.

3. Chatwoot Public API

Used for client-side operations without an agent login: creating contacts, starting conversations,
and sending messages from an external system. The Public API only works with API channel inboxes
(Channel::Api) — this is the inbox type Evolution API and other WhatsApp bridges create, and the
one you get from Chatwoot’s Inboxes > Add Inbox > API. Website (web widget), Email, Telegram and
other inbox types answer 404 for every Public API call.

When HMAC Token is set, Public Contact operations compute identifier_hash automatically for
any contact created or updated with an Identifier, which an inbox enforcing identity validation
requires — otherwise Chatwoot rejects the request.

> Note: Keep your API tokens secure. They provide access to your Chatwoot account.

—

Nodes

Chatwoot Node

The main node for interacting with Chatwoot APIs. Supports 38 resources across three API types:

Application API (31 resources) – Core operations for conversations, contacts, messages, macros, notifications, campaigns, companies, SLA policies, applied SLAs, global search, reports v2, live reports, summary reports, etc.
Platform API (4 resources) – Admin operations for accounts, users, and agent bots
Public API (3 resources) – Client-side operations for widgets and external integrations

Chatwoot Trigger

Webhook-based trigger that starts workflows when events occur in Chatwoot. See
Trigger Reference below for the full reference: sources, signature
verification, events and filters.

—

Resources & Operations

Account

Manage your Chatwoot account settings.

Agent

Manage team members and their settings.

Canned Response

Manage pre-saved response templates.

Contact

Full contact management with search and merge capabilities.

Conversation

Manage customer conversations with assignment and labeling.

Custom Attribute

Manage custom fields for contacts and conversations.

Inbox

Manage communication channels.

Label

Organize conversations and contacts with labels.

Message

Send and retrieve messages in conversations.

> WhatsApp template messages (since v0.8.1): use the templateparams JSON option with format {"name": "templatename", "category": "MARKETING|UTILITY|AUTHENTICATION", "language": "enUS", "processedparams": {"1": "value1", "2": "value2"}}.
>
> Attachments (since v0.9.0): add one or more binary properties from a previous node (e.g. an HTTP Request or Read Binary File output) to Attachments (Binary Properties) as a comma-separated list. Turn on Send Audio as Voice Message to send an audio attachment as a Chatwoot voice note.

Team

Manage agent teams for conversation routing.

Webhook

Manage webhook subscriptions programmatically.

Agent Bot

Manage AI agent bots.

Automation Rule

Manage automation rules for conversations.

Custom Filter

Manage saved filters for conversations and contacts.

Report

Access analytics and reporting data via Chatwoot’s /api/v2/reports endpoints. Now correctly routed through v2 (was broken in v0.3.0–v0.7.x — see v0.8.0 release notes).

Live Report

Real-time conversation metrics (no date range needed).

Summary Report

Per-entity summary metrics with date range (JSON, max 6-month range for channel).

Applied SLA (Enterprise)

Track SLA compliance per conversation.

Profile

Manage user profile.

Help Center

Manage knowledge base content.

Integration

Manage integrations (Dialogflow, Slack, etc.).

Audit Log

Access account activity logs.

CSAT Survey

Access customer satisfaction surveys.

Macro

Manage reusable action sequences.

Notification

Manage agent notifications.

Campaign

Manage outbound campaigns.

Contact Note

Manage notes on contacts.

Conversation Participant

Manage conversation watchers/participants.

Company (Enterprise)

Manage B2B companies. Requires Chatwoot Enterprise.

SLA Policy (Enterprise)

Manage SLA policies. Requires Chatwoot Enterprise.

Search (Global)

Search across all entities.

—

Platform API Resources

These resources require the Chatwoot Platform API credential.

Platform Account

Manage accounts at the platform level.

Platform User

Manage users at the platform level.

Account User

Manage users within a specific account.

Account Agent Bot

Manage agent bots at the account level.

—

Public API Resources

These resources require the Chatwoot Public API credential.

Public Contact

Manage contacts via the public API. When the credential’s HMAC Token is set, Create and Update
compute identifier_hash automatically for a contact sent with an Identifier.

Public Conversation

Manage conversations via the public API.

Public Message

Manage messages via the public API.

[Public] Inbox

Read the public settings of the credential’s API inbox — no side effects.

| Operation | Description |
|———–|————-|
| Get | Get the inbox’s name, timezone, working hours, and whether CSAT surveys, greetings and identity validation are enabled |

—

Trigger Reference

The Chatwoot Trigger has two delivery Sources. Both verify Chatwoot’s HMAC signature by default.

Account Webhook (Automatic) — the default

n8n creates a Chatwoot account webhook for this trigger’s URL when the workflow is activated,
stores its signing secret, and deletes the webhook when the workflow is deactivated. This needs an
administrator API access token (on Chatwoot Cloud, a plan with API and webhooks). Reactivating the
workflow, or renaming it, reuses or re-adopts the existing webhook instead of creating a duplicate.

Events: Contact Created/Updated, Conversation Created/Updated/Status Changed, Conversation
Typing On/Off, Inbox Created/Updated (only sent when the Chatwoot server sets
ENABLEINBOXEVENTS), Message Created/Updated, Webwidget Triggered.

Agent Bot / API Channel (Manual URL)

Paste this trigger’s Production URL (or the Test URL while testing) directly into an **Agent
Bot‘s Webhook URL (Settings > Bots), an API Channel inbox**’s Webhook URL (Settings > Inboxes >
the inbox > Settings — this is the inbox type Evolution API creates), or a webhook you manage by
hand in Settings > Integrations > Webhooks. n8n registers nothing in Chatwoot for this source; you
provide the Signing Secret yourself (Chatwoot shows it as secret on the agent bot or inbox,
or when you create a webhook). Do not use this source’s URL as an account webhook target, and don’t
use the Account Webhook source’s URL as an agent bot/API channel target — each signs with its own
secret and Chatwoot rejects the other with HTTP 401.

This source has its own, larger event list, since agent bots, API channels and account webhooks
each fire a different subset: it adds Conversation Opened and Conversation Resolved
(agent-bot handoff events, not available on the Account Webhook source), and leaves out events an
agent bot or API channel never sends (Contact Created/Updated, Inbox Created/Updated). An error
response from this workflow (inactive workflow, invalid signature) makes Chatwoot mark the delivery
as failed — for an agent bot, pending conversations move back to Open unless the account keeps them
pending on bot failure.

Signature verification and options

Filters

Filters apply after the event-type check and narrow which matching events actually start the
workflow (everything else is answered 200 OK and ignored, so Chatwoot doesn’t retry it):

Inbox IDs — only these inboxes.
Sender Types — Contact / Agent / Agent Bot.
Message Types — Incoming / Outgoing / Template / Activity.
Private Notes — include, exclude, or only private notes.
Ignore Messages From User IDs — drop messages sent by specific agent/bot user IDs (for

example, to stop a workflow from reacting to its own replies).

Ignore Outgoing WhatsApp Echoes (Evolution API) — Evolution API relays every outbound message

back to Chatwoot as its own message_created event; turn this on to drop those echoes so the
trigger only fires for messages that didn’t originate from this same workflow.

SafeFetch (Chatwoot 4.14+)

Chatwoot 4.14 and later only deliver webhooks to publicly-routable addresses (its anti-SSRF
“SafeFetch” filter). If Chatwoot can only reach this n8n instance through a private address (a
Docker service name, localhost, 10.x, 172.16–31.x, 192.168.x), every delivery is dropped
silently — Chatwoot logs “Invalid webhook URL” on its side and n8n never receives anything.
Set SAFEFETCHALLOWPRIVATENETWORK=true on the Chatwoot server (available since 4.14.1) to
allow it. The trigger node shows a notice about this when its computed webhook URL looks private.

—

Using the Chatwoot Node as an AI Agent Tool

The Chatwoot node declares usableAsTool: true, so it can be connected to the Tool input of an
AI Agent node (or any other node that accepts sub-node tools) instead of only running as a
regular workflow step. Connect it like any other tool sub-node, then either:

Pin Resource and Operation and let the agent fill in the remaining parameters (for

example, always Message > Create on a fixed conversation, letting the model write the
Content), or

Set the node’s parameters to expressions the model fills in through the tool’s schema, for a more

general-purpose tool (e.g. “search contacts”, “create a conversation”, “add a label”).

Every operation the node otherwise supports is available this way — there’s no separate “AI tool”
mode. The usual guidance for tool-enabled community nodes applies: keep the exposed surface to the
handful of operations the agent actually needs (one Chatwoot node per operation is easier for a
model to use reliably than one node with 39 resources and 230+ operations all exposed at once).

—

Using with Evolution API (WhatsApp)

Evolution API is a common way to connect WhatsApp
to Chatwoot: it creates an API channel inbox (Channel::Api) in Chatwoot and relays messages
both ways. A few things behave differently for these inboxes compared to a native Chatwoot channel:

Contact identifier is the JID. For a WhatsApp contact created through Evolution, the

contact’s identifier is the WhatsApp JID (e.g. 5215512345678@s.whatsapp.net), not an
arbitrary ID from your own CRM. Search and merge operations that match on identifier need the
JID, not a customer/CRM ID.

Typing indicators aren’t relayed to WhatsApp. Chatwoot’s Conversation > Toggle Typing calls

the standard API-channel typing endpoint, but Evolution doesn’t forward
conversationtypingon/off to the WhatsApp client, so the contact never sees a “typing…”
indicator, even though the call itself succeeds.

Outbound-message echoes. Evolution can relay a message n8n just sent back into Chatwoot as

its own incoming message_created webhook event, which would otherwise make an
“auto-reply” trigger workflow fire on its own replies. Turn on the Chatwoot Trigger’s
Ignore Outgoing WhatsApp Echoes (Evolution API) filter to drop these.

Attachments. Use Message > Create’s Attachments (Binary Properties) field to send images,

documents or audio; turn on Send Audio as Voice Message for a WhatsApp voice note instead of
a regular audio attachment.

Use the Public API for contact-facing automations (for example, a bot that creates

conversations or messages as the contact rather than as an agent): it only works with API channel
inboxes, which is exactly what Evolution creates — see Chatwoot Public API above.

Chatwoot 4.14+’s SafeFetch also applies to the webhook Evolution itself receives from

Chatwoot and to the Chatwoot Trigger’s own URL — see SafeFetch above
if messages stop arriving after a Chatwoot upgrade.

This package does not include an Evolution API node; use n8n’s HTTP Request node (or a
dedicated Evolution community node) for Evolution’s own endpoints (sending messages directly,
managing instances, etc.) alongside this node for the Chatwoot side of the integration.

—

Compatibility

| | Supported | Notes |
|—|—|—|
| Chatwoot | 4.13 – 4.18 | Verified against each version’s documented API behavior. Some operations require an Enterprise license or a specific account feature flag (noted in their description) — Chatwoot answers 401/403 for those on Community Edition or when the feature is off. |
| n8n | 2.x | Works on current n8n 2.x releases. |
| n8n 3.0 | Not verified yet | Unverified community packages are disabled by default in n8n 3.0 (planned October 2026) — set N8NUNVERIFIEDPACKAGES_ENABLED=true until this package is verified. See Installation. |
| Node.js | >= 18 | Matches the engines.node requirement in package.json. |

Version-specific behavior worth knowing about:

Chatwoot 4.14+: SafeFetch blocks webhook deliveries to private-network addresses (see

SafeFetch); Custom Attribute Create/Update/Delete require an
administrator token (an agent token used to work).

Chatwoot 4.17+: Update Custom Attributes on a conversation supports merging instead of

replacing (Merge With Existing option).

Chatwoot 4.18: Toggle Priority / Update’s priority field rejects an explicit “none” value

with 422 (older versions 500’d); the node sends no priority at all to clear it.

Company, SLA Policy and Applied SLA resources need Chatwoot Enterprise, and specifically the

account’s companies/sla feature flags — a Community Edition or unlicensed account gets 403.

—

Usage Examples

Ready-to-import workflows

Download a file from examples/workflows and import it in n8n (Workflows → Import from File), then select your own credentials in each node.

| File | What it does |
|—|—|
| whatsapp-auto-triage.json | Chatwoot Trigger (incoming messages only, signature verified) → IF the customer asks for prices → append the ventas label → reply with the price list |
| ai-agent-chatwoot-tool.json | AI Agent that uses the Chatwoot node as three tools (find conversations, add labels, reply) with $fromAI() parameters |
| daily-account-summary.json | Every morning, fetch yesterday’s Account Summary report and format a one-line summary |
| basic-conversation-workflow.json | List open conversations |
| contact-sync-workflow.json | Search a contact by email, then update it or create it |
| send-message-workflow.json | Send a message and set the conversation to pending |

Auto-Reply to New Conversations

Chatwoot Trigger (conversation_created)
  → Chatwoot (Create Message)

Automatically send a welcome message when a new conversation is created.

Sync Contacts from Your CRM

CRM Trigger (new lead)
  → Chatwoot (Create Contact)

Keep your Chatwoot contacts in sync with your CRM.

Close Stale Conversations

Schedule Trigger (daily)
  → Chatwoot (Get Many Conversations: status=pending)
  → Filter (older than 7 days)
  → Chatwoot (Update Status: resolved)

Automatically resolve conversations that have been inactive.

Route Conversations by Label

Chatwoot Trigger (conversation_updated)
  → IF (label = "urgent")
    → Chatwoot (Assign to specific team)
  → ELSE
    → Chatwoot (Assign to general team)

Auto-assign conversations based on labels.

Daily Agent Performance Report

Schedule Trigger (daily)
  → Chatwoot (Get Many Conversations: resolved today)
  → Aggregate by agent
  → Email (send report)

Generate daily performance metrics.

Contact Merge Deduplication

Webhook (CRM update)
  → Chatwoot (Search Contact by email)
  → IF (multiple found)
    → Chatwoot (Merge Contacts)

Automatically merge duplicate contacts.

—

Troubleshooting

Common Errors

Base URL Configuration

> Important: Do not include /api/v1 or trailing slashes.

Permission Levels

Webhook Issues

If the Chatwoot Trigger isn’t receiving events:

1. Check that your n8n instance is publicly accessible
2. Verify the webhook was created in Chatwoot (Settings > Integrations > Webhooks)
3. Ensure the selected events match what Chatwoot is sending
4. Check n8n’s execution log for incoming requests

—

API Reference

This node uses three Chatwoot APIs:

Application API – Core API for managing conversations, contacts, messages, etc.
Platform API – Admin API for managing accounts, users, and agent bots (requires super admin access)
Public API – Client-side API for widgets and external integrations

API Documentation

Chatwoot Application API Reference
Chatwoot Platform API Reference
Chatwoot Public API Reference
Webhooks Documentation
API Authentication

—

Development

Clone and setup
git clone https://github.com/serversmx/n8n-nodes-chatwoot.git
cd n8n-nodes-chatwoot
npm install
npx tsc --noEmit    # Type-check
npm run lint        # ESLint 8, TypeScript style + n8n-nodes-base rules
npm run lint:n8n    # n8n community-node verification lint (@n8n/eslint-plugin-community-nodes)
npm test            # Jest unit tests
npm run build       # Compile to dist/ and copy icons + codex files
Link for local testing
npm link
cd ~/.n8n/nodes && npm link @renatoascencio/n8n-nodes-chatwoot

Tests

The test suite (1007 tests, 12 suites) is entirely offline — it never calls a real Chatwoot
instance. test/helpers/mockExecuteFunctions.ts builds a mock IExecuteFunctions/
ILoadOptionsFunctions/IHookFunctions/IWebhookFunctions context whose httpRequest helper
returns pre-programmed responses (or throws a shaped HTTP error), so each test exercises the real
execute() code path — parameter reading, request construction, response handling, pagination and
error mapping — for one resource/operation at a time. test/exec.*.test.ts cover the Application/
Platform/Public API resources by area, test/exec.trigger.test.ts covers the Chatwoot Trigger’s
webhook lifecycle and signature verification, test/Resources.test.ts validates every resource’s
operation/field definitions (naming, displayOptions, alphabetical ordering), and
test/review.*.test.ts lock in the specific behaviors called out in the Changelog’s “Changed”
section (compatibility defaults, label semantics, etc.) so a future change can’t silently regress
them.

n8n verification lint

npm run lint:n8n runs @n8n/eslint-plugin-community-nodes‘s recommended rule set (ESLint 9,
flat config only — that’s why it’s a separate eslint.n8n.config.mjs and script from the ESLint 8
.eslintrc.js/npm run lint pair) against nodes/, credentials/ and package.json. It’s the
same static analysis n8n’s own community-node verification checks for. See the CI workflow
(.github/workflows/ci.yml) and the handful of documented, narrowly-scoped eslint-disable
comments in the source for the small number of findings that don’t apply to this codebase (for
example, a rule that assumes every thrown error might be unwrapped, when this package’s single
request layer already guarantees every error reaching a resource is a NodeApiError).

—

Release Process

Releases are tag-triggered and publish with npm provenance, per n8n’s community-node verification
requirement (mandatory since May 1, 2026: publish via a GitHub Action and include a
provenance statement).

1. Update version in package.json and add an entry to CHANGELOG.md.
2. Open a PR; .github/workflows/ci.yml runs type-checking, both lints, the test suite and the
build on every push and PR.
3. Once merged to main, tag the release and push the tag:

   git tag v0.9.0
   git push origin v0.9.0

4. .github/workflows/publish.yml runs on the v* tag: npm ci, npm test, npm run build,
then npm publish --provenance --access public.

Authentication: this repository publishes using npm’s Trusted Publishing (OIDC) — the
workflow requests an id-token: write permission and npm exchanges it for a short-lived publish
token, so no NPM_TOKEN secret is stored in the repository. This needs a one-time setup on
npmjs.com: on the package’s page, **Settings → Trusted Publishers → Add a trusted publisher →
GitHub Actions**, with this repository and publish.yml as the workflow filename. If you fork this
repository and want to publish your own version, either configure Trusted Publishing for your fork
the same way, or replace the last step of publish.yml with the classic
NPMTOKEN/.npmrc approach and add NPMTOKEN as a repository secret.

—

Contributing

Contributions are welcome. See CLAUDE.md for the architecture and conventions this
package follows (resource/operation layout, the shared request layer, compatibility options, and
how the test harness works), and the Development section above to get set up.
Please add or update tests for any behavior change, and run the full check list
(npx tsc --noEmit && npm run lint && npm run lint:n8n && npm test) before opening a PR.

—

Changelog

See CHANGELOG.md for release history.

—

License

MIT – See LICENSE file for details.

—

Support

Issues: GitHub Issues
Chatwoot Docs: chatwoot.com/developers
n8n Community: community.n8n.io

—

Made with care for the n8n and Chatwoot communities

Included Nodes

Description

n8n-nodes-chatwoot

Highlights

Screenshots

Table of Contents

Installation

Community Nodes (Recommended)

Manual Installation

For self-hosted n8n

Restart n8n

Docker

Configuration

1. Chatwoot API (Application API)

2. Chatwoot Platform API

3. Chatwoot Public API

Nodes

Chatwoot Node

Chatwoot Trigger

Resources & Operations

Account

Agent

Canned Response

Contact

Conversation

Custom Attribute

Inbox

Label

Message

Team

Webhook

Agent Bot

Automation Rule

Custom Filter

Report

Live Report

Summary Report

Applied SLA (Enterprise)

Profile

Help Center

Integration

Audit Log

CSAT Survey

Macro

Notification

Campaign

Contact Note

Conversation Participant

Company (Enterprise)

SLA Policy (Enterprise)

Search (Global)

Platform API Resources

Platform Account

Platform User

Account User

Account Agent Bot

Public API Resources

Public Contact

Public Conversation

Public Message

[Public] Inbox

Trigger Reference

Account Webhook (Automatic) — the default

Agent Bot / API Channel (Manual URL)

Signature verification and options

Filters

SafeFetch (Chatwoot 4.14+)

Using the Chatwoot Node as an AI Agent Tool

Using with Evolution API (WhatsApp)

Compatibility

Usage Examples

Ready-to-import workflows

Auto-Reply to New Conversations

Sync Contacts from Your CRM

Close Stale Conversations

Route Conversations by Label

Daily Agent Performance Report

Contact Merge Deduplication

Troubleshooting

Common Errors