Chatwoot — Oshun System Docs

What It Does

Chatwoot is the routing and threading layer for all patient-facing communication. Inbound messages from WhatsApp, Instagram DM, and the website widget land here first, are assigned to the Oshun inbox, and forwarded to Karen AI via webhook for processing.

Maintains conversation threading across channels — a patient who messages via WhatsApp and later via the widget is recognised as the same contact
Serves as the CRM — contact records, conversation history, and labels live here. No separate CRM tool is needed.
Outbound replies from Karen are sent back through Chatwoot via the API, keeping the conversation thread intact
Website widget is embedded on the Oshun site — handles visitor chat and routes to Karen exactly like WhatsApp messages

External Service Details

Cloud account — Account ID 156369. Plan: Starter ($19/mo). Managed at app.chatwoot.com.
Self-hosted instance — Also running at chat.irievybz.ai (account 3) for operator use.
WhatsApp number — +1 876 676 6297 connected via the WhatsApp Business API channel in Chatwoot.

Required environment variables:

CHATWOOT_BASE_URL — API base (e.g. https://app.chatwoot.com)
CHATWOOT_API_TOKEN — user access token for API calls
CHATWOOT_WEBHOOK_SECRET — used to verify inbound webhook payloads
CHATWOOT_ACCOUNT_ID — account ID (156369)

Journeys

Chatwoot is the message routing layer for these patient journeys:

Key Source Files

src/webhooks/chatwoot.js — Registers the Chatwoot webhook route and Cal.com webhook route. Entry: registerChatwootRoutes(). Responds 200 immediately, processes asynchronously.
src/webhooks/chatwoot_actions.js — Dispatches actions triggered by Chatwoot events. Key exports: executeWidgetAction() (website widget requests), executeChatwootAction() (WhatsApp/IG events).
src/webhooks/utils.js — Shared webhook utilities. Key export: replyToChatwoot() — sends Karen's response back as a Chatwoot message via the API.

Known Issues

Instagram DM response latency ~14 seconds. IG DMs go through an extra Meta relay hop before hitting the Chatwoot webhook. The full round-trip (receive → Karen → reply) averages ~14s for IG versus ~4s for WhatsApp. No workaround currently — this is a Meta platform constraint.

6 WhatsApp message templates pending Meta approval. Proactive outbound messages (appointment reminders, care follow-ups) require pre-approved Meta templates. Six templates are currently in review. Until approved, only session-window replies (within 24h of patient initiation) can be sent via WhatsApp.