Chatwoot API 使用指南：跨渠道客户支持自动化与集成教程

chatwoot by vm0-ai/vm0-skills

75 周安装量

49 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/vm0-ai/vm0-skills --skill chatwoot

自动化客户支持 API

🇨🇳中文介绍

Chatwoot

通过直接使用 curl 调用 Chatwoot，跨多个渠道（网站、电子邮件、WhatsApp 等）管理客户支持。

官方文档：https://developers.chatwoot.com/api-reference/introduction

何时使用

在需要以下操作时使用此技能：

管理联系人 - 创建、搜索和更新客户资料
处理对话 - 创建、分配和跟踪支持对话
发送消息 - 回复客户或添加内部备注
列出客服人员 - 获取支持团队信息
自动化工作流 - 与 CRM、工单系统或通知系统集成

先决条件

设置 Chatwoot（云端或自托管）
登录并进入个人资料设置以获取您的 API 访问令牌
从 URL 中记下您的账户 ID（例如，/app/accounts/1/...）

export CHATWOOT_API_TOKEN="your-api-access-token"

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

API 类型	认证方式	使用场景
应用 API	用户访问令牌	客服/管理员自动化
客户端 API	收件箱标识符	自定义聊天界面
平台 API	平台应用令牌	多租户管理（仅限自托管）

3. 获取联系人详情

通过 ID 获取特定联系人。将 <contact-id> 替换为来自"搜索联系人"或"创建联系人"响应的实际联系人 ID：

curl -s -X GET "$(printenv CHATWOOT_BASE_URL)/api/v1/accounts/$(printenv CHATWOOT_ACCOUNT_ID)/contacts/<contact-id>" -H "api_access_token: $(printenv CHATWOOT_API_TOKEN)"

与联系人创建新对话：

写入 /tmp/chatwoot_request.json：

{
  "source_id": "api_conversation_123",
  "inbox_id": 1,
  "contact_id": 123,
  "status": "open",
  "message": {
    "content": "Hello! How can I help you today?"
  }
}

curl -s -X POST "$(printenv CHATWOOT_BASE_URL)/api/v1/accounts/$(printenv CHATWOOT_ACCOUNT_ID)/conversations" -H "api_access_token: $(printenv CHATWOOT_API_TOKEN)" -H "Content-Type: application/json" -d @/tmp/chatwoot_request.json

获取所有对话，支持可选过滤器：

# 列出打开的对话
curl -s -X GET "$(printenv CHATWOOT_BASE_URL)/api/v1/accounts/$(printenv CHATWOOT_ACCOUNT_ID)/conversations?status=open" -H "api_access_token: $(printenv CHATWOOT_API_TOKEN)" | jq '.data.payload[] | {id, status, contact: .meta.sender.name}'

6. 获取对话详情

获取特定对话的详情。将 <conversation-id> 替换为来自"列出对话"或"创建对话"响应的实际对话 ID：

curl -s -X GET "$(printenv CHATWOOT_BASE_URL)/api/v1/accounts/$(printenv CHATWOOT_ACCOUNT_ID)/conversations/<conversation-id>" -H "api_access_token: $(printenv CHATWOOT_API_TOKEN)"

在对话中发送消息。将 <conversation-id> 替换为来自"列出对话"响应的实际对话 ID：

写入 /tmp/chatwoot_request.json：

{
  "content": "Thank you for contacting us! Let me help you with that.",
  "message_type": "outgoing",
  "private": false
}

curl -s -X POST "$(printenv CHATWOOT_BASE_URL)/api/v1/accounts/$(printenv CHATWOOT_ACCOUNT_ID)/conversations/<conversation-id>/messages" -H "api_access_token: $(printenv CHATWOOT_API_TOKEN)" -H "Content-Type: application/json" -d @/tmp/chatwoot_request.json

8. 添加私有备注

添加内部备注（对客户不可见）。将 <conversation-id> 替换为来自"列出对话"响应的实际对话 ID：

写入 /tmp/chatwoot_request.json：

{
  "content": "Customer is a VIP - handle with priority",
  "message_type": "outgoing",
  "private": true
}

