Skip to main content

​
Chatwoot Integration

Chatwoot is an open-source customer engagement platform that brings all your customer conversations into one place. You can integrate Chatwoot with Evolution API to manage WhatsApp conversations through Chatwoot’s unified inbox.

​
What is Chatwoot?

Chatwoot provides:
  • Unified inbox for all customer conversations
  • Team collaboration and assignment
  • Canned responses and shortcuts
  • Conversation labels and filters
  • Customer profiles and context
  • Integration with multiple channels
  • Reporting and analytics

​
Enable Chatwoot Integration

Add these environment variables to your .env file: 
# Enable Chatwoot integration
CHATWOOT_ENABLED=true

# Message behavior settings
CHATWOOT_MESSAGE_READ=true
CHATWOOT_MESSAGE_DELETE=true

# Bot contact for instance updates
CHATWOOT_BOT_CONTACT=true

# Database connection for message import (optional)
CHATWOOT_IMPORT_DATABASE_CONNECTION_URI=postgresql://user:password@host:5432/chatwoot?sslmode=disable
CHATWOOT_IMPORT_PLACEHOLDER_MEDIA_MESSAGE=true

​
Environment Variables Explained

​
CHATWOOT_ENABLED
boolean
required
Enable or disable Chatwoot integration globally
​
CHATWOOT_MESSAGE_READ
boolean
When true, sending a message in Chatwoot marks the customer’s last message as read on WhatsApp. Default: true
​
CHATWOOT_MESSAGE_DELETE
boolean
When false, deleting a message for everyone on WhatsApp will not delete it in Chatwoot. Default: true
​
CHATWOOT_BOT_CONTACT
boolean
When true, creates a contact in Chatwoot to provide QR codes and instance update messages. Default: true
​
CHATWOOT_IMPORT_DATABASE_CONNECTION_URI
string
PostgreSQL connection URI to import messages directly to Chatwoot database (optional)
​
CHATWOOT_IMPORT_PLACEHOLDER_MEDIA_MESSAGE
boolean
When true, imports media messages as placeholders. Default: true

​
Create Chatwoot Integration

1

Get Chatwoot credentials

From your Chatwoot dashboard:
  • Navigate to Settings → Integrations → API
  • Create an API access token
  • Note your Account ID from the URL
2

Configure in Evolution API

Use the create endpoint to connect your WhatsApp instance to Chatwoot.
3

Configure webhook in Chatwoot

Add the provided webhook URL to your Chatwoot inbox settings.
curl -X POST https://your-api.com/chatwoot/create/{instance} \
  -H "apikey: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "accountId": "123456",
    "token": "your-chatwoot-api-token",
    "url": "https://chatwoot.yourdomain.com",
    "nameInbox": "WhatsApp Support",
    "signMsg": true,
    "signDelimiter": "\n\n---\n",
    "number": "5511999999999",
    "reopenConversation": true,
    "conversationPending": false,
    "mergeBrazilContacts": true,
    "importContacts": true,
    "importMessages": false,
    "daysLimitImportMessages": 60,
    "autoCreate": true,
    "organization": "My Company",
    "logo": "https://yoursite.com/logo.png"
  }'

​
Request Parameters

