Skip to main content

Documentation Index

Fetch the complete documentation index at: https://developers.chatwoot.com/llms.txt

Use this file to discover all available pages before exploring further.

The Chatwoot CLI ships with an agent skill — a small instruction file that teaches AI coding tools (Claude Code, Cursor, Codex, Gemini CLI, and 50+ others) how to use chatwoot correctly. With the skill installed, a prompt like “find conversations tagged refund and assign the unassigned ones to me” runs the right commands, parses JSON properly, and pauses for confirmation before sending customer-visible replies.

​
Install

The skill is published in the chatwoot/cli repository. Use the skills CLI to install it into whichever AI tool you use: 
npx skills add chatwoot/cli
The skills CLI auto-detects the coding agents you have installed and offers to install the skill into each. Add --global (or -g) to install the skill once for every project: 
npx skills add chatwoot/cli --global
The skill activates automatically when you ask the agent to do something Chatwoot-related — “triage my inbox”, “reply to conv 123”, “find conversations tagged refund”.

​
Authenticate the agent

Coding agents run commands non-interactively, so chatwoot auth login has to be run separately. In certain scenarios, agents might be run in a sandbox environment so the API token may not be accessible to them. In this case, you can set the CHATWOOT_API_KEY in your shell or the agent’s environment: 
export CHATWOOT_API_KEY=your_token_here

​
What the skill teaches the agent

  • The id-first grammar — chatwoot conv 123 reply "..." instead of guessing flag layouts.
  • The output contract — parse -o json, never the human-readable text format.
  • Safety rules — reply is customer-visible and irreversible, so the agent shows the full text and asks before sending.
  • Common pitfalls — label replaces rather than appends, --query searches message content (not contacts), assign --agent <name> is a case-insensitive substring match, list endpoints paginate.
  • Composable patterns — -q | xargs for bulk operations, jq chaining for lookups.
The full skill source lives at chatwoot/cli/skills/chatwoot-cli read it directly to see exactly what behavior is shaped.

​
Example prompts

Once the skill is installed, prompts like these work without further setup:
  • “What’s in my open inbox today? Group by priority.”
  • “Find conversations tagged refund that have been pending for more than 48 hours and assign them to Alice.”
  • “Read the last five messages on conv 412 and draft a reply — show it to me before sending.”
  • “Resolve every open conversation tagged spam.”
The agent composes chatwoot commands, parses JSON, and stops to confirm before any write that affects customers.

​
Remove the skill

npx skills remove chatwoot-cli                    # all agents
npx skills remove chatwoot-cli --agent claude-code  # one agent