curl -s -X POST "$(printenv CHATWOOT_BASE_URL)/api/v1/accounts/$(printenv CHATWOOT_ACCOUNT_ID)/conversations/<conversation-id>/messages" -H "api_access_token: $(printenv CHATWOOT_API_TOKEN)" -H "Content-Type: application/json" -d @/tmp/chatwoot_request.json

将对话分配给客服人员。将 <conversation-id> 替换为实际对话 ID，将 <agent-id> 替换为来自"列出客服人员"响应的客服人员 ID：

写入 /tmp/chatwoot_request.json：

{
  "assignee_id": 1
}

curl -s -X POST "$(printenv CHATWOOT_BASE_URL)/api/v1/accounts/$(printenv CHATWOOT_ACCOUNT_ID)/conversations/<conversation-id>/assignments" -H "api_access_token: $(printenv CHATWOOT_API_TOKEN)" -H "Content-Type: application/json" -d @/tmp/chatwoot_request.json

10. 更新对话状态

更改对话状态（打开、已解决、待处理）。将 <conversation-id> 替换为来自"列出对话"响应的实际对话 ID：

写入 /tmp/chatwoot_request.json：

{
  "status": "resolved"
}

curl -s -X POST "$(printenv CHATWOOT_BASE_URL)/api/v1/accounts/$(printenv CHATWOOT_ACCOUNT_ID)/conversations/<conversation-id>/toggle_status" -H "api_access_token: $(printenv CHATWOOT_API_TOKEN)" -H "Content-Type: application/json" -d @/tmp/chatwoot_request.json

11. 列出客服人员

获取账户中的所有客服人员：

curl -s -X GET "$(printenv CHATWOOT_BASE_URL)/api/v1/accounts/$(printenv CHATWOOT_ACCOUNT_ID)/agents" -H "api_access_token: $(printenv CHATWOOT_API_TOKEN)" | jq '.[] | {id, name, email, role, availability_status}'

获取账户中的所有收件箱（渠道）：

curl -s -X GET "$(printenv CHATWOOT_BASE_URL)/api/v1/accounts/$(printenv CHATWOOT_ACCOUNT_ID)/inboxes" -H "api_access_token: $(printenv CHATWOOT_API_TOKEN)" | jq '.payload[] | {id, name, channel_type}'

13. 获取对话计数

获取按状态分类的计数，用于仪表板：

curl -s -X GET "$(printenv CHATWOOT_BASE_URL)/api/v1/accounts/$(printenv CHATWOOT_ACCOUNT_ID)/conversations/meta" -H "api_access_token: $(printenv CHATWOOT_API_TOKEN)" | jq '.meta.all_count, .meta.mine_count'

状态	描述
`open`	活跃对话
`resolved`	已关闭/已完成
`pending`	等待回复
`snoozed`	暂时暂停

类型	值	描述
发送	`outgoing`	客服人员发送给客户
接收	`incoming`	客户发送给客服人员
私有	`private: true`	内部备注（对客户不可见）

字段	描述
`id`	联系人 ID
`name`	联系人姓名
`email`	电子邮件地址
`phone_number`	电话号码
`identifier`	外部系统 ID
`custom_attributes`	自定义字段

字段	描述
`id`	对话 ID
`inbox_id`	渠道/收件箱 ID
`status`	当前状态
`assignee`	分配的客服人员
`contact`	客户信息

字段	描述
`id`	消息 ID
`content`	消息文本
`message_type`	接收/发送
`private`	是否为内部备注
`status`	已发送/已送达/已读/失败

从个人资料设置获取 API 令牌：登录 Chatwoot → 个人资料 → 访问令牌
账户 ID 在 URL 中：查看浏览器中的 /app/accounts/{id}/...
需要收件箱 ID：首先使用列出收件箱端点获取收件箱 ID
对话使用 source_id：通过 API 创建对话时需要
私有消息：设置 private: true 用于内部备注
自托管：将 CHATWOOT_BASE_URL 更改为您的实例 URL
推荐使用 Webhook：使用 Webhook 进行实时更新，而不是轮询

🇺🇸English

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

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

Prerequisites

Set up Chatwoot (Cloud or Self-hosted)
Log in and go to Profile Settings to get your API access token
Note your Account ID from the URL (e.g., /app/accounts/1/...)

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

