企业微信 API 开发：外部群自动化推送的技术实现

外部群的消息推送，本质上是利用企业微信的服务端 API 与 自建应用权限 。目前主流的实现路径有两种：基于 Appchat 接口的深度集成和基于群机器人的轻量推送。

1. 核心技术路径对比

方案	自建应用发送 (Appchat)	群机器人 (Webhook)
适用场景	业务逻辑高度集成、需要追踪发送状态	简单的预警通知、非结构化信息共享
开发难度	较高（需维护 Token、管理 chatid）	较低（直接调用 Hook 地址）
消息类型	文本、图片、图文、文件、卡片等	文本、Markdown、图片、文件
可控性	强（可由后台逻辑动态控制）	弱（严重依赖群内配置的 Webhook）

2. 基于 Appchat 接口的开发流程

这是最常用的二次开发方案，允许企业自建系统向指定的外部群推送结构化业务消息。

第一步：获取权限与 AccessToken

所有 API 调用必须通过 AccessToken 鉴权。你需要自建应用的 AgentID 和 Secret。

AccessToken = f(CorpID, AppSecret)

注意： 针对外部群操作，该应用必须在企业微信管理后台的"客户联系"权限范围内，并具备相应群聊的管理权限。

第二步：建立群 ID (`chatid`) 映射

外部群的 chatid 是推送的唯一标识。开发者通常通过以下方式获取：

通过接口创建群： 调用 create_chat 接口时直接返回。
事件回调： 当群聊发生变更或成员变动时，通过回调 XML/JSON 获取。
配置应用范围： 确保应用在外部群所在的群主管理范围内。

第三步：构造并发送消息

接口地址：POST https://qyapi.weixin.qq.com/cgi-bin/appchat/send?access_token=ACCESS_TOKEN

技术要点：消息体封装

对于外部群，推荐使用 textcard（文本卡片）或 markdown 格式，这能提供更好的结构化视觉体验。

复制代码

{
    "chatid": "EXTERNAL_CHATID_123",
    "msgtype": "textcard",
    "textcard": {
        "title": "业务处理提醒",
        "description": "单据编号：PO-20231024\n当前状态：待审批",
        "url": "https://yourserver.com/detail",
        "btntxt": "立即处理"
    }
}

3. 开发中必须注意的关键约束

频率限制（Throttling）：

企业微信对外部消息推送有严格的频率限制。通常，同一个群每分钟接收消息不能超过特定阈值。建议在代码层引入令牌桶（Token Bucket）或漏桶算法来平滑推送压力。
客户接收配额：

外部群消息受企业微信"客户联系"规则限制。如果某位客户接收到的群发消息超过每日配额，推送接口可能会返回 81013 或其他特定的错误码。
安全校验：

在处理回调请求时，务必对 Timestamp、Nonce 和 Signature 进行严格校验，防止伪造的推送指令。

4. 架构设计建议

异步队列化： 不要将推送操作放在同步业务逻辑中。建议使用 RabbitMQ 或 Redis 队列，将待发送的消息落库，由独立的 Worker 异步执行，以便处理失败重试和流控。
状态闭环： 记录接口返回的 msgid。虽然 Appchat 接口目前不直接支持阅读回执，但可以通过在卡片 URL 中携带参数，在业务侧实现点击确认。
敏感词预检： 外部群消息涉及企业形象，建议在调用 API 前，通过内部的过滤机制剔除敏感词，避免因违规导致应用权限被封禁。

5. 总结

外部群主动推送的难点不在于 API 调用本身，而在于对权限范围的理解 和推送频率的控制。开发者应优先确保应用具备操作外部联系人的权限，并在此基础上构建稳健的异步推送体系。

提供了后台直登功能，登录成功后获取相关参数，快速Apifox在线测试，所有登录功能都是基于QiWe平台API自定义开发。