Back to Details

chatwoot

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Chatwoot

Chatwoot

Use Chatwoot via direct 
curl
calls to manage customer support across multiple channels (website, email, WhatsApp, etc.).
Official docs: 
https://developers.chatwoot.com/api-reference/introduction
通过直接调用
curl
来使用Chatwoot，实现跨多渠道（网站、邮件、WhatsApp等）的客户支持管理。
官方文档：
https://developers.chatwoot.com/api-reference/introduction

When to Use

使用场景

Use this skill when you need to:
  • Manage contacts - create, search, and update customer profiles
  • Handle conversations - create, assign, and track support conversations
  • Send messages - reply to customers or add internal notes
  • List agents - get support team information
  • Automate workflows - integrate with CRM, ticketing, or notification systems
当你需要以下操作时，可使用该技能：
  • 管理联系人 - 创建、搜索和更新客户资料
  • 处理对话 - 创建、分配和跟踪支持对话
  • 发送消息 - 回复客户或添加内部备注
  • 列出客服人员 - 获取支持团队信息
  • 自动化工作流 - 与CRM、工单系统或通知系统集成

Prerequisites

前置条件

  1. Set up Chatwoot (Cloud or Self-hosted)
  2. Log in and go to Profile Settings to get your API access token
  3. Note your Account ID from the URL (e.g., 
    /app/accounts/1/...
    )
bash
export CHATWOOT_API_TOKEN="your-api-access-token"
export CHATWOOT_ACCOUNT_ID="1"
export CHATWOOT_BASE_URL="https://app.chatwoot.com" # or your self-hosted URL
  1. 搭建Chatwoot（云端或自托管版本）
  2. 登录后进入个人资料设置获取API访问令牌
  3. 从URL中记录你的账户ID（例如：
    /app/accounts/1/...
    ）
bash
export CHATWOOT_API_TOKEN="your-api-access-token"
export CHATWOOT_ACCOUNT_ID="1"
export CHATWOOT_BASE_URL="https://app.chatwoot.com" # 或你的自托管URL

API Types

API类型

API TypeAuthUse Case
Application APIUser access_tokenAgent/admin automation
Client APIinbox_identifierCustom chat interfaces
Platform APIPlatform App tokenMulti-tenant management (self-hosted only)
Important: When using 
$VAR
in a command that pipes to another command, wrap the command containing 
$VAR
in 
bash -c '...'
. Due to a Claude Code bug, environment variables are silently cleared when pipes are used directly.
bash
bash -c 'curl -s "https://api.example.com" -H "Authorization: Bearer $API_KEY"' | jq .
API类型认证方式使用场景
Application API用户access_token客服/管理员自动化
Client APIinbox_identifier自定义聊天界面
Platform APIPlatform App token多租户管理（仅自托管版本可用）
重要提示： 当在包含管道的命令中使用
$VAR
时，请将包含
$VAR
的命令用
bash -c '...'
包裹。由于Claude Code的bug，直接使用管道时环境变量会被静默清除。
bash
bash -c 'curl -s "https://api.example.com" -H "Authorization: Bearer $API_KEY"' | jq .

How to Use

使用方法

All examples use the Application API with user access token.
所有示例均使用Application API及用户访问令牌。

1. Create a Contact

1. 创建联系人

