Chatwoot CLI

Independent CLI over the official Chatwoot Application API. It is not an official Chatwoot product. It works with Chatwoot Cloud and with self-hosted instances. The commands are generated from Chatwoot's official swagger (124 endpoints), and field names are unchanged.

Run locally

cd api-apps/chatwoot-api
npm install --workspaces=false
bun run build
node dist/index.js --help

Authentication

You need a user access token from Profile settings → Access Token. The CLI sends it as the api_access_token header.

<secret-manager-command> | chatwoot-api auth --token-stdin                                   # Chatwoot Cloud
<secret-manager-command> | chatwoot-api auth --token-stdin --base-url https://chat.example.com  # self-hosted

You can also use environment variables: CHATWOOT_API_ACCESS_TOKEN, CHATWOOT_BASE_URL (default https://app.chatwoot.com) and CHATWOOT_ACCOUNT_ID. If your user belongs to exactly one account, the CLI reads the account id from your profile. Credentials are saved to ~/.config/chatwoot-api/credentials.json (mode 0600).

Plan caveats:

• On Chatwoot Cloud, user API access tokens are a paid-plan feature. The free plan shows "API access tokens are available on paid plans" and returns an empty token.
• Self-hosted Chatwoot always provides the token.
• Agent-bot tokens only reach the conversation and message endpoints. Contacts, inboxes and agents return 401 for bots.

Coverage

These are the groups, generated from swagger/tag_groups/application_swagger.json by scripts/generate.py:

account, agents, agent-bots, audit-logs, automation-rules, campaigns, canned-responses, contacts, conversations, custom-attributes, custom-filters, inboxes, integrations, labels, messages, portals, profile, reports, teams, webhooks.

Path arguments follow the URL order, and {account_id} is filled in automatically.

The Platform API (super-admin) and the public Client API are not wrapped. Call them with api.

Examples

chatwoot-api conversations list --status open --assignee_type all --all
chatwoot-api messages create 42 --data '{"content":"Thanks, fixed!","message_type":"outgoing"}' --yes
chatwoot-api messages create 42 --data '{"content":"internal note","private":true}' --yes
chatwoot-api conversations toggle-status 42 --data '{"status":"resolved"}' --yes
chatwoot-api conversations assign 42 --data '{"assignee_id":3}' --yes
chatwoot-api contacts search --q [email protected]
chatwoot-api contacts filter --data '{"payload":[{"attribute_key":"email","filter_operator":"contains","values":["@acme.com"]}]}' --all
chatwoot-api api GET /api/v1/accounts/{account_id}/inboxes

Development

python3 scripts/generate.py   # refresh src/endpoints.json from the official swagger
bun test
bun run test:node