# Chatwoot — Open Source Customer Support & Live Chat

> Chatwoot is an open-source Intercom/Zendesk alternative with live chat, email, social media support, and omnichannel inbox for customer communication.

## Install

Save the content below to `.claude/skills/` or append to your `CLAUDE.md`:

## Quick Use

```bash
docker run --name chatwoot -p 3000:3000 
  -e SECRET_KEY_BASE=$(openssl rand -hex 64) 
  -e FRONTEND_URL=http://localhost:3000 
  chatwoot/chatwoot:latest
```

Open `http://localhost:3000` — create your admin account and set up your first inbox.

## Intro

**Chatwoot** is an open-source customer engagement platform that serves as an alternative to Intercom, Zendesk, and Freshdesk. Built with Ruby on Rails and Vue.js, it provides a unified inbox for managing customer conversations across live chat, email, social media (WhatsApp, Facebook, Instagram, Twitter), and messaging apps — all from a single dashboard.

With 28.4K+ GitHub stars, Chatwoot empowers businesses to provide excellent customer support while maintaining full control over their data and reducing SaaS costs.

## What Chatwoot Does

Chatwoot covers the entire customer communication workflow:

- **Live Chat Widget**: Embeddable chat widget for your website with customizable branding
- **Omnichannel Inbox**: Unified inbox for chat, email, WhatsApp, Facebook Messenger, Instagram DM, Twitter, Telegram, LINE, and SMS
- **Team Collaboration**: Agent assignment, team routing, internal notes, and canned responses
- **Automation**: Rule-based automation for routing, labeling, and auto-responses
- **CRM Contacts**: Customer profiles with conversation history, custom attributes, and notes
- **Reporting**: Agent performance, conversation metrics, CSAT scores, and SLA tracking
- **Bot Integration**: Connect with Dialogflow, Rasa, or custom AI bots for automated responses

## Architecture

```
┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│  Chat Widget │────▶│  Rails API   │────▶│  PostgreSQL  │
│  + Dashboard │     │  + Sidekiq   │     │  + Redis     │
│  (Vue.js)    │     │  (Ruby)      │     │              │
└──────────────┘     └──────┬───────┘     └──────────────┘
                            │
              ┌─────────────┼─────────────┐
              │             │             │
       ┌──────┴──┐   ┌─────┴───┐   ┌─────┴───┐
       │WhatsApp │   │Facebook │   │ Email   │
       │  API    │   │  API    │   │ (IMAP)  │
       └─────────┘   └─────────┘   └─────────┘
```

## Self-Hosting

### Docker Compose

```yaml
services:
  chatwoot-web:
    image: chatwoot/chatwoot:latest
    command: bundle exec rails s -b 0.0.0.0 -p 3000
    ports:
      - "3000:3000"
    environment:
      SECRET_KEY_BASE: your-secret-key
      FRONTEND_URL: http://localhost:3000
      DATABASE_URL: postgresql://chatwoot:chatwoot@postgres:5432/chatwoot
      REDIS_URL: redis://redis:6379
      RAILS_ENV: production
    depends_on:
      - postgres
      - redis

  chatwoot-worker:
    image: chatwoot/chatwoot:latest
    command: bundle exec sidekiq
    environment:
      SECRET_KEY_BASE: your-secret-key
      DATABASE_URL: postgresql://chatwoot:chatwoot@postgres:5432/chatwoot
      REDIS_URL: redis://redis:6379
    depends_on:
      - postgres
      - redis

  postgres:
    image: postgres:16
    environment:
      POSTGRES_USER: chatwoot
      POSTGRES_PASSWORD: chatwoot
      POSTGRES_DB: chatwoot
    volumes:
      - pg-data:/var/lib/postgresql/data

  redis:
    image: redis:7-alpine
    volumes:
      - redis-data:/data

volumes:
  pg-data:
  redis-data:
```

## Key Features

### Chat Widget Integration

```html
<!-- Add to your website -->
<script>
  (function(d,t) {
    var BASE_URL="http://localhost:3000";
    var g=d.createElement(t),s=d.getElementsByTagName(t)[0];
    g.src=BASE_URL+"/packs/js/sdk.js";
    g.defer = true;
    g.async = true;
    s.parentNode.insertBefore(g,s);
    g.onload=function(){
      window.chatwootSDK.run({
        websiteToken: 'YOUR_WEBSITE_TOKEN',
        baseUrl: BASE_URL
      })
    }
  })(document,"script");
</script>
```

### Automation Rules

Set up automatic workflows:
- **Auto-assign**: Route conversations to specific agents/teams based on channel, content, or customer attributes
- **Auto-label**: Tag conversations automatically based on keywords or patterns
- **SLA Alerts**: Notify agents when response time thresholds are approaching
- **Auto-resolve**: Close inactive conversations after a set period

### Canned Responses

Pre-built reply templates for common questions:
```
/greeting  → "Hi there! Thanks for reaching out. How can I help?"
/pricing   → "Our plans start at $X/month. Here's a detailed comparison: [link]"
/refund    → "I understand. I've initiated a refund for your order #..."
```

### API Integration

```bash
# Create a contact
curl -X POST http://localhost:3000/api/v1/accounts/1/contacts 
  -H "api_access_token: YOUR_TOKEN" 
  -H "Content-Type: application/json" 
  -d '{"name": "John Doe", "email": "john@example.com"}'

# Send a message
curl -X POST http://localhost:3000/api/v1/accounts/1/conversations/1/messages 
  -H "api_access_token: YOUR_TOKEN" 
  -d '{"content": "Hello! How can I help?", "message_type": "outgoing"}'
```

## Chatwoot vs Alternatives

| Feature | Chatwoot | Intercom | Zendesk | Freshdesk |
|---------|----------|----------|---------|-----------|
| Open Source | Yes | No | No | No |
| Self-hosted | Yes | No | No | No |
| Live chat | Yes | Yes | Yes | Yes |
| WhatsApp | Yes | Add-on | Add-on | Add-on |
| Email | Yes | Yes | Yes | Yes |
| AI bot | Integration | Built-in | Built-in | Built-in |
| Pricing | Free (self-host) | $74/seat/mo | $55/agent/mo | $15/agent/mo |

## FAQ

**Q: What support team sizes is Chatwoot suitable for?**
A: From 1 person to 100+ agents. The self-hosted version has no seat limit. Larger teams should deploy via Kubernetes for better scalability.

**Q: How do I integrate the WhatsApp Business API?**
A: Chatwoot supports WhatsApp Cloud API (official from Meta) and third-party BSPs (like 360dialog). Apply for WhatsApp Business API access through Meta Business, then configure the Channel in Chatwoot.

**Q: Can I plug in an AI support bot?**
A: Yes. Chatwoot has native integrations with Dialogflow CX/ES and Rasa. You can also connect any custom AI service (OpenAI, Claude, etc.) via webhooks for smart replies.

## Source & Thanks

- GitHub: [chatwoot/chatwoot](https://github.com/chatwoot/chatwoot) — 28.4K+ ⭐
- Website: [chatwoot.com](https://chatwoot.com)

---
Source: https://tokrepo.com/en/workflows/chatwoot-open-source-customer-support-live-chat-60e0b759
Author: AI Open Source