Chatwoot

  # Chatwoot Integration

Connect your Botpress bot to Chatwoot for seamless customer support with Human-in-the-Loop (HITL) capabilities.

## Features

- ✅ **Full Message Sync**: All conversations appear in Chatwoot dashboard
- ✅ **Multiple Inbox Support**: Works with any Chatwoot inbox (Telegram, WhatsApp, Website, etc.)
- ✅ **HITL (Human-in-the-Loop)**: Seamless handoff between bot and human agents
- ✅ **Rich Messages**: Support for text, images, quick replies, and cards
- ✅ **Private Notes**: Send internal notes visible only to agents
- ✅ **Agent Assignment**: Assign conversations to specific agents or teams
- ✅ **Contact Sync**: Sync customer information with Chatwoot contacts
- ✅ **Self-Hosted Support**: Works with both Chatwoot Cloud and self-hosted instances

## Configuration

### Required Settings

1. **Base URL**: Your Chatwoot instance URL
   - Chatwoot Cloud: `https://app.chatwoot.com`
   - Self-hosted: `https://your-chatwoot-domain.com`

2. **Account ID**: Found in your Chatwoot URL after `/app/accounts/`
   - Example: If URL is `https://app.chatwoot.com/app/accounts/12345/...`, Account ID is `12345`

3. **API Access Token**: Generate from your Chatwoot profile
   - Go to Profile Settings → Access Token → Copy

## Setup Instructions

1. Install this integration from Botpress Hub
2. Configure with your Chatwoot credentials
3. The integration will automatically create a webhook in Chatwoot
4. Start building your bot!

## Available Actions

### Start HITL
Hand off the conversation to a human agent. Optionally provide a summary and assign to specific agent/team.

### Stop HITL  
Return the conversation to bot control by setting status to "pending".

### Send Private Note
Send an internal note visible only to agents (not the customer).

### Assign Agent
Assign the conversation to a specific agent or team.

### Set Conversation Status
Change conversation status: `open`, `pending`, `resolved`, or `snoozed`.

### Sync Contact
Create or update contact information in Chatwoot.

## HITL Workflow

1. Bot handles customer conversation (status: `pending`)
2. Customer requests human → Use "Start HITL" action → (status: `open`)
3. Agent sees conversation in Chatwoot and responds
4. Agent sets status to "pending" when done
5. Bot receives `hitlStopped` event and resumes control

## Message Types

| Botpress | Chatwoot |
|----------|----------|
| Text | Text message |
| Image | Image URL |
| Choice | Quick replies (input_select) |
| Card | Card with buttons |

**Note**: Interactive messages (cards, quick replies) only render properly in Chatwoot's Website widget inbox.

## Support

For issues or feature requests, please contact the integration developer.