Package Information
Downloads: 2 weekly / 38 monthly
Latest Version: 1.0.1
Author: Dave Ang
Documentation
n8n-nodes-chatwoot-zh
这是一个 Chatwoot 的 n8n 社区节点汉化定制版。基于 fazer.ai 的开源代码进行了深度中文化优化，旨在为中文用户提供更友好的自动化体验。
Chatwoot 是一个开源的客户互动平台，帮助企业管理跨多个渠道的客户对话。此节点提供了与 Chatwoot API 的全面集成，允许你自动化客户支持工作流、管理联系人、处理对话等。
[!TIP]
此版本包含了增强功能，如看板面板 (Kanban Boards)、基于 Baileys/Z-API 供应商的 WhatsApp 集成，以及更多的 Webhook 事件触发。
安装 | 节点说明 | 功能操作 | 凭据配置 | 开发相关
安装
按照 n8n 社区节点文档中的 安装指南 进行操作。
在 n8n 的社区节点安装界面输入以下包名：
n8n-nodes-chatwoot-zh
节点说明
此软件包包含两个节点：
- Chatwoot fazer.ai (汉化版)：用于与 Chatwoot API 交互的主节点，支持所有的增删改查操作。
- Chatwoot fazer.ai 触发器 (汉化版)：Webhook 触发器节点，用于实时监听 Chatwoot 事件并启动工作流。
功能操作 (核心概览)
常用模块
- 账户 (Account)：获取特定账户详细信息。
- 联系人 (Contact)：创建、获取、更新、删除、搜索联系人，以及管理自定义属性。
- 对话 (Conversation)：发送文本/文件消息、发送 WhatsApp 模板、分配客服、修改状态、设置优先级、模拟输入状态等。
- 看板 (Kanban) ⚡：创建看板面板、管理阶段（列）、移动任务卡片。
- 收件箱 (Inbox)：管理渠道，支持 WhatsApp 专属功能（扫码连接、断开连接等）。
凭据配置
要进行身份验证，你需要：
- Chatwoot API 地址：你的 Chatwoot 实例 URL（例如
https://app.chatwoot.com）。 - 访问令牌 (Access Token)：在 Chatwoot 个人设置页面的最下方获取。
开发与维护
项目设置
# 克隆你自己的仓库
git clone [https://github.com/DaveAng008/n8n-nodes-chatwoot-zh.git](https://github.com/DaveAng008/n8n-nodes-chatwoot-zh.git)
cd n8n-nodes-chatwoot-zh
# 安装依赖
pnpm install
# 编译代码
pnpm build
Chatwoot 触发器 (Trigger)
一个 Webhook 触发器节点，用于监听 Chatwoot 事件。会自动在你的 Chatwoot 实例中注册和管理 Webhook。
操作
账户 (Account)
| 操作 (Operation) | 描述 (Description) |
|---|---|
| 获取详情 (Get) | 检索特定 Chatwoot 账户的详细信息 |
联系人 (Contact)
| 操作 (Operation) | 描述 (Description) |
|---|---|
| 创建联系人 (Create) | 创建一个包含姓名、电话（E.164 格式）、邮箱和自定义属性的新联系人 |
| 获取 (Get) | 获取联系人信息 |
| 更新 (Update) | 更新联系人详情 |
| 删除 (Delete) | 删除一个联系人 |
| 列表 (List) | 分页列出所有联系人 |
| 搜索 (Search) | 通过关键词搜索联系人 |
| 设置自定义属性 (Set Custom Attributes) | 在联系人上设置自定义属性 |
| 清除自定义属性 (Destroy Custom Attributes) | 移除联系人的所有自定义属性 |
对话 (Conversation)
| 操作 (Operation) | 描述 (Description) |
|---|---|
| 创建对话 (Create) | 为联系人创建一个新对话 |
| 获取 (Get) | 获取特定的对话详情 |
| 列表 (List) | 通过筛选条件列出对话 |
| 发送文本消息 (Send Message) | 在对话中发送一条文本消息 |
| 发送文件/图片 (Send File) | 在对话中发送文件/附件消息 |
| 获取消息列表 (List Messages) | 分页列出对话中的消息记录 |
| 获取附件列表 (List Attachments) | 列出对话中的所有附件 |
| 分配给客服 (Assign Agent) | 将客服人员分配给对话 |
| 分配给团队 (Assign Team) | 将团队分配给对话 |
| 追加标签 (Add Labels) | 为对话追加标签（保留现有标签） |
| 移除标签 (Remove Labels) | 从对话中移除特定的标签 |
| 更新标签 (Update Labels) | 替换对话的所有标签 |
| 切换状态 (Toggle Status) | 更改对话状态（开启、待办、解决、延后） |
| 设置优先级 (Set Priority) | 设置对话的优先级 |
| 追加自定义属性 (Add Custom Attributes) | 追加自定义属性（保留现有属性） |
| 移除自定义属性 (Remove Custom Attributes) | 移除特定的自定义属性 |
| 重置自定义属性 (Set Custom Attributes) | 替换现有的所有自定义属性 |
| 更新最后阅读时间 (Update Last Seen) | 更新对话的最后阅读时间戳 |
| 更新在线/输入状态 (Update Presence) | 设置输入状态（关闭、正在输入、正在录音） |
| 标记为未读 (Mark Unread) | 将对话标记为未读 |
| 更新附件元数据 (Update Attachment Metadata) | 更新附件的元数据（例如：语音转录文本） |
自定义属性定义 (Custom Attribute)
| 操作 (Operation) | 描述 (Description) |
|---|---|
| 创建定义 (Create) | 创建自定义属性定义（文本、数字、日期、列表、复选框、链接） |
| 列表 (List) | 列出所有自定义属性定义 |
| 删除 (Delete) | 删除一个自定义属性定义 |
收件箱/渠道 (Inbox)
| 操作 (Operation) | 描述 (Description) |
|---|---|
| 获取详情 (Get) | 获取特定收件箱的信息 |
| 列表 (List) | 列出账户中的所有收件箱 |
| 检查 WhatsApp 注册 (On WhatsApp) ? | 检查手机号是否注册了 WhatsApp |
| 断开 WhatsApp 连接 (WhatsApp Disconnect) ? | 断开 WhatsApp 收件箱的连接 |
| 获取登录二维码 (WhatsApp Get QR Code) ? | 获取用于连接 WhatsApp 的二维码 |
? 这些操作仅在 fazer.ai 的 Chatwoot 版本 中可用。
看板面板 (Kanban Board) ?
| 操作 (Operation) | 描述 (Description) |
|---|---|
| 创建 (Create) | 创建一个新的看板面板 |
| 获取 (Get) | 获取特定的看板面板详情 |
| 列表 (List) | 列出所有看板面板 |
| 更新 (Update) | 更新看板面板信息 |
| 删除 (Delete) | 删除一个看板面板 |
| 更新客服人员 (Update Agents) | 更新分配到看板的客服人员 |
| 更新收件箱 (Update Inboxes) | 更新链接到看板的收件箱 |
看板阶段 (Kanban Step) ?
| 操作 (Operation) | 描述 (Description) |
|---|---|
| 创建 (Create) | 在看板中创建一个新阶段（列） |
| 列表 (List) | 列出看板中的所有阶段 |
| 更新 (Update) | 更新阶段信息 |
| 删除 (Delete) | 删除一个阶段 |
看板任务 (Kanban Task) ?
| 操作 (Operation) | 描述 (Description) |
|---|---|
| 创建 (Create) | 创建一个新任务 |
| 获取 (Get) | 获取特定的任务详情 |
| 列表 (List) | 列出看板中的所有任务 |
| 更新 (Update) | 更新任务信息 |
| 移动 (Move) | 将任务移动到另一个阶段/位置 |
| 删除 (Delete) | 删除一个任务 |
标签 (Label)
| 操作 (Operation) | 描述 (Description) |
|---|---|
| 创建 (Create) | 创建一个新标签 |
| 列表 (List) | 列出所有标签 |
| 更新 (Update) | 更新标签信息 |
| 删除 (Delete) | 删除一个标签 |
个人资料 (Profile)
| 操作 (Operation) | 描述 (Description) |
|---|---|
| 获取详情 (Get) | 获取当前用户的个人资料信息 |
定时消息 (Scheduled Message)
| 操作 (Operation) | 描述 (Description) |
|---|---|
| 创建 (Create) | 在对话中创建一条新的定时消息 |
| 获取多个 (Get Many) | 列出对话中的所有定时消息 |
| 更新 (Update) | 更新现有的定时消息 |
| 删除 (Delete) | 删除一条定时消息 |
团队 (Team)
| 操作 (Operation) | 描述 (Description) |
|---|---|
| 创建 (Create) | 创建一个新团队 |
| 删除 (Delete) | 删除一个团队 |
| 列表 (List) | 列出所有团队 |
| 获取团队成员 (Get Team Members) | 获取团队中的所有成员 |
| 分配客服 (Assign Agent) | 将客服人员分配给团队 |
| 取消分配客服 (Unassign Agent) | 从团队中移除客服人员 |
触发事件 (Trigger Events)
Chatwoot fazer.ai 触发器 节点支持以下 Webhook 事件：
| 事件 (Event) | 描述 (Description) |
|---|---|
| 联系人已创建 (Contact Created) | 当新联系人创建时触发 |
| 联系人已更新 (Contact Updated) | 当联系人信息更新时触发 |
| 新对话已创建 (Conversation Created) | 当新对话创建时触发 |
| 对话状态已变更 (Conversation Status Changed) | 当对话状态发生变化时触发 |
| 对话已更新 (Conversation Updated) | 当对话信息更新时触发 |
| 正在输入 (Conversation Typing On) | 当有人开始打字输入时触发 |
| 停止输入 (Conversation Typing Off) | 当有人停止打字输入时触发 |
| 消息已创建 (Message Created) | 当消息创建时触发 |
| 消息已更新 (Message Updated) | 当消息更新时触发 |
| 收到呼入消息 (Message Incoming) ? | 仅针对收到的消息触发 |
| 发出呼出消息 (Message Outgoing) ? | 仅针对发出的消息触发 |
| 看板任务已创建 (Kanban Task Created) ? | 当看板任务创建时触发 |
| 看板任务已更新 (Kanban Task Updated) ? | 当看板任务更新时触发 |
| 看板任务已删除 (Kanban Task Deleted) ? | 当看板任务删除时触发 |
| 收到供应商事件 (Provider Event Received) ? | 当收到供应商事件（如 WhatsApp 底层事件）时触发 |
| 用户打开聊天插件 (Live Chat Widget Opened) | 当用户打开在线聊天小部件时触发 |
? 这些事件仅在 fazer.ai 的 Chatwoot 版本 中可用。
凭据配置
要进行 Chatwoot 身份验证，你需要：
1. Chatwoot API 地址
你的 Chatwoot 实例基础 URL（例如 https://app.chatwoot.com 或你的私有部署 URL）。
2. 访问令牌 (Access Token)
从你的 Chatwoot 个人资料中获取访问令牌：
- 登录你的 Chatwoot 控制面板
- 进入 个人设置 (Profile Settings) (点击头像 → 个人设置)
- 滚动到页面最下方的 访问令牌 (Access Token)
- 复制你的令牌
该令牌将作为 Api-Access-Token 请求头随每个请求发送。
兼容性
- 最低 n8n 版本要求: 1.0.0
- 已测试版本: n8n 1.x 和 2.x
- Chatwoot 版本: 兼容 Chatwoot v4.x 及更高版本
- fazer.ai Chatwoot: 使用看板面板 (Kanban Board)、WhatsApp 供应商操作及额外的 Webhook 事件时为必需
使用方法
基础工作流：自动回复新对话
- 添加一个 Chatwoot fazer.ai 触发器 节点
- 选择你的账户并选择 "新对话已创建 (Conversation Created)" 事件
- 连接到一个 Chatwoot fazer.ai 节点
- 将操作对象 (Resource) 设置为 "对话 (Conversation)"，操作 (Operation) 设置为 "发送文本消息 (Send Message)"
- 使用触发器输出的对话 ID (Conversation ID)
操作联系人
联系人资源支持 E.164 电话号码格式验证（例如 +60123456789）。你还可以在创建或更新联系人时设置社交媒体资料和自定义属性。
使用资源定位器 (Resource Locators)
所有资源均支持两种选择模式：
- 从列表中选择 (From List): 浏览并搜索可用项（账户、收件箱、对话等）
- 通过 ID 指定 (By ID): 直接输入 ID，适用于动态工作流
自定义属性
自定义属性可以通过三种方式指定：
- 定义模式 (Definition mode): 从现有的属性定义中选择
- 键值对模式 (Key-pair mode): 手动输入键值对
- JSON 模式 (JSON mode): 为复杂结构提供 JSON 对象
AI 工具支持
此节点已启用为 n8n AI 工具 (usableAsTool: true)，允许与 AI Agent（AI 代理）配合使用，构建智能自动化工作流。
资源
开发
预备条件
- Node.js v22 或更高版本
- pnpm 包管理器
项目设置
# 克隆仓库
git clone [https://github.com/fazer-ai/n8n-nodes-chatwoot.git](https://github.com/fazer-ai/n8n-nodes-chatwoot.git)
cd n8n-nodes-chatwoot
# 安装依赖
pnpm install
常用脚本
| 命令 | 描述 |
|---|---|
pnpm build |
将 TypeScript 源码编译到 dist/ 目录 |
pnpm lint |
运行 ESLint 代码检查 |
pnpm lint:fix |
运行 ESLint 并自动修复错误 |
pnpm dev |
启动开发模式 |
pnpm start |
启动 Docker 开发环境 |
pnpm start:log |
启动 Docker 开发环境并显示日志 |
项目结构
├── credentials/ # 凭据定义
├── nodes/Chatwoot/ # 节点具体实现
│ ├── actions/ # 资源操作逻辑
│ ├── methods/ # 列表搜索与加载选项
│ └── shared/ # 共享工具类
├── icons/ # 节点图标
└── dist/ # 编译输出（用于发布）
许可证
作者
Cayo Oliveira - fazer.ai
Gabriel Jablonski - fazer.ai
由 Dave Ang 基于 fazer.ai 节点汉化定制。
如有建议，欢迎在 GitHub Issues 提交。