Chatwoot Setup

Chatwoot provides the support chat backend for FrameWorks. Deckhand integrates with Chatwoot to enable customer messaging from the webapp.

Initial Setup

After starting Chatwoot for the first time:

1. Create Admin Account

Visit http://localhost:18092 when using the local FrameWorks compose stack (or your deployed Chatwoot URL) and complete the setup wizard to create your admin account. Chatwoot still listens on port 3000 inside its container; the FrameWorks compose and Ansible defaults expose it on host port 18092.

2. Get API Token

1. Click the profile icon (bottom-left corner)
2. Go to Profile Settings
3. Copy the Access Token value
4. Set it in your environment:

   CHATWOOT_API_TOKEN=your-token-here

3. Create API Inbox

1. Go to Settings → Inboxes
2. Click Add Inbox
3. Select API as the channel type
4. Name it FrameWorks Support
5. Complete the wizard

Note the inbox ID from the URL (e.g., /app/accounts/1/settings/inboxes/1 → inbox ID is 1).

4. Add Custom Attributes

Go to Settings → Custom Attributes and add each of these:

Applies to	Display Name	Key	Type	Description
Conversation	Tenant ID	tenant_id	Text	Customer tenant identifier
Conversation	Page URL	page_url	Link	Page where conversation started
Conversation	Subject	subject	Text	Conversation subject line

Deckhand writes these as conversation custom attributes when it creates a support thread. Contacts are matched using the contact source_id; no contact custom attributes are required for the current integration.

5. Configure Webhook

1. Go to Settings → Integrations → Webhooks
2. Click Configure then Add new webhook
3. Set the URL:
   • Ansible Docker Chatwoot + native Deckhand: http://host.docker.internal:18015/webhooks/chatwoot
   • Same Docker network for both services: http://deckhand:18015/webhooks/chatwoot
4. Check these events:
   • conversation_created
   • conversation_updated
   • message_created
   • message_updated
5. Click Create Webhook

Environment Variables

# Required
CHATWOOT_SECRET_KEY=   # Chatwoot Rails secret; compose requires it, Ansible can generate it
CHATWOOT_API_TOKEN=    # From step 2 above; Deckhand requires it

# Defaults (usually don't need to change for docker-compose)
CHATWOOT_HOST=chatwoot
CHATWOOT_PORT=3000
CHATWOOT_ACCOUNT_ID=1
CHATWOOT_INBOX_ID=1

For production GitOps deployments, set CHATWOOT_FRONTEND_URL, CHATWOOT_ACCOUNT_ID, CHATWOOT_INBOX_ID, and CHATWOOT_API_TOKEN in the shared environment after creating the Chatwoot account and API inbox.

How It Works

1. User opens support chat in webapp
2. Webapp sends message to Bridge GraphQL API
3. Bridge forwards to Deckhand gRPC service
4. Deckhand creates/finds contact in Chatwoot (using tenant_id as source_id)
5. Deckhand creates conversation with custom attributes
6. Chatwoot webhook notifies Deckhand of agent replies
7. Deckhand broadcasts to webapp via Signalman

Troubleshooting

Empty conversations list: Contact’s source_id doesn’t match tenant ID. Edit the contact in Chatwoot and set source_id to the tenant’s UUID.

Webhook not firing: Verify the webhook URL is reachable from the Chatwoot container. For the Ansible Docker stack, use http://host.docker.internal:18015/webhooks/chatwoot.

“Inbox not found” errors: Ensure CHATWOOT_INBOX_ID matches the inbox you created.