Chatwoot

Chatwoot

This connector uses the Chatwoot Application API (/api/v1 and the /api/v2 reports) of Chatwoot Cloud or your own self-hosted Chatwoot: inboxes, conversations and their messages, contacts, labels, agents, teams, canned responses and the support reports. Replies, private notes and new conversations are included but installed switched off.

Setup (about 2 minutes)

1. Sign in to Chatwoot with the user the AI should act as. Agents only see conversations of the inboxes they belong to and cannot read reports, so use an administrator for the full picture.
2. Click your avatar, Profile Settings, and copy the Access Token at the bottom of the page into CHATWOOT_API_TOKEN. It does not expire; reset it on the same page.
3. CHATWOOT_URL is the address you open Chatwoot at: https://app.chatwoot.com on Chatwoot Cloud, or your own domain (e.g. https://chat.example.com) when self-hosted. No path, no /api.
4. CHATWOOT_ACCOUNT_ID is the number after /app/accounts/ in the browser address bar (e.g. https://app.chatwoot.com/app/accounts/3/dashboard means 3). chatwoot_get_profile also lists every account of the token under accounts.
5. Install and run chatwoot_get_profile to check the token.

The account token is not the Platform App token of a self-hosted super admin (/platform/api); this connector does not use the Platform API.

Self-hosted behind nginx: the token travels in the api_access_token header. nginx drops headers with an underscore unless underscores_in_headers on; is set, which shows up as 401 on every call although the token is right.

Workflow

• Find things first: chatwoot_list_inboxes, chatwoot_list_agents, chatwoot_list_teams, chatwoot_list_labels, chatwoot_list_inbox_agents, chatwoot_list_team_members, chatwoot_list_canned_responses, chatwoot_list_custom_attributes, chatwoot_get_account.
• Conversations: chatwoot_list_conversations (status open by default, 25 per page; page until the list is empty), chatwoot_count_conversations for counts only, chatwoot_filter_conversations for conditions such as "created after a date and assigned to agent 4", chatwoot_get_conversation, then chatwoot_list_messages for the thread. Message types: 0 incoming from the contact, 1 outgoing, 2 activity, 3 template; private notes have private: true.
• Contacts: chatwoot_search_contacts (name, e-mail, phone, identifier), chatwoot_list_contacts, chatwoot_get_contact, chatwoot_list_contact_conversations.
• Reports (administrator token): chatwoot_get_report_summary for a period with the previous period alongside, chatwoot_get_report_timeseries for a metric over time, chatwoot_get_summary_by to compare agents, inboxes or teams, chatwoot_get_live_conversation_stats for what is open and unattended now.

Dates: conversation and message times, and the since / until of the reports, are Unix timestamps in seconds (UTC). Convert before quoting a time to the user. Report times (avg_first_response_time, avg_resolution_time, reply_time) are seconds.

Labels: chatwoot_set_conversation_labels replaces the whole label list of a conversation. To add one, send the current labels plus the new title; to remove one, send the list without it.

Writes switched off: chatwoot_send_message (reply or private note) and chatwoot_create_conversation reach the customer at once on WhatsApp, e-mail or chat, so an admin turns them on deliberately. Before each call show the user the text and the recipient and wait for a yes. A private note (private: true) is internal. WhatsApp Cloud API inboxes only deliver free text within 24 hours of the contact's last message; outside that window Chatwoot needs an approved template, which this connector does not send.

Managing agents (switched off): chatwoot_add_agent invites a person (Chatwoot e-mails them at once and, on Chatwoot Cloud, the seat is billed), chatwoot_update_agent changes role or availability (Chatwoot wants the role on every update), chatwoot_remove_agent takes their access away. All three need an administrator token and are installed switched off; take the agent id from chatwoot_list_agents, show the change and wait for a yes.

Errors: 401 means a wrong or reset token (or nginx dropping the header). 404 on every call usually means a wrong CHATWOOT_URL or CHATWOOT_ACCOUNT_ID; 404 on one conversation means an id the user cannot see. Reports answer 401 or 403 for agents who are not administrators.