Chatwoot Integration

​

Overview

• Receive WhatsApp messages in your Chatwoot inbox
• Reply to WhatsApp messages directly from Chatwoot
• Support text messages, images, audio, video, and file attachments
• Handle both individual chats and group conversations
• Sync message history to Chatwoot

​

Prerequisites

1. Go WhatsApp Web Multidevice running and accessible via a public URL
2. Chatwoot instance (self-hosted or cloud) with admin access
3. API Channel inbox created in Chatwoot
4. At least one WhatsApp device connected and logged in

​

Configuration

​

Environment Variables

​

Configuration Examples

CHATWOOT_ENABLED=true
CHATWOOT_URL=https://app.chatwoot.com
CHATWOOT_API_TOKEN=your_api_token_here
CHATWOOT_ACCOUNT_ID=12345
CHATWOOT_INBOX_ID=67890
CHATWOOT_DEVICE_ID=my-whatsapp-device

# Optional: History sync settings
CHATWOOT_IMPORT_MESSAGES=true
CHATWOOT_DAYS_LIMIT_IMPORT_MESSAGES=7

​

Chatwoot Setup

​

Step 1: Create an API Channel Inbox

1. Log in to your Chatwoot dashboard
2. Navigate to Settings > Inboxes
3. Click Add Inbox
4. Select API as the channel type
5. Configure the inbox:
   • Name: WhatsApp (or any descriptive name)
   • Webhook URL: Leave empty for now (we’ll configure this in Step 4)
6. Click Create Inbox
7. Note down the Inbox ID (visible in the URL or inbox settings)

​

Step 2: Get Your API Token

1. Navigate to Settings > Profile Settings
2. Scroll to Access Token section
3. Copy your API access token

​

Step 3: Find Your Account ID

https://app.chatwoot.com/app/accounts/[ACCOUNT_ID]/dashboard

​

Step 4: Configure the Webhook

1. Navigate to Settings > Integrations > Webhooks
2. Click Add new webhook
3. Configure:
   • URL: https://your-whatsapp-api.com/chatwoot/webhook
   • Events: Select message_created
4. Click Create

​

Multi-Device Setup

​

Finding Your Device ID

1. Access your WhatsApp API at http://your-api:3000
2. Navigate to the device management section
3. Note the Device ID of the device you want to use for Chatwoot

curl http://your-api:3000/devices

​

Configuration

# Using JID format
CHATWOOT_DEVICE_ID=[email protected]

# Or using custom device ID
CHATWOOT_DEVICE_ID=my-support-device

​

Message History Sync

​

Enabling Auto-Sync

CHATWOOT_IMPORT_MESSAGES=true
CHATWOOT_DAYS_LIMIT_IMPORT_MESSAGES=7  # Sync last 7 days

​

Manual Sync via API

curl -X POST "http://your-api:3000/chatwoot/sync" \
  -H "Content-Type: application/json" \
  -d '{
    "device_id": "my-device-id",
    "days_limit": 7,
    "include_media": true,
    "include_groups": true
  }'

​

Sync Options

​

How It Works

1. Reads stored messages from the local chat storage database
2. Creates contacts in Chatwoot for each chat participant
3. Creates conversations for each chat
4. Imports messages with timestamps, preserving chronological order
5. Downloads and attaches media (if enabled and media is still available)

​

Supported Features

​

Incoming Messages (WhatsApp → Chatwoot)

​

Outgoing Messages (Chatwoot → WhatsApp)

​

Group Support

• Groups are automatically detected by JID format (@g.us)
• Group name is used as contact name in Chatwoot
• Replies go to the correct group chat
• Group messages include sender name prefix

​

Architecture

┌─────────────────────┐         ┌──────────────────────┐
│   WhatsApp User     │         │      Chatwoot        │
│                     │         │                      │
└─────────┬───────────┘         └───────────┬──────────┘
          │                                 │
          │ Incoming                        │ Outgoing
          │ Message                         │ Message
          ▼                                 ▼
┌─────────────────────────────────────────────────────────┐
│            Go WhatsApp Web Multidevice                  │
│                                                         │
│  ┌─────────────────┐     ┌─────────────────────────┐   │
│  │ Event Handler   │     │  /chatwoot/webhook      │   │
│  │ (Message Event) │     │  (POST endpoint)        │   │
│  └────────┬────────┘     └───────────┬─────────────┘   │
│           │                          │                  │
│           │ Forward to               │ Resolve Device   │
│           │ Chatwoot API             │ & Send Message   │
│           ▼                          ▼                  │
│  ┌─────────────────┐     ┌─────────────────────────┐   │
│  │ Chatwoot Client │     │  Device Manager         │   │
│  │ (Create Message)│     │  (CHATWOOT_DEVICE_ID)   │   │
│  └─────────────────┘     └─────────────────────────┘   │
└─────────────────────────────────────────────────────────┘

​

Message Flow

1. Incoming (WhatsApp → Chatwoot):
   • WhatsApp message received by connected device
   • Event handler processes the message
   • Message forwarded to Chatwoot API
   • Contact/conversation created if needed
   • Message appears in Chatwoot inbox
2. Outgoing (Chatwoot → WhatsApp):
   • Agent replies in Chatwoot
   • Chatwoot sends webhook to /chatwoot/webhook
   • Handler resolves device from CHATWOOT_DEVICE_ID or default
   • Message sent via WhatsApp
   • Delivery confirmed

​

Troubleshooting

​

Outbound Messages Not Sending

​

Incoming Messages Not Appearing in Chatwoot

​

Common Error Messages

​

Debug Logging

./whatsapp rest --debug=true

APP_DEBUG=true ./whatsapp rest

• Chatwoot Webhook: - Webhook processing
• Chatwoot: - API operations (contact/conversation/message creation)

​

Best Practices

​

Security Considerations

• Keep CHATWOOT_API_TOKEN secure and rotate periodically
• Use HTTPS for all webhook communications
• Consider network-level restrictions on the webhook endpoint
• Monitor for unusual activity in Chatwoot logs
• Use strong authentication for the WhatsApp API (APP_BASIC_AUTH)