n8n-nodes-chatwoot

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

• 38 Resources - Comprehensive coverage of Application, Platform, and Public APIs
• 220+ Operations - Complete CRUD operations for all resources
• 3 API Types - Application API (v1 + v2), Platform API, and Public API support
• Trigger Node - Real-time webhook events (10 event types) from Chatwoot
• Reports v2 - Full coverage of /api/v2/reports, /live_reports, /summary_reports
• WhatsApp Templates - Native template_params support for template 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 - Clear feedback for troubleshooting

---

Table of Contents

• Installation
• Configuration
• Nodes
  • Chatwoot Node
  • Chatwoot Trigger
• Resources & Operations
• Usage Examples
• Troubleshooting
• Contributing
• License

---

Installation

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:
  - N8N_CUSTOM_EXTENSIONS=@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:

Field	Description	Example
Base URL	Your Chatwoot instance URL	https://app.chatwoot.com or https://chatwoot.yourdomain.com
Account ID	Your Chatwoot account ID	Found in URL: /app/accounts/1/...
API Access Token	Your personal API token	Found in Profile Settings

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.

Field	Description	Example
Base URL	Your Chatwoot instance URL	https://app.chatwoot.com
Platform API Token	Super admin platform token	Found in Super Admin settings

3. Chatwoot Public API

Used for client-side/widget operations - creating contacts and conversations from external sources.

Field	Description	Example
Base URL	Your Chatwoot instance URL	https://app.chatwoot.com
Inbox Identifier	The unique identifier for your inbox	Found in inbox settings (e.g., abc123xyz)

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. Automatically registers and manages webhooks in your Chatwoot account.

Supported Events (10 total):

• contact_created - New contact added
• contact_updated - Contact information changed
• conversation_created - New conversation started
• conversation_status_changed - Status changed (open/resolved/pending/snoozed)
• conversation_typing_off - Typing indicator stopped
• conversation_typing_on - Typing indicator started
• conversation_updated - Conversation modified
• message_created - New message sent or received
• message_updated - Message edited
• webwidget_triggered - Web widget interaction

---

Resources & Operations

Account

Manage your Chatwoot account settings.

Operation	Description
Get	Get account information
Update	Update account settings (name, locale, support email, auto-resolve duration)

Agent

Manage team members and their settings.

Operation	Description
Get Many	List all agents in the account
Create	Add a new agent (requires email, name, role)
Update	Modify agent settings (role, availability, auto-offline)
Delete	Remove an agent from the account

Canned Response

Manage pre-saved response templates.

Operation	Description
Get Many	List all canned responses
Create	Create a new canned response (short code + content)
Update	Modify an existing canned response
Delete	Remove a canned response

Contact

Full contact management with search and merge capabilities.

Operation	Description
Create	Create a new contact (requires inbox_id)
Get	Retrieve a contact by ID
Get Many	List all contacts with pagination
Update	Modify contact details
Delete	Remove a contact
Search	Find contacts by name, email, phone, or identifier
Get Conversations	List all conversations for a contact
Merge	Merge two contacts into one
Filter	Filter contacts with advanced criteria
Add Labels	Add labels to a contact
List Labels	Get all labels for a contact
Import	Import contacts from CSV file (binary upload)
Export	Export contacts as CSV
Contactable Inboxes	Get inboxes that can reach a contact

Conversation

Manage customer conversations with assignment and labeling.

Operation	Description
Get	Get a single conversation with full details
Get Many	List conversations with filters (status, inbox, team, labels, search)
Create	Create a new conversation
Update Status	Change status to open, resolved, pending, or snoozed
Update	Update conversation (custom attributes, team, etc.)
Assign	Assign to an agent or team (with dynamic dropdowns)
Add Labels	Set labels on a conversation
List Labels	Get all labels for a conversation
Toggle Priority	Set conversation priority (urgent, high, medium, low, none)
Filter	Filter conversations with advanced criteria
Update Custom Attributes	Set custom attributes on conversation
Get Meta	Get conversation metadata
Mute	Mute a conversation
Unmute	Unmute a conversation
Delete	Delete a conversation
Search	Search conversations by query
Transcript	Send conversation transcript via email
Toggle Typing	Show/hide typing indicator

Custom Attribute

Manage custom fields for contacts and conversations.

Operation	Description
Get Many	List all custom attributes
Get	Get a specific attribute by key
Create	Create a new custom attribute
Update	Modify an existing attribute
Delete	Remove a custom attribute

Inbox

Manage communication channels.