Create a new contact in your account:
Write to 
/tmp/chatwoot_request.json
:
json
{
  "inbox_id": 1,
  "name": "John Doe",
  "email": "john@example.com",
  "phone_number": "+1234567890",
  "identifier": "customer_123",
  "additional_attributes": {
    "company": "Acme Inc",
    "plan": "premium"
  }
}
Then run:
bash
bash -c 'curl -s -X POST "${CHATWOOT_BASE_URL}/api/v1/accounts/${CHATWOOT_ACCOUNT_ID}/contacts" -H "api_access_token: ${CHATWOOT_API_TOKEN}" -H "Content-Type: application/json" -d @/tmp/chatwoot_request.json'
在账户中创建新联系人：
写入
/tmp/chatwoot_request.json
：
json
{
  "inbox_id": 1,
  "name": "John Doe",
  "email": "john@example.com",
  "phone_number": "+1234567890",
  "identifier": "customer_123",
  "additional_attributes": {
    "company": "Acme Inc",
    "plan": "premium"
  }
}
然后运行：
bash
bash -c 'curl -s -X POST "${CHATWOOT_BASE_URL}/api/v1/accounts/${CHATWOOT_ACCOUNT_ID}/contacts" -H "api_access_token: ${CHATWOOT_API_TOKEN}" -H "Content-Type: application/json" -d @/tmp/chatwoot_request.json'

2. Search Contacts

2. 搜索联系人

Search contacts by email, phone, or name:
bash
bash -c 'curl -s -X GET "${CHATWOOT_BASE_URL}/api/v1/accounts/${CHATWOOT_ACCOUNT_ID}/contacts/search?q=john@example.com" -H "api_access_token: ${CHATWOOT_API_TOKEN}"' | jq '.payload[] | {id, name, email}'
通过邮箱、电话或姓名搜索联系人：
bash
bash -c 'curl -s -X GET "${CHATWOOT_BASE_URL}/api/v1/accounts/${CHATWOOT_ACCOUNT_ID}/contacts/search?q=john@example.com" -H "api_access_token: ${CHATWOOT_API_TOKEN}"' | jq '.payload[] | {id, name, email}'

3. Get Contact Details

3. 获取联系人详情

Get a specific contact by ID. Replace 
<contact-id>
with the actual contact ID from the "Search Contacts" or "Create a Contact" response:
bash
bash -c 'curl -s -X GET "${CHATWOOT_BASE_URL}/api/v1/accounts/${CHATWOOT_ACCOUNT_ID}/contacts/<contact-id>" -H "api_access_token: ${CHATWOOT_API_TOKEN}"'
通过ID获取特定联系人的详情。将
<contact-id>
替换为“搜索联系人”或“创建联系人”响应中的实际联系人ID：
bash
bash -c 'curl -s -X GET "${CHATWOOT_BASE_URL}/api/v1/accounts/${CHATWOOT_ACCOUNT_ID}/contacts/<contact-id>" -H "api_access_token: ${CHATWOOT_API_TOKEN}"'

4. Create a Conversation

4. 创建对话

Create a new conversation with a contact:
Write to 
/tmp/chatwoot_request.json
:
json
{
  "source_id": "api_conversation_123",
  "inbox_id": 1,
  "contact_id": 123,
  "status": "open",
  "message": {
    "content": "Hello! How can I help you today?"
  }
}
Then run:
bash
bash -c 'curl -s -X POST "${CHATWOOT_BASE_URL}/api/v1/accounts/${CHATWOOT_ACCOUNT_ID}/conversations" -H "api_access_token: ${CHATWOOT_API_TOKEN}" -H "Content-Type: application/json" -d @/tmp/chatwoot_request.json'
与联系人创建新对话：
写入
/tmp/chatwoot_request.json
：
json
{
  "source_id": "api_conversation_123",
  "inbox_id": 1,
  "contact_id": 123,
  "status": "open",
  "message": {
    "content": "Hello! How can I help you today?"
  }
}
然后运行：
bash
bash -c 'curl -s -X POST "${CHATWOOT_BASE_URL}/api/v1/accounts/${CHATWOOT_ACCOUNT_ID}/conversations" -H "api_access_token: ${CHATWOOT_API_TOKEN}" -H "Content-Type: application/json" -d @/tmp/chatwoot_request.json'

5. List Conversations

5. 列出对话

Get all conversations with optional filters:
bash
undefined
获取所有对话，可添加可选筛选条件：
bash
undefined

List open conversations

列出未关闭的对话

