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

• 27 Resources - Comprehensive coverage of Application, Platform, and Public APIs
• 130+ Operations - Complete CRUD operations for all resources
• 3 API Types - Application API, Platform API, and Public API support
• Trigger Node - Real-time webhook events from Chatwoot
• 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 27 resources across three API types:

• Application API (20 resources) - Core operations for conversations, contacts, messages, 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:

• conversation_created - New conversation started
• conversation_status_changed - Status changed (open/resolved/pending/snoozed)
• conversation_updated - Conversation modified
• message_created - New message sent or received
• message_updated - Message edited
• contact_created - New contact added
• contact_updated - Contact information changed
• 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

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

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)
Get Many	Retrieve message history with cursor-based pagination
Update	Update an existing message
Delete	Delete a message

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.

Operation	Description
Account Summary	Get account-level report summary
Agent Statistics	Get agent conversation metrics
Conversation Counts	Get conversation counts by status
Conversation Statistics	Get statistics grouped by agent, inbox, team, or channel

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

---

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