@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. Meta Platform APIs (Optional but Recommended)

To enable typing indicators, read receipts, and direct media sending on WhatsApp, Instagram, and Facebook Messenger, configure the Meta Platform credentials:

For WhatsApp:

1. Go to Meta Business Suite
2. Navigate to your WhatsApp Business Account
3. Get your WhatsApp Access Token and Phone Number ID
4. Add them in the credential configuration

For Facebook Messenger:

1. Create a Facebook App at developers.facebook.com
2. Add the Messenger product
3. Generate a Page Access Token
4. Add your Facebook Page ID and token

For Instagram:

1. Your Instagram Business Account must be linked to a Facebook Page
2. Use the same Facebook Page Access Token
3. Add your Instagram Page ID (same as Facebook Page ID if linked)
4. Important: Enable "Instagram API for Typing/Read" toggle only if you have Meta permissions for instagram_manage_messages

⚠️ Note on Instagram API: Instagram uses graph.instagram.com API (v21.0+). If you don't have advanced Meta permissions for typing indicators, disable the "Instagram API for Typing/Read" toggle - media sending and mark as read will still work through Meta's API (only typing indicator requires app verification).

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

How It Works Internally

Channel Detection

The node automatically detects the channel type from Chatwoot's conversation data and routes API calls accordingly.

Media Sending (Always Meta API)

All media is sent directly through Meta's official APIs - no Chatwoot fallback:

| Channel | API Used | Endpoint | |---------|----------|----------| | WhatsApp | Meta Cloud API | graph.facebook.com/v17.0/{phone_id}/messages | | Instagram | Instagram Graph API | graph.instagram.com/v21.0/{page_id}/messages | | Facebook Messenger | Messenger Platform API | graph.facebook.com/v17.0/{page_id}/messages |

Typing Indicators & Read Receipts

| Channel | Typing ON | Mark as Read | |---------|-----------|--------------| | WhatsApp | Meta Cloud API | Meta Cloud API | | Facebook Messenger | Messenger Platform API | Messenger Platform API | | Instagram | See note below | Instagram Graph API (always works) |

Instagram Typing ON - Special Case

Instagram's typing indicator requires your Meta App to be verified and approved by Meta (submitted for App Review with instagram_manage_messages permission).

If your app is verified:

• Enable "Instagram API for Typing/Read" toggle in credentials
• Uses graph.instagram.com/v21.0 API for typing indicator

If your app is NOT verified:

• Disable "Instagram API for Typing/Read" toggle
• Falls back to Chatwoot's native API for typing indicator
• Mark as Read and Media sending still work - only typing is affected

Changelog

v2.0.18 (December 2025)

• Fixed: Instagram API now uses correct endpoint graph.instagram.com instead of graph.facebook.com
• Fixed: Updated Instagram API to v21.0 for compatibility
• Added: Toggle to disable Instagram typing/read API for accounts without Meta permissions
• Improved: Better error handling for Instagram API responses

v2.0.17

• Added Meta Platform APIs support for WhatsApp, Instagram, and Facebook Messenger
• Typing indicators and read receipts via direct Meta APIs
• Media sending through native platform APIs

v2.0.0

• Complete rewrite with cleaner architecture
• Added Chatwoot Trigger node with clean webhook parsing
• Multi-channel support (WhatsApp, Instagram, Facebook, Email, Website)

Troubleshooting

Instagram "Unsupported post request" error

This usually means:

1. Your Meta App doesn't have instagram_manage_messages permission
2. Solution: Disable "Enable Instagram API for Typing/Read" in credentials

Typing indicator not working

1. Verify Meta credentials are correctly configured
2. Check that the Access Token has required permissions
3. For Instagram, ensure the toggle is enabled AND you have permissions

Media not sending

1. For social channels, verify the media URL is publicly accessible
2. Check file size limits (WhatsApp: 16MB, Instagram: 8MB, Messenger: 25MB)

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