Chat

The Chat module surfaces the health of the customer chat/helpdesk inbox — which runs in Chatwoot, a separate helpdesk platform, not inside the ERP itself — as a "Chat" tab on the ERP dashboard, and mirrors conversations/messages locally so they show up in a Customer or CRM Contact's interaction timeline. It's used by support/admin staff who want an at-a-glance read on open conversations and response times without leaving the dashboard, and by anyone viewing a Customer/Lead/Deal record who wants to see their chat history alongside calls and emails.

What you can do

• Dashboard "Chat" tab — see live cards for open conversations, unassigned conversations, new conversations and resolutions over the selected period, average first-response time and average resolution time, incoming/outgoing message counts, and total contacts.
• Spot dropped conversations at a glance — the Open and Unassigned cards render in red the moment anything is waiting, so an unattended chat is visible without opening the tab.
• Track service-level trends — a "new conversations per day" line chart, and first-response/resolution-time cards graded green/amber/red against built-in targets (first response within 60 minutes, resolution within 24 hours).
• Jump straight into Chatwoot — every card and the recent-conversations list link out to the matching view in Chatwoot (inbox, reports, or contacts).
• Browse recent conversations — a "Recent conversations" list of the 10 most recently active conversations, showing who's writing, a snippet of their last message, and status.
• See chat history on a Customer/Contact record — the Customer drawer's Interactions tab, and the CRM Contact/Deal drawers' Interactions tab, include Chatwoot messages merged in with calls and emails, newest first.
• Link a Chatwoot contact to a Customer or CRM Contact manually — when the automatic email/phone match misses (or matched the wrong record), link a Chatwoot contact ID to the correct Customer or Contact by hand.
• Configure the Chatwoot connection — set the Chatwoot URL, account ID, and API token via the Remote Connections grid (or environment fallback), and fetch the webhook URL/secret to paste into Chatwoot's own webhook settings.

Common tasks

1. Check today's chat volume on the dashboard Open the ERP dashboard and switch to the "Chat" tab. The cards show the current open/unassigned counts plus new conversations, resolutions, and message volumes for the selected reporting window (days).

2. Investigate an unassigned or slow-response conversation From the Chat tab, click the Open or Unassigned card (or an item in the recent-conversations list) to jump straight into that inbox view in Chatwoot, where the conversation can be picked up or reassigned.

3. Review response-time trends Look at the "Avg first response" and "Avg resolution" cards — they're colour-graded (green/amber/red) against the built-in targets — and click through to Chatwoot's Reports Overview for the full breakdown, or follow the "New conversations per day" chart for volume trends.

4. See a customer's full chat history Open a Customer record and go to its Interactions tab (or a CRM Contact/Deal's Interactions tab) — Chatwoot messages for that person appear inline with their calls and emails, matched automatically by email/phone.

5. Link a conversation to the right Customer/Contact manually If a Chatwoot conversation didn't auto-match (or matched the wrong person), find the Chatwoot contact ID in Chatwoot and use the manual link action on the correct Customer or CRM Contact to attach it — this also backfills any of that contact's existing conversation rows.

6. Set up the Chatwoot webhook (one-time, per site) Fetch the webhook URL and secret for this site, then paste them into Chatwoot under Settings → Integrations → Webhooks, subscribed to Conversation Created/Updated, Message Created and Contact Updated. A secret is auto-generated the first time this is fetched if none exists yet.

Data model

Chatwoot itself stays the system of record; these tables are a local, queryable mirror fed by the webhook, plus two link columns on existing tables. None of it is tenant-scoped — Chatwoot is treated as one site-wide inbox.

Table / column	Purpose
chatwoot_conversations	One row per Chatwoot conversation — inbox, channel (website/whatsapp/email/etc.), status, assignee, a snapshot of the contact's name/email/phone, and the matched customer_id/contact_id (either may be null until matched).
chatwoot_messages	One row per Chatwoot message on a mirrored conversation — direction (incoming/outgoing/note), content, sender name, and Chatwoot's own sent-at timestamp.
acc_customer.chatwoot_contact_id	The Chatwoot contact this Customer is linked to (auto-matched or manually linked).
crm_contacts.chatwoot_contact_id	The Chatwoot contact this CRM Contact is linked to (auto-matched or manually linked).

Configuration & integrations

• The module talks to a single external Chatwoot installation (chat.telecloud.co.za in production) over its REST API, authenticated with a user API access token belonging to an account administrator (Chatwoot's v2 reports endpoints are admin-only), sent as the api_access_token header.
• Connection settings — URL, API token, account ID — resolve from the chatwoot row on the Remote Connections grid first, falling back to the CHATWOOT_URL / CHATWOOT_API_TOKEN / CHATWOOT_ACCOUNT_ID environment settings. If the URL or token is missing, the dashboard tab simply returns no data instead of erroring.
• Inbound sync runs the other way: Chatwoot pushes events (Conversation Created/Updated, Message Created, Contact Updated) to this site's webhook receiver, gated by a shared ?secret= query parameter (Chatwoot has no built-in webhook signing). The webhook URL and secret are fetched from the API and pasted into Chatwoot's own webhook settings; the secret is auto-provisioned on first fetch if not already set.
• Incoming Chatwoot contacts are auto-matched to an existing Customer or CRM Contact by email or phone (never creates a new record) and the match is cached on chatwoot_contact_id so later events for the same contact skip straight to it.

API reference

Method & Path	Purpose
POST /webhooks/chatwoot?secret=…	Webhook receiver — ingests message_created, conversation_created/conversation_updated, and contact_created/contact_updated events from Chatwoot; unauthenticated, gated by the shared secret. Always returns 200 on anything accepted or intentionally ignored.
GET /chatwoot/webhook-info	Returns the webhook URL and secret to paste into Chatwoot's settings, auto-provisioning a secret on first call.
POST /customers/{customer_id}/chatwoot-link	Manually link a Chatwoot contact ID to an AccCustomer, and backfill any of that contact's existing conversation rows.
POST /crm/contacts/{contact_id}/chatwoot-link	Manually link a Chatwoot contact ID to a CRM Contact, and backfill any of that contact's existing conversation rows.
GET /customers/{customer_id}/interactions	Merged interaction timeline (calls, emails, Chatwoot messages) for a Customer.
GET /erp/sites/{site}/stats	Powers the dashboard tabs generally; for the "chat" category this returns the Chat tab's cards, chart, and recent-conversations items, sourced live from Chatwoot's API rather than the local mirror tables.

There is no dedicated grid CRUD surface for chatwoot_conversations / chatwoot_messages — they're written only by the webhook receiver and read via the interaction-timeline endpoints above, not exposed as an editable admin grid.