Operation	Description
Get Many	List all inboxes
Get	Get inbox details
Create	Create a new inbox
Update	Modify inbox settings (name, greeting, auto-assignment, etc.)
Add Agent	Add an agent to an inbox
Delete Agent	Remove an agent from an inbox
Get Members	List inbox members
Get Agent Bot	Get associated agent bot
Set Agent Bot	Associate an agent bot with inbox

Label

Organize conversations and contacts with labels.

Operation	Description
Get Many	List all labels
Create	Create a new label (title, color, description)
Update	Modify label properties
Delete	Remove a label

Message

Send and retrieve messages in conversations.

Operation	Description
Create	Send a message (supports private notes, WhatsApp template params, content_attributes)
Get Many	Retrieve message history with cursor-based pagination
Update	Update an existing message
Delete	Delete a message

WhatsApp template messages (since v0.8.1): use the template_params JSON option with format {"name": "template_name", "category": "MARKETING|UTILITY|AUTHENTICATION", "language": "en_US", "processed_params": {"1": "value1", "2": "value2"}}.

Team

Manage agent teams for conversation routing.

Operation	Description
Get Many	List all teams
Get	Get team details
Create	Create a new team
Update	Modify team settings
Delete	Remove a team
Add Agent	Add an agent to a team
Delete Agent	Remove an agent from a team
Get Members	List team members
Update Agents	Update team agent memberships

Webhook

Manage webhook subscriptions programmatically.

Operation	Description
Get Many	List all webhooks
Create	Register a new webhook URL with event subscriptions
Update	Modify webhook URL or subscriptions
Delete	Remove a webhook

Agent Bot

Manage AI agent bots.

Operation	Description
Get Many	List all agent bots
Get	Retrieve an agent bot by ID
Create	Create a new agent bot
Update	Modify agent bot settings
Delete	Remove an agent bot

Automation Rule

Manage automation rules for conversations.

Operation	Description
Get Many	List all automation rules
Get	Retrieve an automation rule by ID
Create	Create a new automation rule
Update	Modify automation rule settings
Delete	Remove an automation rule

Custom Filter

Manage saved filters for conversations and contacts.

Operation	Description
Get Many	List all custom filters
Get	Retrieve a custom filter by ID
Create	Create a new custom filter
Update	Modify filter settings
Delete	Remove a custom filter

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

Operation	Description
Account Summary	Period comparison summary (current vs previous)
Timeseries	Timeseries data for a metric
Bot Summary	Bot-specific summary metrics
Bot Metrics	Bot performance metrics
Agent Statistics	Per-agent summary (CSV)
Inbox Statistics	Per-inbox summary (CSV)
Label Statistics	Per-label summary (CSV)
Team Statistics	Per-team summary (CSV)
Conversation Statistics	Conversation metrics by type
Conversations Summary	Conversation summary (CSV)
Conversation Traffic	Hourly heatmap (CSV)
Inbox Label Matrix	Cross-tabulation of inboxes vs labels
First Response Time Distribution	Distribution of first response times
Outgoing Messages Count	Outgoing counts grouped by entity
Year in Review	Annual review statistics
Conversation Counts	Conversation counts by status (uses v1 /conversations/meta)

Live Report

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

Operation	Description
Conversation Metrics	Real-time counts (open, unattended, unassigned, pending)
Grouped Conversation Metrics	Real-time counts grouped by team or agent

Summary Report

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

Operation	Description
Agent Summary	Per-agent summary metrics
Team Summary	Per-team summary metrics
Inbox Summary	Per-inbox summary metrics
Label Summary	Per-label summary metrics
Channel Summary	Per-channel summary metrics

Applied SLA (Enterprise)

Track SLA compliance per conversation.

Operation	Description
Get Many	List applied SLAs (paginated)
Metrics	SLA hit rate metrics
Download	Export breached conversations as CSV

Profile

Manage user profile.

Operation	Description
Fetch	Get the authenticated user's profile

Help Center

Manage knowledge base content.

Operation	Description
Create Portal	Create a new help center portal
Get Portal	Retrieve portal details by slug
Update Portal	Modify portal settings
Create Category	Add a category to a portal
Create Article	Add an article to a portal

Integration

Manage integrations (Dialogflow, Slack, etc.).

Operation	Description
Get Many	List all integrations
Create Hook	Create an integration hook
Update Hook	Modify hook settings
Delete Hook	Remove an integration hook

Audit Log

Access account activity logs.

Operation	Description
Get Many	Retrieve account audit logs

CSAT Survey

Access customer satisfaction surveys.

Operation	Description
Get	Get CSAT survey for a conversation
Metrics	Get CSAT survey metrics summary
Download	Download CSAT survey responses

Macro

Manage reusable action sequences.