bash -c 'curl -s -X GET "${CHATWOOT_BASE_URL}/api/v1/accounts/${CHATWOOT_ACCOUNT_ID}/conversations?status=open" -H "api_access_token: ${CHATWOOT_API_TOKEN}"' | jq '.data.payload[] | {id, status, contact: .meta.sender.name}'

---
bash -c 'curl -s -X GET "${CHATWOOT_BASE_URL}/api/v1/accounts/${CHATWOOT_ACCOUNT_ID}/conversations?status=open" -H "api_access_token: ${CHATWOOT_API_TOKEN}"' | jq '.data.payload[] | {id, status, contact: .meta.sender.name}'

---

6. Get Conversation Details

6. 获取对话详情

Get details of a specific conversation. Replace 
<conversation-id>
with the actual conversation ID from the "List Conversations" or "Create a Conversation" response:
bash
bash -c 'curl -s -X GET "${CHATWOOT_BASE_URL}/api/v1/accounts/${CHATWOOT_ACCOUNT_ID}/conversations/<conversation-id>" -H "api_access_token: ${CHATWOOT_API_TOKEN}"'
获取特定对话的详情。将
<conversation-id>
替换为“列出对话”或“创建对话”响应中的实际对话ID：
bash
bash -c 'curl -s -X GET "${CHATWOOT_BASE_URL}/api/v1/accounts/${CHATWOOT_ACCOUNT_ID}/conversations/<conversation-id>" -H "api_access_token: ${CHATWOOT_API_TOKEN}"'

7. Send a Message

7. 发送消息

Send a message in a conversation. Replace 
<conversation-id>
with the actual conversation ID from the "List Conversations" response:
Write to 
/tmp/chatwoot_request.json
:
json
{
  "content": "Thank you for contacting us! Let me help you with that.",
  "message_type": "outgoing",
  "private": false
}
Then run:
bash
bash -c 'curl -s -X POST "${CHATWOOT_BASE_URL}/api/v1/accounts/${CHATWOOT_ACCOUNT_ID}/conversations/<conversation-id>/messages" -H "api_access_token: ${CHATWOOT_API_TOKEN}" -H "Content-Type: application/json" -d @/tmp/chatwoot_request.json'
在对话中发送消息。将
<conversation-id>
替换为“列出对话”响应中的实际对话ID：
写入
/tmp/chatwoot_request.json
：
json
{
  "content": "Thank you for contacting us! Let me help you with that.",
  "message_type": "outgoing",
  "private": false
}
然后运行：
bash
bash -c 'curl -s -X POST "${CHATWOOT_BASE_URL}/api/v1/accounts/${CHATWOOT_ACCOUNT_ID}/conversations/<conversation-id>/messages" -H "api_access_token: ${CHATWOOT_API_TOKEN}" -H "Content-Type: application/json" -d @/tmp/chatwoot_request.json'

8. Add Private Note

8. 添加私人备注

Add an internal note (not visible to customer). Replace 
<conversation-id>
with the actual conversation ID from the "List Conversations" response:
Write to 
/tmp/chatwoot_request.json
:
json
{
  "content": "Customer is a VIP - handle with priority",
  "message_type": "outgoing",
  "private": true
}
Then run:
bash
bash -c 'curl -s -X POST "${CHATWOOT_BASE_URL}/api/v1/accounts/${CHATWOOT_ACCOUNT_ID}/conversations/<conversation-id>/messages" -H "api_access_token: ${CHATWOOT_API_TOKEN}" -H "Content-Type: application/json" -d @/tmp/chatwoot_request.json'
添加内部备注（对客户不可见）。将
<conversation-id>
替换为“列出对话”响应中的实际对话ID：
写入
/tmp/chatwoot_request.json
：
json
{
  "content": "Customer is a VIP - handle with priority",
  "message_type": "outgoing",
  "private": true
}
然后运行：
bash
bash -c 'curl -s -X POST "${CHATWOOT_BASE_URL}/api/v1/accounts/${CHATWOOT_ACCOUNT_ID}/conversations/<conversation-id>/messages" -H "api_access_token: ${CHATWOOT_API_TOKEN}" -H "Content-Type: application/json" -d @/tmp/chatwoot_request.json'