​
enabled
boolean
required
Enable or disable this integration
​
accountId
string
required
Your Chatwoot account ID
​
token
string
required
Chatwoot API access token
​
url
string
required
Your Chatwoot installation URL (e.g., “https://chatwoot.yourdomain.com”)
​
nameInbox
string
Name for the inbox in Chatwoot. Defaults to instance name if not provided
​
signMsg
boolean
required
Add agent signature to messages sent from Chatwoot
​
signDelimiter
string
Delimiter for agent signature. Required if signMsg is true
​
number
string
WhatsApp number associated with this inbox
​
reopenConversation
boolean
Automatically reopen resolved conversations when customer responds
​
conversationPending
boolean
Set new conversations to pending status instead of open
​
mergeBrazilContacts
boolean
Merge contacts with Brazil country code variations (+55)
​
importContacts
boolean
Import existing WhatsApp contacts to Chatwoot
​
importMessages
boolean
Import message history to Chatwoot
​
daysLimitImportMessages
number
Number of days of message history to import. Maximum: 365
​
autoCreate
boolean
Automatically create inbox in Chatwoot if it doesn’t exist
​
organization
string
Organization name for branding
URL to organization logo
​
ignoreJids
array
List of JIDs to exclude from Chatwoot sync

​
Response

{
  "enabled": true,
  "accountId": "123456",
  "token": "your-chatwoot-api-token",
  "url": "https://chatwoot.yourdomain.com",
  "nameInbox": "WhatsApp Support",
  "webhook_url": "https://your-api.com/chatwoot/webhook/my-instance"
}
Copy the webhook_url from the response and add it to your Chatwoot inbox webhook settings.

​
Find Chatwoot Configuration

Retrieve the current Chatwoot configuration for your instance: 
curl -X GET https://your-api.com/chatwoot/find/{instance} \
  -H "apikey: your-api-key"

​
Configure Chatwoot Webhook

After creating the integration, configure the webhook in Chatwoot:
1

Open Chatwoot inbox settings

Navigate to Settings → Inboxes → Select your WhatsApp inbox
2

Add webhook URL

In the “Webhooks” section, add the webhook_url provided by Evolution API
3

Test the connection

Send a message from Chatwoot and verify it appears in WhatsApp

​
Message Synchronization

​
WhatsApp to Chatwoot

All incoming WhatsApp messages are automatically:
  • Created as conversations in Chatwoot
  • Assigned to the inbox
  • Include sender information and context
  • Support media attachments

​
Chatwoot to WhatsApp

Messages sent from Chatwoot:
  • Are delivered through WhatsApp
  • Can include agent signatures (if signMsg: true)
  • Support media attachments
  • Mark WhatsApp messages as read (if CHATWOOT_MESSAGE_READ=true)

​
Contact Management

​
Auto Contact Creation

When autoCreate: true, Evolution API automatically:
  • Creates contacts in Chatwoot for new WhatsApp conversations
  • Updates existing contact information
  • Links conversations to the correct contact

​
Brazil Contact Merging

When mergeBrazilContacts: true, the system:
  • Handles variations of Brazilian phone numbers
  • Merges contacts with different formatting
  • Prevents duplicate contacts for the same person

​
Import Existing Contacts

When importContacts: true:
  • Existing WhatsApp contacts are imported to Chatwoot
  • Contact names and avatars are synchronized
  • Updates are reflected in Chatwoot

​
Message Import

You can import historical WhatsApp messages to Chatwoot: 
{
  "importMessages": true,
  "daysLimitImportMessages": 60
}
Message import requires CHATWOOT_IMPORT_DATABASE_CONNECTION_URI to be configured in your environment.
Importing large message histories can take significant time and resources. Start with a lower daysLimitImportMessages value.

​
Conversation Management

​
Conversation Status

Reopen Conversations: When reopenConversation: true
  • Resolved conversations automatically reopen when customer responds
  • Ensures no customer messages are missed
Pending Status: When conversationPending: true
  • New conversations start in “pending” status
  • Requires manual assignment or automation to move to “open”
  • Useful for triage workflows

​
Delete Behavior

Control how message deletions are handled: 
# Sync deletions from WhatsApp to Chatwoot
CHATWOOT_MESSAGE_DELETE=true

# Keep messages in Chatwoot even when deleted on WhatsApp
CHATWOOT_MESSAGE_DELETE=false

​
Bot Contact

When CHATWOOT_BOT_CONTACT=true, Evolution API creates a special bot contact that:
  • Receives QR codes during instance connection
  • Gets notifications about instance status changes
  • Provides system updates and alerts

​
Agent Signatures

Add agent names to messages sent from Chatwoot: 
{
  "signMsg": true,
  "signDelimiter": "\n\n---\n"
}
Example message with signature: 
Hello! How can I help you today?

---
John (Support Team)

​
Use Cases

Centralize WhatsApp support:
  • Manage all WhatsApp conversations in Chatwoot
  • Assign conversations to team members
  • Use canned responses for common questions
  • Track conversation metrics and SLAs
Unified customer experience:
  • Combine WhatsApp with email, live chat, and social media
  • View complete customer history across channels
  • Provide consistent support experience
  • Route conversations based on channel and priority
Improve team efficiency:
  • Private notes between team members
  • Conversation assignments and transfers
  • Real-time collaboration on customer issues
  • Knowledge base integration
Scale customer support:
  • Queue management and distribution
  • Performance monitoring and reporting
  • Automation and chatbot integration
  • Business hours and auto-assignment rules

​
Best Practices

Always test the integration with a small number of conversations before enabling contact and message import.
  • Use meaningful inbox names: Set nameInbox to help agents identify the WhatsApp channel
  • Enable signatures carefully: Only use signMsg: true if your use case requires it
  • Monitor import progress: Start with small daysLimitImportMessages values
  • Set up automation: Use Chatwoot’s automation features for conversation routing
  • Train your team: Ensure agents understand WhatsApp-specific features and limitations

​
Troubleshooting

  • Verify CHATWOOT_ENABLED=true in environment
  • Check that integration is enabled: enabled: true
  • Confirm webhook URL is configured in Chatwoot inbox settings
  • Verify Chatwoot URL and API token are correct
  • Check Chatwoot logs for webhook delivery errors
  • Enable mergeBrazilContacts: true for Brazilian numbers
  • Check that phone numbers are formatted consistently
  • Verify contact matching logic in Chatwoot
  • Verify webhook URL is correctly configured
  • Check that the instance is connected to WhatsApp
  • Ensure API key has proper permissions
  • Review Evolution API logs for webhook processing errors
  • Verify CHATWOOT_IMPORT_DATABASE_CONNECTION_URI is configured
  • Check database connectivity and credentials
  • Ensure Chatwoot database is accessible from Evolution API
  • Start with a smaller daysLimitImportMessages value
  • Typebot - Interactive chatbot builder
  • OpenAI - AI-powered automation
  • N8N - Workflow automation

Build docs developers (and LLMs) love

Get started for freeTalk to us