Operation	Description
Get Many	List all macros
Get	Retrieve a macro by ID
Create	Create a new macro with actions
Update	Modify macro settings
Delete	Remove a macro
Execute	Execute a macro on a conversation

Notification

Manage agent notifications.

Operation	Description
Get Many	List notifications (with read/snoozed filters)
Mark Read	Mark a notification as read
Mark Unread	Mark a notification as unread
Mark All Read	Mark all notifications as read
Delete	Remove a notification
Unread Count	Get count of unread notifications

Campaign

Manage outbound campaigns.

Operation	Description
Get Many	List all campaigns
Get	Retrieve a campaign by ID
Create	Create a new campaign
Update	Modify campaign settings
Delete	Remove a campaign

Contact Note

Manage notes on contacts.

Operation	Description
Get Many	List all notes for a contact
Create	Create a note on a contact
Update	Modify a contact note
Delete	Remove a contact note

Conversation Participant

Manage conversation watchers/participants.

Operation	Description
Get Many	List participants of a conversation
Add	Add participants to a conversation
Remove	Remove participants from a conversation

Company (Enterprise)

Manage B2B companies. Requires Chatwoot Enterprise.

Operation	Description
Get Many	List all companies with sorting
Get	Retrieve a company by ID
Create	Create a new company
Update	Modify company settings
Delete	Remove a company
Search	Search companies by name or domain

SLA Policy (Enterprise)

Manage SLA policies. Requires Chatwoot Enterprise.

Operation	Description
Get Many	List all SLA policies
Get	Retrieve an SLA policy by ID
Create	Create an SLA policy with thresholds
Update	Modify SLA policy settings
Delete	Remove an SLA policy

Search (Global)

Search across all entities.

Operation	Description
Search All	Search across conversations, contacts, and messages
Search Conversations	Search conversations only
Search Contacts	Search contacts only
Search Messages	Search messages only

---

Platform API Resources

These resources require the Chatwoot Platform API credential.

Platform Account

Manage accounts at the platform level.

Operation	Description
Create	Create a new account
Get	Retrieve account details
Update	Modify account settings
Delete	Remove an account

Platform User

Manage users at the platform level.

Operation	Description
Create	Create a new platform user
Get	Retrieve user details
Update	Modify user settings
Delete	Remove a user
Get SSO URL	Generate SSO login URL

Account User

Manage users within a specific account.

Operation	Description
Get Many	List all users in an account
Create	Add a user to an account
Delete	Remove a user from an account

Account Agent Bot

Manage agent bots at the account level.

Operation	Description
Get Many	List all account agent bots
Get	Retrieve an agent bot by ID
Create	Create a new account agent bot
Update	Modify agent bot settings
Delete	Remove an account agent bot

---

Public API Resources

These resources require the Chatwoot Public API credential.

Public Contact

Manage contacts via the public API.

Operation	Description
Create	Create a contact via public API
Get	Retrieve contact details
Update	Update contact information

Public Conversation

Manage conversations via the public API.

Operation	Description
Create	Create a conversation via public API
Get	Retrieve a conversation
Get Many	List all conversations for a contact
Resolve	Resolve/toggle conversation status
Toggle Typing	Show typing indicator
Update Last Seen	Mark messages as seen

Public Message

Manage messages via the public API.

Operation	Description
Create	Send a message via public API
Get Many	List messages in a conversation
Update	Update a message

---

Usage Examples

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

Error	Cause	Solution
401 Unauthorized	Invalid API token	Regenerate your API Access Token
403 Forbidden	Insufficient permissions	Use an Administrator account or check inbox access
404 Not Found	Resource doesn't exist	Verify the ID is correct
422 Unprocessable Entity	Invalid data format	Check required fields and data types
429 Rate Limited	Too many requests	Wait 60 seconds (limit: 60 req/min)

Base URL Configuration

Instance Type	Base URL
Chatwoot Cloud	https://app.chatwoot.com
Self-hosted	https://your-domain.com

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

Permission Levels

Role	Access
Administrator	All resources, all inboxes
Agent	Only assigned inboxes, limited operations

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

---

Contributing

Contributions are welcome! See CLAUDE.md for development guidelines.

# Clone and setup
git clone https://github.com/RenatoAscencio/n8n-nodes-chatwoot.git
cd n8n-nodes-chatwoot
npm install

# Development
npm run build      # Compile TypeScript
npm run lint       # Check code style
npm run lint:fix   # Auto-fix issues
npm test           # Run tests
npm run format     # Format with Prettier

# Link for local testing
npm link
cd ~/.n8n/nodes && npm link @renatoascencio/n8n-nodes-chatwoot

---

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