9. Assign Conversation

9. 分配对话

Assign a conversation to an agent. Replace 
<conversation-id>
with the actual conversation ID and 
<agent-id>
with the agent ID from the "List Agents" response:
Write to 
/tmp/chatwoot_request.json
:
json
{
  "assignee_id": 1
}
Then run:
bash
bash -c 'curl -s -X POST "${CHATWOOT_BASE_URL}/api/v1/accounts/${CHATWOOT_ACCOUNT_ID}/conversations/<conversation-id>/assignments" -H "api_access_token: ${CHATWOOT_API_TOKEN}" -H "Content-Type: application/json" -d @/tmp/chatwoot_request.json'
将对话分配给客服人员。将
<conversation-id>
替换为实际对话ID，
<agent-id>
替换为“列出客服人员”响应中的客服ID：
写入
/tmp/chatwoot_request.json
：
json
{
  "assignee_id": 1
}
然后运行：
bash
bash -c 'curl -s -X POST "${CHATWOOT_BASE_URL}/api/v1/accounts/${CHATWOOT_ACCOUNT_ID}/conversations/<conversation-id>/assignments" -H "api_access_token: ${CHATWOOT_API_TOKEN}" -H "Content-Type: application/json" -d @/tmp/chatwoot_request.json'

10. Update Conversation Status

10. 更新对话状态

Change conversation status (open, resolved, pending). Replace 
<conversation-id>
with the actual conversation ID from the "List Conversations" response:
Write to 
/tmp/chatwoot_request.json
:
json
{
  "status": "resolved"
}
Then run:
bash
bash -c 'curl -s -X POST "${CHATWOOT_BASE_URL}/api/v1/accounts/${CHATWOOT_ACCOUNT_ID}/conversations/<conversation-id>/toggle_status" -H "api_access_token: ${CHATWOOT_API_TOKEN}" -H "Content-Type: application/json" -d @/tmp/chatwoot_request.json'
更改对话状态（open、resolved、pending）。将
<conversation-id>
替换为“列出对话”响应中的实际对话ID：
写入
/tmp/chatwoot_request.json
：
json
{
  "status": "resolved"
}
然后运行：
bash
bash -c 'curl -s -X POST "${CHATWOOT_BASE_URL}/api/v1/accounts/${CHATWOOT_ACCOUNT_ID}/conversations/<conversation-id>/toggle_status" -H "api_access_token: ${CHATWOOT_API_TOKEN}" -H "Content-Type: application/json" -d @/tmp/chatwoot_request.json'

11. List Agents

11. 列出客服人员

Get all agents in the account:
bash
bash -c 'curl -s -X GET "${CHATWOOT_BASE_URL}/api/v1/accounts/${CHATWOOT_ACCOUNT_ID}/agents" -H "api_access_token: ${CHATWOOT_API_TOKEN}"' | jq '.[] | {id, name, email, role, availability_status}'
获取账户中的所有客服人员：
bash
bash -c 'curl -s -X GET "${CHATWOOT_BASE_URL}/api/v1/accounts/${CHATWOOT_ACCOUNT_ID}/agents" -H "api_access_token: ${CHATWOOT_API_TOKEN}"' | jq '.[] | {id, name, email, role, availability_status}'

12. List Inboxes

12. 列出收件箱

