> ## Documentation Index
> Fetch the complete documentation index at: https://docs.routiq.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Chatwoot Integration

> Connect Chatwoot for multi-channel patient messaging via WhatsApp, SMS, and Email

## Overview

Chatwoot integration enables multi-channel communication with patients through WhatsApp, SMS, and Email from a single platform. It also provides a unified inbox for managing patient responses.

<Info>
  Chatwoot is **optional** but **recommended** for practices wanting multi-channel messaging and team collaboration features.
</Info>

## Benefits

<CardGroup cols={2}>
  <Card title="Multi-Channel" icon="comments">
    Send messages via WhatsApp, SMS, and Email
  </Card>

  <Card title="Unified Inbox" icon="inbox">
    All patient responses in one place
  </Card>

  <Card title="Team Collaboration" icon="users">
    Assign conversations to team members
  </Card>

  <Card title="Message History" icon="clock">
    Complete conversation history per patient
  </Card>
</CardGroup>

## Prerequisites

Before connecting Chatwoot, you need:

* **Chatwoot account** (self-hosted or Chatwoot Cloud)
* **Chatwoot API key** with agent permissions
* **Channels configured** in Chatwoot:
  * WhatsApp (via Twilio, 360Dialog, or WhatsApp Cloud)
  * SMS (via Twilio)
  * Email (via SMTP)

## Setup Guide

