@fedcairo/n8n-nodes-chatwoot

Community node for N8N that provides deep integration with Chatwoot customer support platform.

Features

🎯 Two Powerful Nodes

1. Chatwoot - Action Node

Control conversations and messages across WhatsApp, Instagram, and Facebook Messenger:

Message Operations:

• ✉️ Send text messages
• 📎 Send media (images, videos, audio, documents)
• 🔒 Send private notes (internal team communication)

Conversation Operations:

• ✅ Mark as read
• ⌨️ Toggle typing indicator (realistic UX)
• 📊 Change conversation status (open/resolved/pending/snoozed)

2. Chatwoot Trigger - Webhook Node

Clean, parsed webhooks that eliminate Chatwoot's verbose payload:

Features:

• 🧹 Clean Data: Only essential information (90% smaller payload)
• 🔍 Smart Filtering: By event type and channel
• 🎯 Channel Detection: Auto-identifies WhatsApp, Instagram, Facebook, Email, Website
• 📦 Simplified Attachments: Direct URLs and types

Clean Output Example:

{
  "event": "message_created",
  "accountId": 1,
  "conversationId": 123,
  "messageId": 456,
  "channel": {
    "type": "Channel::Whatsapp",
    "name": "WhatsApp Support",
    "inboxId": 789
  },
  "message": {
    "content": "Hello!",
    "contentType": "text",
    "messageType": "incoming",
    "attachments": [
      {
        "type": "image",
        "url": "https://...",
        "extension": "jpg"
      }
    ]
  },
  "contact": {
    "id": 999,
    "name": "John Doe",
    "phone": "+1234567890"
  }
}

Installation

In N8N Cloud or Self-Hosted:

# From N8N UI: Settings → Community Nodes → Install
@fedcairo/n8n-nodes-chatwoot

In Docker N8N:

docker exec -it <n8n-container> sh
cd ~/.n8n/nodes
npm install @fedcairo/n8n-nodes-chatwoot
exit
docker restart <n8n-container>

Manual Installation:

cd ~/.n8n/nodes
npm install @fedcairo/n8n-nodes-chatwoot
# Restart N8N

Configuration

1. Create Chatwoot API Credentials

1. Go to User Settings → Profile Settings
2. Generate Access Token
3. Copy the token

2. Configure in N8N

1. Add Chatwoot API credential
2. Enter your Chatwoot URL (e.g., https://app.chatwoot.com or self-hosted)
3. Paste your API Access Token
4. Test connection

3. Configure Webhook (for Trigger Node)

1. In Chatwoot: Settings → Integrations → Webhooks
2. Add webhook URL from N8N Chatwoot Trigger node
3. Select events: message_created, conversation_status_changed, etc.

Usage Examples

Example 1: AI Customer Support Bot

Chatwoot Trigger (incoming message)
   ↓
AI Agent (Groq/OpenAI) - Generate response
   ↓
Chatwoot (Toggle Typing: ON)
   ↓
Wait (realistic delay based on message length)
   ↓
Chatwoot (Send Text) - Send AI response
   ↓
Chatwoot (Mark as Read)
   ↓
Chatwoot (Toggle Typing: OFF)

Example 2: Send Property Images (Real Estate)

Webhook Trigger (property inquiry)
   ↓
Search Properties API
   ↓
Chatwoot (Toggle Typing: ON)
   ↓
Chatwoot (Send Media) - Property image
   ↓
Chatwoot (Send Text) - Property details
   ↓
Chatwoot (Mark as Read)

Example 3: Auto-Close Resolved Conversations

Chatwoot Trigger (filter: conversation_status_changed)
   ↓
IF (status = "resolved")
   ↓
Wait 24 hours
   ↓
Chatwoot (Change Status: snoozed)

API Reference

Chatwoot Node

Required Fields:

• Account ID: Your Chatwoot account ID (found in URL)
• Conversation ID: The conversation ID to act upon

Operations:

| Resource | Operation | Description | |----------|-----------|-------------| | Message | Send Text | Send text message to conversation | | Message | Send Media | Send image/video/audio/document | | Conversation | Mark as Read | Mark conversation as read | | Conversation | Toggle Typing | Show/hide typing indicator | | Conversation | Change Status | Update conversation status |

Chatwoot Trigger Node

Configuration:

| Field | Type | Description | |-------|------|-------------| | Event Type | Dropdown | Filter by specific events or "All Events" | | Filter Channels | Multi-select | Only trigger for WhatsApp, Facebook, Instagram, etc. | | Include Message Data | Boolean | Include detailed message content | | Include Contact Data | Boolean | Include contact information |

Supported Events:

• message_created
• message_updated
• conversation_created
• conversation_status_changed

Supported Channels:

• WhatsApp (Channel::Whatsapp)
• Facebook Messenger (Channel::FacebookPage)
• Instagram Direct Messages (auto-detected)
• Email (Channel::Email)
• Website (Channel::WebWidget)
• API (Channel::Api)

Benefits Over HTTP Request Nodes

✅ Simpler: No need to construct URLs or headers manually ✅ Validated: Built-in parameter validation ✅ Typed: Autocomplete for all operations ✅ Clean Data: Trigger node eliminates 90% of unnecessary payload ✅ Error Handling: Better error messages and debugging ✅ Future-Proof: Auto-updates when Chatwoot API changes

Compatibility

• N8N Version: 1.0.0+
• Chatwoot Version: v4.1.0+ (tested up to v4.7.0)
• Channels: WhatsApp, Instagram, Facebook Messenger, Email, Website, API

Support

• Issues: GitHub Issues
• NPM: @fedcairo/n8n-nodes-chatwoot
• Author: Federico Aivence ([email protected])

License

MIT License - see LICENSE file for details

Credits

Created by Federico Aivence for the N8N and Chatwoot communities.

Special thanks to:

• N8N team for the amazing automation platform
• Chatwoot team for the open-source customer support platform

Made with ❤️ for the automation community