Get all inboxes (channels) in the account:
bash
bash -c 'curl -s -X GET "${CHATWOOT_BASE_URL}/api/v1/accounts/${CHATWOOT_ACCOUNT_ID}/inboxes" -H "api_access_token: ${CHATWOOT_API_TOKEN}"' | jq '.payload[] | {id, name, channel_type}'
获取账户中的所有收件箱（渠道）：
bash
bash -c 'curl -s -X GET "${CHATWOOT_BASE_URL}/api/v1/accounts/${CHATWOOT_ACCOUNT_ID}/inboxes" -H "api_access_token: ${CHATWOOT_API_TOKEN}"' | jq '.payload[] | {id, name, channel_type}'

13. Get Conversation Counts

13. 获取对话统计

Get counts by status for dashboard:
bash
bash -c 'curl -s -X GET "${CHATWOOT_BASE_URL}/api/v1/accounts/${CHATWOOT_ACCOUNT_ID}/conversations/meta" -H "api_access_token: ${CHATWOOT_API_TOKEN}"' | jq '.meta.all_count, .meta.mine_count'
按状态获取对话数量，用于仪表盘展示：
bash
bash -c 'curl -s -X GET "${CHATWOOT_BASE_URL}/api/v1/accounts/${CHATWOOT_ACCOUNT_ID}/conversations/meta" -H "api_access_token: ${CHATWOOT_API_TOKEN}"' | jq '.meta.all_count, .meta.mine_count'

Conversation Status

对话状态

StatusDescription
open
Active conversation
resolved
Closed/completed
pending
Waiting for response
snoozed
Temporarily paused
状态描述
open
活跃对话
resolved
已关闭/已完成
pending
等待回复
snoozed
暂时暂停

Message Types

消息类型

TypeValueDescription
Outgoing
outgoing
Agent to customer
Incoming
incoming
Customer to agent
Private
private: true
Internal note (not visible to customer)
类型值描述
Outgoing
outgoing
客服发送给客户
Incoming
incoming
客户发送给客服
私人消息
private: true
内部备注（对客户不可见）

Response Fields

响应字段

Contact

联系人

FieldDescription
id
Contact ID
name
Contact name
email
Email address
phone_number
Phone number
identifier
External system ID
custom_attributes
Custom fields
字段描述
id
联系人ID
name
联系人姓名
email
邮箱地址
phone_number
电话号码
identifier
外部系统ID
custom_attributes
自定义字段

Conversation

对话

FieldDescription
id
Conversation ID
inbox_id
Channel/inbox ID
status
Current status
assignee
Assigned agent
contact
Customer info
字段描述
id
对话ID
inbox_id
渠道/收件箱ID
status
当前状态
assignee
被分配的客服
contact
客户信息

Message

消息

FieldDescription
id
Message ID
content
Message text
message_type
incoming/outgoing
private
Is internal note
status
sent/delivered/read/failed
字段描述
id
消息ID
content
消息文本
message_type
incoming/outgoing
private
是否为内部备注
status
sent/delivered/read/failed

Guidelines

注意事项

  1. Get API token from Profile Settings: Log into Chatwoot → Profile → Access Token
  2. Account ID is in URL: Look at 
    /app/accounts/{id}/...
    in your browser
  3. Inbox ID is required: Get inbox IDs first with the list inboxes endpoint
  4. Use source_id for conversations: Required to create conversations via API
  5. Private messages: Set 
    private: true
    for internal notes
  6. Self-hosted: Change 
    CHATWOOT_BASE_URL
    to your instance URL
  7. Webhooks recommended: Use webhooks for real-time updates instead of polling
  1. 从个人资料设置获取API令牌：登录Chatwoot → 个人资料 → 访问令牌
  2. 账户ID位于URL中：在浏览器中查看
    /app/accounts/{id}/...
    路径
  3. 需要收件箱ID：先通过列出收件箱的接口获取收件箱ID
  4. 对话需使用source_id：通过API创建对话时必须提供source_id
  5. 私人消息：设置
    private: true
    来创建内部备注
  6. 自托管版本：将
    CHATWOOT_BASE_URL
    改为你的实例地址
  7. 推荐使用Webhooks：使用Webhooks获取实时更新，而非轮询