API Types

API Type	Auth	Use Case
Application API	User access_token	Agent/admin automation
Client API	inbox_identifier	Custom chat interfaces
Platform API	Platform App token	Multi-tenant management (self-hosted only)

How to Use

All examples use the Application API with user access token.

1. Create a Contact

Create a new contact in your account:

Write to /tmp/chatwoot_request.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:

curl -s -X POST "$(printenv CHATWOOT_BASE_URL)/api/v1/accounts/$(printenv CHATWOOT_ACCOUNT_ID)/contacts" -H "api_access_token: $(printenv CHATWOOT_API_TOKEN)" -H "Content-Type: application/json" -d @/tmp/chatwoot_request.json

2. Search Contacts

Search contacts by email, phone, or name:

curl -s -X GET "$(printenv CHATWOOT_BASE_URL)/api/v1/accounts/$(printenv CHATWOOT_ACCOUNT_ID)/contacts/search?q=john@example.com" -H "api_access_token: $(printenv CHATWOOT_API_TOKEN)" | jq '.payload[] | {id, name, email}'

3. Get Contact Details

Get a specific contact by ID. Replace <contact-id> with the actual contact ID from the "Search Contacts" or "Create a Contact" response:

curl -s -X GET "$(printenv CHATWOOT_BASE_URL)/api/v1/accounts/$(printenv CHATWOOT_ACCOUNT_ID)/contacts/<contact-id>" -H "api_access_token: $(printenv CHATWOOT_API_TOKEN)"

4. Create a Conversation

Create a new conversation with a contact:

Write to /tmp/chatwoot_request.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:

curl -s -X POST "$(printenv CHATWOOT_BASE_URL)/api/v1/accounts/$(printenv CHATWOOT_ACCOUNT_ID)/conversations" -H "api_access_token: $(printenv CHATWOOT_API_TOKEN)" -H "Content-Type: application/json" -d @/tmp/chatwoot_request.json

5. List Conversations

Get all conversations with optional filters:

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

6. Get Conversation Details

Get details of a specific conversation. Replace <conversation-id> with the actual conversation ID from the "List Conversations" or "Create a Conversation" response:

curl -s -X GET "$(printenv CHATWOOT_BASE_URL)/api/v1/accounts/$(printenv CHATWOOT_ACCOUNT_ID)/conversations/<conversation-id>" -H "api_access_token: $(printenv CHATWOOT_API_TOKEN)"

7. Send a Message

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:

{
  "content": "Thank you for contacting us! Let me help you with that.",
  "message_type": "outgoing",
  "private": false
}

Then run:

curl -s -X POST "$(printenv CHATWOOT_BASE_URL)/api/v1/accounts/$(printenv CHATWOOT_ACCOUNT_ID)/conversations/<conversation-id>/messages" -H "api_access_token: $(printenv CHATWOOT_API_TOKEN)" -H "Content-Type: application/json" -d @/tmp/chatwoot_request.json

8. Add Private Note

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:

{
  "content": "Customer is a VIP - handle with priority",
  "message_type": "outgoing",
  "private": true
}

Then run:

curl -s -X POST "$(printenv CHATWOOT_BASE_URL)/api/v1/accounts/$(printenv CHATWOOT_ACCOUNT_ID)/conversations/<conversation-id>/messages" -H "api_access_token: $(printenv CHATWOOT_API_TOKEN)" -H "Content-Type: application/json" -d @/tmp/chatwoot_request.json

9. Assign Conversation

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:

{
  "assignee_id": 1
}

Then run:

curl -s -X POST "$(printenv CHATWOOT_BASE_URL)/api/v1/accounts/$(printenv CHATWOOT_ACCOUNT_ID)/conversations/<conversation-id>/assignments" -H "api_access_token: $(printenv CHATWOOT_API_TOKEN)" -H "Content-Type: application/json" -d @/tmp/chatwoot_request.json

10. Update Conversation Status

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:

{
  "status": "resolved"
}

Then run:

