Coze 连接企业微信机器人教程:从群机器人 Webhook 到自动回复完整实战 欢迎来到本教程,今天我们将学习一个非常实用的场景:如何把 Coze 连接到企业微信机器人,让 Coze 生成的内容自动发送到企业微信群。很多人搜索“Coze 连接企业微信机器人教程”时,其实心里想的不是“我想看概念”,而是:我已经有一个 Coze Bot,企业微信里也有群,能不能让它们真正跑起来?最好能自动推送日报、告警总结、知识库回答,甚至在群里像助手一样回复。这里先说一个容易踩坑的结论:企业微信群机器人 Webhook 本质上是“发消息入口”,不是完整的聊天机器人接口。也就是说,你可以让 Coze 把内容推送到企业微信群;但如果你希望群成员在企业微信群里直接 @机器人,然后 Coze 自动理解并回复,就不能只靠普通群机器人 Webhook,通常还需要企业微信应用回调、第三方中转服务,或者其他消息接入方案。本教程会按初级到中级的学习路径来讲:先完成最稳定的方案:Coze 生成内容 → 企业微信群机器人推送再理解进阶方案:企业微信消息 → 中转服务 → Coze → 企业微信群回复最后给你一套检查清单,方便排查连接失败、消息不显示、接口报错等问题如果你是第一次做,不用急。跟着这个步骤,一步一步来。你将学会什么完成本教程后,你应该能够做到:在企业微信群中创建群机器人并获取 Webhook 地址理解 Coze 与企业微信机器人连接的两种常见架构使用 Coze 工作流或外部服务调用企业微信机器人 Webhook用 Node.js 写一个可运行的中转服务,把用户问题发送给 Coze,再把回答推送到企业微信群排查企业微信机器人常见报错,例如 webhook 无效、消息格式错误、关键词拦截、频率限制等我认为新手最应该先掌握的是“推送型连接”。它简单、稳定、可控,非常适合日报、提醒、总结、审批通知、运维告警、销售线索提醒等场景。前置准备:开始前请确保你已经具备这些条件在进入步骤前,先确认一下环境。少一个环节,后面就容易卡住。1. 一个可用的 Coze Bot你需要在 Coze 中已经创建好 Bot,并且能正常对话。建议你先在 Coze 控制台里测试:输入一个简单问题,比如“请用三句话总结今天的待办事项”确认 Bot 能返回正常内容如果使用知识库或工作流,也要先在 Coze 内部调通不要一开始就把所有系统连起来。根据经验,先让每个模块独立可用,后面排错会轻松很多。2. 企业微信群管理员权限你需要能在目标企业微信群里添加群机器人。一般路径是:企业微信群 → 右上角群设置 → 群机器人 → 添加机器人 → 自定义机器人。添加后,企业微信会给你一个 Webhook 地址,格式通常类似:https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx这个 key 非常重要,等同于发送消息的凭证。不要把它公开到 GitHub、公开文档、截图或日志里。3. 一个可运行代码的环境(进阶部分需要)如果你只做 Coze 工作流推送,可能不需要写代码。但如果你想做更灵活的中转,例如“接收一个问题 → 请求 Coze → 推送到企业微信群”,建议准备:Node.js 18 或以上版本一个可以部署服务的环境,例如云服务器、Railway、Render、Vercel Serverless、企业内部服务器基础命令行能力接着往下做,我们先从最容易成功的方案开始。先搞清楚:Coze 连接企业微信机器人到底有几种方式?很多教程一上来就贴代码,但没有解释清楚连接方式,结果读者照着做也不知道为什么失败。这里我们先把架构拆开。方案 A:Coze 主动推送到企业微信群机器人这是最推荐新手学习的方式。流程是:Coze Bot / Coze 工作流 ↓ HTTP 请求节点或外部脚本 ↓ 企业微信机器人 Webhook ↓ 企业微信群收到消息适合场景:每天早上自动生成工作日报并发到群把客服问题总结后推送给运营群把监控告警交给 Coze 总结,再发到企业微信群定时推送知识库摘要、项目进度、销售线索优点是实现简单,企业微信群机器人原生支持 Webhook。局限是:群机器人只能被动接收你发过去的内容,它不能直接监听群成员发言。方案 B:企业微信消息进入 Coze,再由机器人回复这个就是大家更期待的“群聊智能助手”。流程通常是:企业微信用户消息 ↓ 企业微信应用回调 / 第三方接入层 ↓ 你的中转服务 ↓ Coze OpenAPI ↓ 企业微信机器人 Webhook 或企业微信应用消息 ↓ 企业微信群收到回复这条路线更强,但复杂度明显上升。你需要处理:企业微信回调配置消息验签与解密Coze API 调用上下文管理异常重试安全控制如果你只是想让 Coze 把内容发到企业微信群,不建议一开始就做这条线。先把方案 A 跑通,理解 webhook 和消息格式,再做进阶会更稳。第一步:创建企业微信群机器人并获取 Webhook现在我们来完成企业微信侧的准备。进入企业微信群后,按照下面的路径操作:打开目标企业微信群点击右上角群设置找到“群机器人”点击“添加机器人”选择“自定义机器人”设置机器人名称,例如“Coze 助手”保存后复制 Webhook 地址完成这一步后,你会拿到一个带 key 的 URL。这里有个技巧:建议你先单独保存到本地安全的位置,例如环境变量、密码管理器或服务器配置,不要直接写死在代码里。企业微信机器人消息格式企业微信机器人 Webhook 支持多种消息类型,常用的是 text 和 markdown。text 适合短消息:{ "msgtype": "text", "text": { "content": "这是一条来自 Coze 的测试消息" } }markdown 适合结构化内容:{ "msgtype": "markdown", "markdown": { "content": "## Coze 总结 > 今天有 3 个重点任务需要关注" } }注意,企业微信机器人的 markdown 不是完整 GitHub Markdown,某些复杂表格、HTML、特殊样式可能不会按预期渲染。教程里建议你优先使用标题、列表、引用、加粗这些基础格式。第二步:先用最小测试验证 Webhook 是否可用不要急着接 Coze。下一步很关键:先验证企业微信 Webhook 自己能不能正常收消息。你可以用 Postman、Apifox 或 curl 测试。这里用 curl 举例:curl '你的企业微信机器人 Webhook 地址' \ -H 'Content-Type: application/json' \ -d '{"msgtype":"text","text":{"content":"Coze 企业微信机器人连接测试成功"}}'如果群里能收到消息,说明企业微信侧没有问题。如果没有收到,常见原因是:Webhook 地址复制不完整企业微信机器人被删除或禁用群机器人设置了关键词,但你的消息没有包含关键词请求体不是合法 JSONContent-Type 没有设置为 application/json这里特别提醒一下“关键词”限制。有些企业微信群机器人会设置安全关键词,例如必须包含“告警”或“日报”才允许发送。如果你测试时发的是“hello”,可能会被企业微信拦截。第三步:在 Coze 工作流里调用企业微信机器人 Webhook如果你的 Coze 账号和当前版本支持工作流里的 HTTP 请求节点,那么可以直接在 Coze 内完成推送。我们来学习一个典型流程:用户输入主题,Coze 生成总结,然后发送到企业微信群。工作流设计可以设计成这样:开始节点 ↓ 大模型节点:生成日报或总结 ↓ HTTP 请求节点:调用企业微信机器人 Webhook ↓ 结束节点:返回推送结果大模型节点提示词示例你可以在大模型节点中写:请根据用户输入的内容,生成一段适合发送到企业微信群的工作总结。 要求: 1. 控制在 300 字以内 2. 使用清晰的小标题和列表 3. 语气专业、简洁 4. 如果信息不足,请列出需要补充的内容输出变量可以命名为 summary。HTTP 请求节点配置HTTP 方法选择 POST。请求地址填写企业微信机器人 Webhook。请求头:Content-Type: application/json请求体可以配置为:{ "msgtype": "markdown", "markdown": { "content": "{{summary}}" } }不同版本的 Coze 对变量引用语法可能略有差异。如果你发现 {{summary}} 没有被替换,要回到工作流节点里查看变量选择器,使用平台提供的变量插入方式,不要手写猜测。完成了这一步,你就拥有了一个最基础但很实用的自动推送链路。第四步:用 Node.js 做一个更灵活的中转服务接下来进入进阶环节。为什么需要中转服务?因为真实业务里,你往往不只是“发一段固定内容”。你可能需要:接收外部系统传来的问题或事件调用 Coze 生成回答对回答做格式清洗再发送到企业微信群记录日志,方便排错下面给你一份完整示例。它会提供一个 /ask 接口,你向它提交问题,它会调用 Coze OpenAPI 获取回答,然后推送到企业微信群机器人。安装依赖创建项目目录后执行:npm init -y npm install express dotenv创建 .env 文件:COZE_API_TOKEN=你的 Coze Personal Access Token COZE_BOT_ID=你的 Coze Bot ID WEWORK_WEBHOOK=你的企业微信机器人 Webhook PORT=3000完整代码:server.jsimport express from 'express'; import dotenv from 'dotenv'; dotenv.config(); const app = express(); app.use(express.json()); const COZE_API_TOKEN = process.env.COZE_API_TOKEN; const COZE_BOT_ID = process.env.COZE_BOT_ID; const WEWORK_WEBHOOK = process.env.WEWORK_WEBHOOK; const PORT = process.env.PORT || 3000; function requiredEnv() { const missing = []; if (!COZE_API_TOKEN) missing.push('COZE_API_TOKEN'); if (!COZE_BOT_ID) missing.push('COZE_BOT_ID'); if (!WEWORK_WEBHOOK) missing.push('WEWORK_WEBHOOK'); if (missing.length) { throw new Error(`缺少环境变量:${missing.join(', ')}`); } } async function callCoze(question, userId = 'wework-user') { const createRes = await fetch('https://api.coze.cn/v3/chat', { method: 'POST', headers: { Authorization: `Bearer ${COZE_API_TOKEN}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ bot_id: COZE_BOT_ID, user_id: userId, stream: false, auto_save_history: true, additional_messages: [ { role: 'user', content: question, content_type: 'text' } ] }) }); const createData = await createRes.json(); if (!createRes.ok) { throw new Error(`Coze 创建会话失败:${JSON.stringify(createData)}`); } const chatId = createData.data?.id; const conversationId = createData.data?.conversation_id; if (!chatId || !conversationId) { throw new Error(`Coze 返回缺少 chat_id 或 conversation_id:${JSON.stringify(createData)}`); } for (let i = 0; i < 20; i++) { await new Promise(resolve => setTimeout(resolve, 1000)); const retrieveUrl = new URL('https://api.coze.cn/v3/chat/retrieve'); retrieveUrl.searchParams.set('conversation_id', conversationId); retrieveUrl.searchParams.set('chat_id', chatId); const retrieveRes = await fetch(retrieveUrl, { headers: { Authorization: `Bearer ${COZE_API_TOKEN}` } }); const retrieveData = await retrieveRes.json(); const status = retrieveData.data?.status; if (status === 'completed') { const listUrl = new URL('https://api.coze.cn/v3/chat/message/list'); listUrl.searchParams.set('conversation_id', conversationId); listUrl.searchParams.set('chat_id', chatId); const listRes = await fetch(listUrl, { headers: { Authorization: `Bearer ${COZE_API_TOKEN}` } }); const listData = await listRes.json(); const messages = listData.data || []; const answer = messages.find(item => item.type === 'answer'); return answer?.content || 'Coze 已完成处理,但没有返回可展示的 answer 消息。'; } if (status === 'failed' || status === 'canceled') { throw new Error(`Coze 会话状态异常:${status}`); } } throw new Error('等待 Coze 回复超时'); } function formatForWeWork(question, answer) { return [ '## Coze 助手回复', '', '**问题:**', question, '', '**回答:**', answer ].join(' '); } async function sendToWeWork(content) { const res = await fetch(WEWORK_WEBHOOK, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ msgtype: 'markdown', markdown: { content } }) }); const data = await res.json(); if (!res.ok || data.errcode !== 0) { throw new Error(`企业微信发送失败:${JSON.stringify(data)}`); } return data; } app.post('/ask', async (req, res) => { try { const question = req.body.question; const userId = req.body.userId || 'wework-user'; if (!question || typeof question !== 'string') { return res.status(400).json({ ok: false, message: '请在请求体中提供 question 字段' }); } const answer = await callCoze(question, userId); const markdown = formatForWeWork(question, answer); await sendToWeWork(markdown); res.json({ ok: true, answer }); } catch (error) { console.error(error); res.status(500).json({ ok: false, message: error.message }); } }); app.get('/health', (req, res) => { res.json({ ok: true }); }); requiredEnv(); app.listen(PORT, () => { console.log(`服务已启动:http://localhost:${PORT}`); });如果你的项目默认不是 ES Module,需要在 package.json 中加入:{ "type": "module" }本地运行node server.js然后请求:curl -X POST 'http://localhost:3000/ask' \ -H 'Content-Type: application/json' \ -d '{"question":"请帮我生成一段项目周报,重点包括进度、风险和下周计划"}'正常情况下,你会看到:接口返回 ok: true企业微信群收到一条由 Coze 生成的 markdown 消息恭喜你完成了一个基础版 Coze 企业微信机器人连接服务。第五步:把它变成更像“真实可用”的机器人上面的代码能跑,但还不算生产可用。真实场景里,你至少要考虑下面几件事。1. 不要把 Webhook 和 Token 写进代码这一点非常重要。Coze API Token 和企业微信机器人 Webhook 都属于敏感信息。建议放到:环境变量云平台 Secret 配置企业内部配置中心密钥管理服务不要提交到 Git 仓库。哪怕是私有仓库,也不建议这么做。2. 控制消息长度企业微信机器人对消息长度有限制,不同消息类型限制也不同。Coze 输出太长时,可能会导致发送失败或显示不完整。实用做法是:在 Coze 提示词里要求控制字数在中转服务里截断超长内容长内容拆成多条消息发送对日报、周报使用摘要格式,不要原文全部推送3. 给 Coze 增加明确的群消息格式要求你可以在 Bot 的系统提示词中加入类似规则:当你的回答用于企业微信群消息时,请遵守: 1. 先给出结论 2. 内容控制在 500 字以内 3. 使用项目符号组织信息 4. 避免输出复杂表格 5. 如果信息不足,请明确说明需要补充哪些字段这会明显提升企业微信群里的阅读体验。4. 做好错误提示,而不是静默失败新手常见的问题是:接口失败了,但群里没有任何提示,也不知道哪里错了。建议你在中转服务里至少记录:请求时间用户问题Coze 返回状态企业微信返回 errcode 和 errmsg请求耗时不要记录敏感 Token,也不要把用户隐私内容随意打到公开日志。实践练习:做一个“项目日报助手”现在我们来做一个小练习,帮助你真正掌握这套流程。目标:输入一段项目进展,让 Coze 自动整理成企业微信群日报。你可以向 /ask 提交:{ "question": "请把下面内容整理成项目日报:今天完成登录页联调,修复了验证码刷新问题;接口还有两个字段没确认;明天计划完成权限菜单;风险是测试环境偶尔超时。" }期望企业微信群收到类似结构:## 项目日报 **今日进展** - 完成登录页联调 - 修复验证码刷新问题 **待确认事项** - 接口仍有两个字段需要确认 **明日计划** - 完成权限菜单开发与联调 **风险提醒** - 测试环境偶尔超时,建议排查服务稳定性如果输出不稳定,不要急着改代码。优先调整 Coze Bot 的提示词,让它明确知道“企业微信群消息”需要短、清楚、结构化。检查验收:如何判断你真的连接成功了?完成教程后,可以按这份清单检查。基础验收企业微信 Webhook 单独测试能收到消息Coze Bot 在控制台里能正常回答中转服务 /health 能正常访问/ask 接口能返回 Coze 的 answer企业微信群能收到最终消息格式验收消息没有出现大量乱码markdown 标题、列表可以正常显示内容没有超过企业微信限制群消息读起来像给人看的,而不是接口调试日志安全验收Token 没有写死在代码里Webhook 没有出现在公开仓库服务接口有访问控制,不能被陌生人随便调用日志中没有输出完整密钥如果这些都通过,你的 Coze 企业微信机器人连接就已经具备了可用基础。常见问题 FAQ企业微信群机器人能不能直接接收群成员消息?普通企业微信群自定义机器人主要用于通过 Webhook 往群里发消息,不适合直接接收群成员消息。如果你要做真正的群聊问答,需要考虑企业微信应用回调、客服消息、第三方中转层等方案。为什么企业微信返回成功,但群里没看到消息?优先检查三个点:Webhook 是否对应当前群、机器人是否设置了关键词、消息内容是否符合企业微信要求。有时你发的内容没有包含关键词,接口会返回错误信息,需要看 errcode 和 errmsg。Coze 回复太长怎么办?建议从两层处理:在 Coze 提示词中限制输出长度,在中转服务里做长度判断。对于长内容,可以拆分发送,但不要拆得太碎,否则会刷屏。企业微信机器人适合做哪些 Coze 场景?比较适合通知类、总结类、提醒类场景,例如日报、周报、监控告警摘要、客户线索总结、知识库问答结果推送。不太适合一开始就做复杂多轮群聊,因为上下文和消息接入会更复杂。国内版和海外版 Coze API 地址一样吗?不一定。你要以自己 Coze 控制台和官方文档显示的 API 地址为准。本文示例使用的是常见国内接口写法,如果你的账号环境不同,需要替换对应域名和鉴权方式。结尾:先跑通,再优化学习 Coze 连接企业微信机器人,最容易犯的错误是一步到位:既想接收群消息,又想多轮对话,还想权限控制和知识库检索全部做好。我的建议是按这个顺序推进:先用企业微信 Webhook 发一条测试消息再让 Coze 工作流主动推送一条结构化消息然后用中转服务调用 Coze API 并转发到企业微信群最后再考虑企业微信应用回调、多用户上下文、权限和审计这样学习路径更稳,也更接近真实项目落地方式。当你能稳定完成“Coze 生成内容 → 企业微信群收到消息”这条链路后,后面的智能日报、告警总结、知识库助手、运营播报,本质上都是在这个基础上扩展。