npm package: @fedcairo/n8n-nodes-chatwoot
Description: N8N community node for Chatwoot - Manage conversations, messages, typing indicators, and more
Author: Federico Aivence
Latest version: 1.0.3

# @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:**
```json
{
  "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:

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

### In Docker N8N:

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

### Manual Installation:

```bash
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](https://github.com/fedcairo/n8n-nodes-chatwoot/issues)
- **NPM**: [@fedcairo/n8n-nodes-chatwoot](https://www.npmjs.com/package/@fedcairo/n8n-nodes-chatwoot)
- **Author**: Federico Aivence (federico@aivence.com)

## 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**