<Steps>
  <Step title="Set up Chatwoot Account">
    If you don't have a Chatwoot account:

    1. Sign up at [chatwoot.com](https://www.chatwoot.com)
    2. Choose between:
       * **Chatwoot Cloud** (recommended for ease of use)
       * **Self-hosted** (for full control)
    3. Complete account setup
  </Step>

  <Step title="Configure Messaging Channels">
    In Chatwoot, set up your desired channels:

    ### WhatsApp

    1. Go to **Settings** → **Inboxes** → **Add Inbox**
    2. Select **WhatsApp**
    3. Choose provider (Twilio, 360Dialog, or WhatsApp Cloud)
    4. Follow provider-specific setup instructions
    5. Note your inbox identifier

    ### SMS (via Twilio)

    1. Go to **Settings** → **Inboxes** → **Add Inbox**
    2. Select **Twilio SMS**
    3. Enter Twilio credentials
    4. Configure phone number
    5. Note your inbox identifier

    ### Email

    1. Go to **Settings** → **Inboxes** → **Add Inbox**
    2. Select **Email**
    3. Configure SMTP settings
    4. Set forward-to email address
    5. Note your inbox identifier
  </Step>

  <Step title="Get Chatwoot API Credentials">
    1. Log in to your Chatwoot account
    2. Click your profile picture → **Profile Settings**
    3. Navigate to **Access Token**
    4. Click **Create New Token**
    5. Give it a name: `Routiq Integration`
    6. Copy the **Account ID** (visible in URL: `app.chatwoot.com/app/accounts/YOUR_ID`)
    7. Copy the **Access Token**

    <Warning>
      Store your access token securely. Chatwoot only shows it once.
    </Warning>
  </Step>

  <Step title="Connect in Routiq">
    1. Log in to Routiq
    2. Navigate to **Settings** → **Integrations** → **Chatwoot**
    3. Enter your Chatwoot **Account ID**
    4. Paste your **API Access Token**
    5. Enter your Chatwoot instance URL (e.g., `https://app.chatwoot.com` or your self-hosted URL)
    6. Click **Connect**

    Routiq will validate the connection and fetch your available inboxes.
  </Step>

  <Step title="Map Chatwoot Inboxes">
    After connecting, map Chatwoot inboxes to message types:

    1. **WhatsApp Inbox**: Select your WhatsApp inbox ID
    2. **SMS Inbox**: Select your SMS inbox ID (if different)
    3. **Email Inbox**: Select your Email inbox ID

    <Tip>
      You can use the same inbox for multiple channels if it supports multi-channel.
    </Tip>
  </Step>

  <Step title="Test the Connection">
    Send a test message:

    1. Go to **Settings** → **Integrations** → **Chatwoot**
    2. Click **Send Test Message**
    3. Enter a test phone number/email
    4. Select channel (WhatsApp, SMS, or Email)
    5. Click **Send**

    Check your Chatwoot inbox to verify the message appears.

    <Check>
      Your Chatwoot integration is now active!
    </Check>
  </Step>
</Steps>

## How It Works

### Sending Messages from Routiq

When you create a campaign in Routiq:

1. Routiq identifies patients who meet campaign criteria
2. For each patient, Routiq checks their contact preferences
3. Routiq sends message to Chatwoot API
4. Chatwoot routes message to appropriate channel (WhatsApp/SMS/Email)
5. Message is delivered to patient
6. Delivery status is synced back to Routiq

### Receiving Responses

When patients respond:

1. Response arrives in Chatwoot inbox
2. Chatwoot notifies Routiq via webhook
3. Routiq logs the response and updates campaign metrics
4. Your team can reply directly in Chatwoot

<Info>
  All patient conversations remain in Chatwoot for your team to manage. Routiq only initiates outbound reactivation messages.
</Info>

## Message Templates

### Creating Templates in Routiq

Routiq provides template management for Chatwoot messages:

1. Go to **Settings** → **Message Templates**
2. Click **Create Template**
3. Select channel (WhatsApp, SMS, Email)
4. Write your message with variables:
   * `{{first_name}}` - Patient first name
   * `{{last_name}}` - Patient last name
   * `{{last_visit_date}}` - Last appointment date
   * `{{treatment_type}}` - Last treatment type
5. Preview and save

### WhatsApp Template Requirements

<Warning>
  WhatsApp requires pre-approved message templates for business-initiated conversations.
</Warning>

For WhatsApp Business API:

1. Create template in Meta Business Manager
2. Submit for approval (usually 24-48 hours)
3. Once approved, template becomes available in Chatwoot
4. Use approved template name in Routiq campaigns

[Learn more about WhatsApp templates →](https://developers.facebook.com/docs/whatsapp/message-templates)

## Channel Selection Strategy

### When to use WhatsApp

* **Best for**: High engagement, rich media, two-way conversations
* **Requirements**: Approved message templates
* **Cost**: Moderate (varies by provider)
* **Use cases**: Appointment reminders, reactivation campaigns, follow-ups

### When to use SMS

* **Best for**: Urgent messages, universal reach
* **Requirements**: None - works on all phones
* **Cost**: Low to moderate
* **Use cases**: Quick reminders, time-sensitive messages

### When to use Email

* **Best for**: Detailed information, newsletters
* **Requirements**: Valid email addresses
* **Cost**: Very low
* **Use cases**: Educational content, detailed communications

<Info>
  Response rates vary significantly based on your practice, patient demographics, and message quality. Start with small test campaigns to establish your baseline.
</Info>

## Managing Patient Responses

### Chatwoot Inbox Workflow

1. Patient responses appear in Chatwoot inbox
2. Assign conversation to team member
3. Team member responds within Chatwoot
4. Conversation history is preserved
5. Close conversation when resolved

### Response Routing

Configure automatic routing in Chatwoot:

1. Go to **Settings** → **Automation Rules**
2. Create rule: Route conversations from Routiq to specific team/agent
3. Set business hours for auto-assignment
4. Configure canned responses for common questions

## Security & Compliance

### Data Protection

* API credentials encrypted at rest with AES-256
* All communications use TLS 1.2+
* Patient data accessible only within your Chatwoot account
* No patient data stored permanently in Routiq

### HIPAA Considerations

If you're subject to HIPAA:

<Warning>
  WhatsApp and SMS are not appropriate channels for transmitting PHI. Routiq is not HIPAA-certified; if you operate under HIPAA, review your PHI handling with your compliance officer.
</Warning>

**Recommendations**:

* Use secure messaging for PHI
* Obtain patient consent for SMS/WhatsApp
* Avoid sending sensitive health information
* Use generic appointment reminders

[Our security & compliance posture →](/security/compliance)

## Troubleshooting

### "Invalid API credentials" error

**Solution**:

1. Verify Account ID is correct (check Chatwoot URL)
2. Regenerate API token in Chatwoot
3. Ensure token has "Agent" permissions
4. Try reconnecting

### Messages not sending

**Possible causes**:

* Inbox not configured in Chatwoot
* Channel (WhatsApp/SMS) not connected
* Insufficient balance (for Twilio-based channels)

**Solution**:

1. Check Chatwoot inbox is active
2. Verify channel is connected and working
3. Test sending directly from Chatwoot
4. Check provider balance (Twilio, etc.)

### WhatsApp messages failing

**Possible causes**:

* Template not approved by Meta
* 24-hour messaging window expired
* Patient phone number not opted in

**Solution**:

1. Use only approved WhatsApp templates
2. Only send business-initiated messages with approved templates
3. Ensure phone numbers are valid and opted in

### Responses not syncing to Routiq

**Possible causes**:

* Webhook not configured
* Webhook URL incorrect
* Chatwoot firewall blocking webhook delivery

**Solution**:

1. Go to **Settings** → **Integrations** → **Chatwoot** → **Webhook Status**
2. Verify webhook URL is configured in Chatwoot
3. Test webhook delivery
4. Check Chatwoot webhook logs

## Advanced Features

### Conversation Assignment

Automatically assign patient conversations to specific team members based on:

* Treatment type
* Practitioner
* Business location
* Time of day

Configure in **Settings** → **Chatwoot** → **Assignment Rules**

### Canned Responses

Create quick responses for common patient questions:

1. In Chatwoot: **Settings** → **Canned Responses**
2. Create responses for:
   * Booking appointments
   * Pricing questions
   * Business hours
   * Location/directions

### Tags and Labels

Use Chatwoot tags to categorize conversations:

* `reactivation` - Routiq-initiated conversations
* `booked` - Patient booked appointment
* `not_interested` - Patient declined
* `follow_up` - Needs follow-up

## Disconnecting Chatwoot

To disconnect Chatwoot:

1. Go to **Settings** → **Integrations** → **Chatwoot**
2. Click **Disconnect**
3. Confirm action

<Warning>
  Active campaigns will stop sending messages. Patient conversation history remains in Chatwoot.
</Warning>

## Next Steps

<CardGroup cols={2}>
  <Card title="Create Campaigns" icon="megaphone" href="/features/campaigns">
    Build automated reactivation campaigns
  </Card>

  <Card title="Launch Campaign" icon="rocket" href="/getting-started/quickstart">
    Start your first reactivation campaign
  </Card>
</CardGroup>