canonical: https://jentic.com/apis/chatwoot.com/chatwoot

# Chatwoot

Chatwoot is an open-source customer engagement platform that unifies conversations from email, web chat, social channels, and messaging apps into a shared inbox. Its API exposes deep control over accounts, agents, contacts, conversations, messages, inboxes, teams, labels, automation rules, and reporting - 144 endpoints across more than 30 resource groups. It supports three distinct API token types (user, agent bot, and platform app) so you can build everything from in-app integrations to multi-tenant provisioning. This specification is derived from the OpenAPI description Chatwoot publishes in its own open-source repository, kept validated and agent-ready.

## For AI agents

Manage Chatwoot conversations, contacts, agents, inboxes, and automation rules through a single API so an agent can triage support tickets, send replies, label conversations, and pull reports.

## Scope

Does not handle outbound marketing campaigns, voice telephony, or payment processing - use for managing customer support conversations, contacts, and agent workflows only.

## Capabilities

- Create, list, and update contacts and merge duplicates across inboxes
- Read and reply to conversations across email, web, and messaging channels
- Send outbound messages and attach private notes for agent collaboration
- Provision inboxes, agents, teams, and labels for new accounts
- Configure automation rules that route conversations and apply labels
- Pull reporting metrics on conversation volume, agent load, and CSAT
- Manage agent bots and webhooks for custom workflow extensions

## Use cases

### Automated Conversation Triage

Route incoming customer conversations to the right team based on content, channel, or contact attributes. Use the conversations and labels endpoints to inspect new threads, apply tags, and assign them to agents or teams. Pair with automation rules so the platform handles routine cases without human intervention.

Example prompt: Fetch all unassigned conversations in account 12, label any matching 'billing' as 'finance-team', and assign them to team_id 4.

### Unified Contact Management

Keep customer profiles in sync between Chatwoot and your CRM. Create, search, and update contacts via the Contacts API; attach custom attributes for product tier or lifecycle stage; and merge duplicates that arrive through different channels. Useful for support teams running on multiple sources of truth.

Example prompt: Create a contact for 'jane@example.com' with custom attribute plan='enterprise' in account 12 and confirm the contact id is returned.

### Support Reporting and Analytics

Pull operational metrics - conversation volume, response times, agent workload, CSAT - into a BI tool or weekly stand-up summary. The Reports endpoints aggregate by team, agent, label, or inbox, so you can compare performance across channels and time windows without exporting data manually.

Example prompt: Pull the agents report for account 12 between 2026-06-01 and 2026-06-07 and summarise the top three agents by conversations resolved.

### AI Agent for Customer Support

An autonomous agent watches Chatwoot for new conversations, drafts contextual replies based on the contact's history and product, posts them as private notes for human approval, and labels the thread. Through Jentic, the agent calls the Conversations and Messages APIs without ever holding the api_access_token in its prompt.

Example prompt: Through Jentic, search 'reply to a conversation', load the schema, and post a private note suggesting a refund for conversation_id 9876.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/api/v1/accounts/{account_id}/conversations` | List conversations in an account |
| POST | `/api/v1/accounts/{account_id}/conversations/{conversation_id}/messages` | Send a message in a conversation |
| POST | `/api/v1/accounts/{account_id}/contacts` | Create a contact |
| GET | `/api/v1/accounts/{account_id}/reports` | Retrieve reports for an account |
| POST | `/api/v1/accounts/{account_id}/automation_rules` | Create an automation rule |
| POST | `/api/v1/accounts/{account_id}/agent_bots` | Create an agent bot |

## Key resources

- **Conversations** — List, fetch, assign, label, and update conversation threads
- **Messages** — Send replies, attach private notes, and stream message history
- **Contacts** — Create, search, merge, and enrich customer contact records
- **Inboxes** — Provision and manage email, web, and messaging inboxes
- **Agents and Teams** — Manage agent accounts, team membership, and assignments
- **Reports** — Aggregate metrics on conversations, agents, and CSAT
- **Automation Rules** — Define rules that auto-assign, label, or route conversations
- **Agent Bots** — Register bot integrations that act on conversations

## Why Jentic

- **Setup:** Wiring Chatwoot by hand means handling its api_access_token header, picking which token type applies (user, agent bot, or platform app), and finding the right call among 144 endpoints. Through Jentic you install once, import Chatwoot from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** Chatwoot puts the account id in the URL path (`/api/v1/accounts/{account_id}/...`), so a rule can pin your agent to one account: it works within that account and nothing else. You choose the operations it may call, so creating automation rules or agent bots is not included unless you add it.
- **Credential handling:** Your Chatwoot api_access_token is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'reply to a conversation' or 'create a contact', and Jentic returns the matching Chatwoot operation with its input schema so the agent picks the right endpoint among 144 without browsing the reference docs.

## Related APIs

- **Chatsistant API** — AI chatbot platform that can pre-handle conversations before they hit a Chatwoot agent
- **Chatwork API** — Team chat platform with a different focus - internal collaboration rather than customer support
- **Checkly API** — Synthetic monitoring you can use to verify Chatwoot endpoints stay available

## FAQ

### Does Chatwoot publish an official OpenAPI spec?

Yes. Chatwoot is open source and publishes a machine-readable OpenAPI 3.1 description in its own repository at `swagger/swagger.json`, served from its GitHub repo at `https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/swagger.json`. That URL tracks the `develop` branch, so it moves with the product and is not a pinned release artifact; each release tag carries a snapshot of the same file. The specification on this page is derived from that file and validated before publication. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the Chatwoot API use?

Chatwoot uses an API key passed in the api_access_token header. Three token types are defined: user (full user permissions), agent bot (limited bot integrations), and platform app (provisioning accounts and users). Through Jentic, the right token is stored encrypted in your Jentic One instance and injected at execution time without entering the agent's context.

### Can I send replies to conversations with the Chatwoot API?

Yes. POST `/api/v1/accounts/{account_id}/conversations/{conversation_id}/messages` sends a reply or private note in a specific conversation. The endpoint accepts the message content, message type (incoming, outgoing, or private), and optional attachments.

### How do I create a contact via the Chatwoot API?

Use POST `/api/v1/accounts/{account_id}/contacts` with name, email, phone, and any custom attributes. The endpoint returns the created contact id, which you can then attach to inboxes or conversations.

### What are the rate limits for the Chatwoot API?

The OpenAPI specification does not declare formal rate limits. Self-hosted Chatwoot instances are bound by the host's configuration, and the cloud version applies plan-based throttling - check your dashboard or the Chatwoot docs for current limits and plan for retry-with-backoff on 429 responses.

### How do I post a reply to a Chatwoot conversation through Jentic?

Install the SDK with `pip install jentic`, then run Jentic.search('send a message in a conversation'), load the schema for `/api/v1/accounts/{account_id}/conversations/{conversation_id}/messages`, and execute with the conversation_id and message content. Jentic injects the api_access_token automatically.

### Can I limit what my agent is allowed to do with the Chatwoot API?

Yes. Because you run Jentic One yourself, your own rules decide which Chatwoot operations and credentials the agent may use. Since Chatwoot puts the account id in the URL path (`/api/v1/accounts/{account_id}/...`), you can pin the agent to a single account so it works within that account and nothing else. You also choose the specific operations it may call, so higher-risk actions like creating automation rules or agent bots are excluded unless you explicitly add them.