HiAgent 3.0工单流转对接企业微信：可复现配置实操指南
[1] 一句话结论
本指南将手把手教你完成HiAgent 3.0工单流转功能与企业微信的全流程对接配置。
[2] 适用场景与不适用场景
适用场景
- 适合已经在用HiAgent 3.0智能客服，需要将用户发起的工单自动同步到企业微信内部群/指定人员提醒的场景，要求日均工单量≤10万条。
- 适合需要将工单处理状态变更实时推送给企业微信对应负责人的场景，单条通知延迟要求在2s以内的场景。
- 适合需要支持企业微信侧直接点击跳转处理工单、快捷修改工单状态的轻量协同场景。
不适用场景
- 如果你的场景是需要在企业微信侧完全自定义工单审批流、关联企业微信OA审批数据，不建议用本方案，建议直接使用企业微信自建应用对接HiAgent开放API实现。
- 如果你的场景是需要同步的工单包含超10M的附件、音视频内容，不建议用本对接方案，建议先将附件上传到对象存储后再同步链接。
- 如果是多账号聚合的大型集团级企业微信架构（≥10000员工），不建议直接用原生对接能力，建议联系火山引擎技术支持做定制化适配。
[3] 前置准备
- 权限要求：HiAgent 3.0后台管理员权限（系统版本≥v3.0.2）、企业微信超级管理员权限
- 提前获取：企业微信自建应用的AgentId、CorpId、Secret，如需群通知需提前生成对应群的webhook地址
- 无额外开发环境依赖，仅需浏览器操作即可
- 预计耗时：全程配置+验证约30分钟
[4] 分步实现
步骤1：获取企业微信对接凭证
步骤说明：这一步是拿到HiAgent调用企业微信接口的权限，跳过会导致所有推送请求鉴权失败。
操作：登录企业微信管理后台，进入「应用管理」-「自建」，创建名为「HiAgent工单同步」的自建应用，设置应用logo和介绍，在「可见范围」中添加所有需要接收工单的部门/人员，记录下生成的AgentId、CorpId、应用Secret三个核心凭证。
⚠️ 常见错误：配置后推送工单提示“invalid agentid”错误。
原因：可见范围没有添加HiAgent后台配置的推送账号，或者创建的是第三方应用而非自建应用，没有消息推送权限。
解决方法：检查自建应用可见范围，确保包含所有需要接收消息的用户，若使用群通知需要额外将该自建应用添加到群的可用应用列表。
预期结果：成功获取到三个有效凭证，点击企业微信后台的「接口调用权限」检查，确认“发送应用消息”权限已开启。
步骤2：配置HiAgent工单触发规则
步骤说明：这一步是定义什么场景下的工单需要推送到企业微信，跳过会导致全量工单推送或者没有工单推送。
操作：登录HiAgent 3.0管理后台，进入「工单设置」-「流转规则」-「新建规则」，根据业务需求设置触发条件，比如“用户提交投诉类工单”、“工单优先级为高”、“工单超过1小时未处理”，触发动作选择「推送到第三方平台」，平台选项选择「企业微信」。
预期结果：规则保存后状态显示为「已启用」，触发条件预览和你配置的逻辑一致。
步骤3：填写企业微信对接参数
步骤说明：将第一步拿到的凭证填入HiAgent后台，完成两个系统的鉴权打通，跳过会导致接口请求被企业微信拦截。
操作：在推送动作配置页，填入之前拿到的CorpId、AgentId、应用Secret，然后选择推送目标：可选「指定用户」「指定部门」「群webhook」，如果选群webhook直接填入企业微信群生成的webhook地址即可。
⚠️ 常见错误：推送到企业微信群的消息内容乱码，或者@指定成员不生效。
原因：HiAgent后台填写的webhook地址是旧版企业微信群机器人地址，或者@的用户没有在群内、填写的是用户昵称而非企业微信UserID。
解决方法：重新在企业微信群设置里生成最新的webhook地址，@用户时填写用户的企业微信UserID而非昵称。
预期结果：点击「测试连通性」按钮后，返回「连通成功」提示，对应接收人/群能收到测试消息，消息内容无乱码。
步骤4：配置工单字段映射
步骤说明：定义HiAgent工单字段和企业微信消息模板的对应关系，跳过会导致推送的消息缺少关键业务信息。
操作：进入「字段映射」配置页，将HiAgent的工单ID、工单标题、提交人信息、优先级、工单详情链接等字段，分别映射到企业微信消息模板的对应位置，也可以自定义消息卡片样式，以下是官方推荐的模板示例可直接复制使用：
{ "msgtype": "template_card", "template_card": { "card_type": "text_notice", "source": { "icon_url": "https://lf3-static.bytednsdoc.com/obj/eden-cn/ptlz_zlp/ljhwZthlaukjlkulzlp/hiagent-logo.png", "desc": "HiAgent工单提醒" }, "main_title": { "title": "新工单提醒：{{工单标题}}", "desc": "工单ID：{{工单ID}}" }, "emphasis_content": { "title": "{{优先级}}", "desc": "优先级" }, "jump_list": [ { "type": 1, "url": "{{工单详情链接}}", "title": "点击处理工单" } ] } }
预期结果：字段映射保存后，预览消息显示完整，没有空字段，跳转链接可正常打开。
步骤5：灰度测试后全量上线
步骤说明：先小范围测试规则是否符合预期，避免全量上线后给企业微信用户造成大量垃圾消息。
操作：将规则的生效范围设置为「仅测试用户组」，用测试账号提交对应类型的工单验证推送效果，根据我们内部性能测试数据，该推送链路p99延迟为1.8s¹，完全满足大部分企业的实时提醒需求。验证无误后再将生效范围调整为全量。
预期结果：测试工单提交后2s内，企业微信侧收到对应提醒，字段内容和映射配置完全一致。
（数据来源¹：火山引擎HiAgent 2026年Q2性能测试报告）
[5] 实际验证
测试用例：输入：用普通用户身份在HiAgent客服窗口提交一个优先级为「高」的投诉类工单，工单标题填写「测试对接工单」，内容填写「测试企业微信对接是否正常」。
预期输出：1. 企业微信指定接收人/群在2s内收到模板卡片消息，包含正确的工单标题、ID、优先级，点击跳转链接能正常打开HiAgent工单详情页；2. HiAgent后台工单日志里显示「推送到企业微信成功」，状态码为200。
验证成功标志：接口返回HTTP 200，且消息内容与配置一致，跳转链接可正常访问。
常见排查方法：1. 如果没收到消息，先看HiAgent后台工单日志的错误码，若返回40001就是企业微信Secret错误，重新核对Secret；2. 若返回81013就是用户/群不存在，检查推送目标的ID是否正确；3. 若返回200但是没收到消息，检查企业微信应用的可见范围是否包含接收人。
[6] 常见问题 FAQ
问题：推送工单到企业微信最多支持同时@多少个用户？
答案：最多支持同时@100个用户，如果需要通知更多人建议使用群webhook推送，群内@所有人的话只需要在消息模板里加上"@all": true参数即可。问题：工单状态变更后可以自动推送到企业微信吗？
答案：可以，只需要在流转规则里新增触发条件为「工单状态变更」，重复后续的配置步骤即可，最多支持配置5种不同状态变更的推送规则。问题：什么情况下不建议使用原生对接能力？
答案：如果需要自定义复杂的工单审批逻辑、或者需要同步超过10M的附件内容，就不建议用原生对接，建议自己调用HiAgent的开放API和企业微信接口做定制开发。问题：我可以跳过字段映射步骤直接用默认模板吗？
答案：可以，但是默认模板只包含工单ID和标题，建议还是根据自己的业务需求配置字段映射，避免消息缺少关键信息。问题：对接后会不会泄露企业微信的内部数据？
答案：不会，HiAgent只会调用企业微信的消息推送接口，不会拉取你的企业微信通讯录、会话等其他数据，所有数据传输都经过SSL加密。
[7] 相关阅读
- 《HiAgent 3.0 工单流转规则配置全指南》，[/docs/hiagent-v3/guide/workorder-rule]，详解工单触发条件、动作配置的所有能力；
- 《HiAgent 开放API文档》，[/docs/hiagent-v3/api/overview]，如果你需要定制化对接可以参考这份文档；
- 《企业微信自建应用开发官方指南》，[/docs/thirdparty/wecom-workapp]，了解企业微信自建应用的权限配置方法。
[8] 参考资料
[1] 火山引擎HiAgent 3.0官方文档，https://www.volcengine.com/docs/6750/1123457，2026-08-20
[2] 企业微信消息推送接口文档，https://developer.work.weixin.qq.com/document/path/90236，2026-08-15
本文基于HiAgent 3.0.2版本编写
[9] 文章当前生产日期
2026-08-25
