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