curl -s -X POST "$(printenv CHATWOOT_BASE_URL)/api/v1/accounts/$(printenv CHATWOOT_ACCOUNT_ID)/conversations/<conversation-id>/toggle_status" -H "api_access_token: $(printenv CHATWOOT_API_TOKEN)" -H "Content-Type: application/json" -d @/tmp/chatwoot_request.json

11. List Agents

Get all agents in the account:

curl -s -X GET "$(printenv CHATWOOT_BASE_URL)/api/v1/accounts/$(printenv CHATWOOT_ACCOUNT_ID)/agents" -H "api_access_token: $(printenv CHATWOOT_API_TOKEN)" | jq '.[] | {id, name, email, role, availability_status}'

12. List Inboxes

Get all inboxes (channels) in the account:

curl -s -X GET "$(printenv CHATWOOT_BASE_URL)/api/v1/accounts/$(printenv CHATWOOT_ACCOUNT_ID)/inboxes" -H "api_access_token: $(printenv CHATWOOT_API_TOKEN)" | jq '.payload[] | {id, name, channel_type}'

13. Get Conversation Counts

Get counts by status for dashboard:

curl -s -X GET "$(printenv CHATWOOT_BASE_URL)/api/v1/accounts/$(printenv CHATWOOT_ACCOUNT_ID)/conversations/meta" -H "api_access_token: $(printenv CHATWOOT_API_TOKEN)" | jq '.meta.all_count, .meta.mine_count'

Conversation Status

Status	Description
`open`	Active conversation
`resolved`	Closed/completed
`pending`	Waiting for response
`snoozed`	Temporarily paused

Message Types

Type	Value	Description
Outgoing	`outgoing`	Agent to customer
Incoming	`incoming`	Customer to agent
Private	`private: true`	Internal note (not visible to customer)

Response Fields

Contact

Field	Description
`id`	Contact ID
`name`	Contact name
`email`	Email address
`phone_number`	Phone number
`identifier`	External system ID
`custom_attributes`	Custom fields

Conversation

Field	Description
`id`	Conversation ID
`inbox_id`	Channel/inbox ID
`status`	Current status
`assignee`	Assigned agent
`contact`	Customer info

Message

Field	Description
`id`	Message ID
`content`	Message text
`message_type`	incoming/outgoing
`private`	Is internal note
`status`	sent/delivered/read/failed

Guidelines

Get API token from Profile Settings : Log into Chatwoot → Profile → Access Token
Account ID is in URL : Look at /app/accounts/{id}/... in your browser
Inbox ID is required : Get inbox IDs first with the list inboxes endpoint
Use source_id for conversations : Required to create conversations via API
Private messages : Set private: true for internal notes
Self-hosted : Change CHATWOOT_BASE_URL to your instance URL
Webhooks recommended : Use webhooks for real-time updates instead of polling

Weekly Installs

Repository

vm0-ai/vm0-skills

GitHub Stars

First Seen

Jan 24, 2026

Security Audits

Gen Agent Trust HubWarn SocketWarn SnykWarn

Installed on

gemini-cli66

opencode64

codex63

github-copilot62

amp60

kimi-cli59

通过 LiteLLM 代理让 Claude Code 对接 GitHub Copilot 运行 | 高级变通方案指南

44,900 周安装

Chatwoot API 使用指南：跨渠道客户支持自动化与集成教程

🇨🇳中文介绍

Chatwoot

何时使用

先决条件

相关 Skills

API 类型

使用方法

1. 创建联系人

2. 搜索联系人

3. 获取联系人详情

4. 创建对话

5. 列出对话

6. 获取对话详情

7. 发送消息

8. 添加私有备注

9. 分配对话

10. 更新对话状态

11. 列出客服人员

12. 列出收件箱

13. 获取对话计数

对话状态

消息类型

响应字段

联系人

对话

消息

指南

🇺🇸English

Chatwoot

When to Use

Prerequisites

API Types

How to Use

1. Create a Contact

2. Search Contacts

3. Get Contact Details

4. Create a Conversation

5. List Conversations

6. Get Conversation Details

7. Send a Message

8. Add Private Note

9. Assign Conversation

10. Update Conversation Status

11. List Agents

12. List Inboxes

13. Get Conversation Counts

Conversation Status

Message Types

Response Fields

Contact

Conversation

Message

Guidelines

最新 Skills