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