企业微信API开发：外部群主动推送场景
QiWe开放平台 · 开发者名片
API驱动企微自动化，让开发更高效
核心能力：为开发者提供标准化接口、快速集成工具，助力产品高效拓展功能场景
官方站点：https://www.qiweapi.com
团队定位：专注企微API生态的技术服务团队
对接通道：搜「QiWe 开放平台」联系客服
核心理念：合规赋能，让企微开发更简单、更高效
以下是针对外部群主动推送场景，整理的开发前必读的底层逻辑与合规红线。
核心逻辑：必须要搞清楚的“身份”问题
在企业微信 API 中，消息推送的权限和展示效果取决于你使用的调用主体：
企业自建应用：适合做自动化通知、报表推送。虽然是主动推送，但如果内容过于营销，容易被用户投诉。
群机器人：最简单的接入方式，但仅限于内部群或开启了机器人权限的外部群。
企业群发（API 触发）：这是最合规的外部推送方式。你调用 API 后，消息会下发到员工的“群发助手”中，需要员工手动点击确认才能发出。这种方式虽然多了一步，但权重最高，不容易封号。
避坑指南：四大核心限制
1. 频率与额度限制（不只是 API 限流）
API 限流：通常为每分钟几千次，但这只是技术限制。
接收上限：外部联系人（客户）每天接收来自同一企业的群发消息是有上限的。这意味着即便你的 API 返回
errcode: 0，客户可能也收不到消息。建议：不要把 API 当作群发垃圾广告的工具，应侧重于基于业务逻辑的精准触发。
2. 素材的有效期
所有非文本消息（图片、文件、语音）都需要先上传获取
media_id。注意：
media_id的有效期仅为3 天。如果你的推送任务是定时触发且跨度较长，必须在发送前动态检查并重新上传素材。
3. IP 白名单与安全
企业微信后台必须配置可信 IP 地址。如果你的服务器更换了 IP 或使用了动态 IP，API 请求会直接被拦截。
Secret 安全：绝对不要在前端代码或公开的 GitHub 仓库中暴露你的
Secret。
4. “被动回执”的重要性
主动推送后，建议配合接收消息服务器（回调）。
如果客户在群里@机器人或产生互动，你的系统需要能接住这些回调信息，从而实现“推送 -> 互动 -> 再推送”的闭环，而不是单向骚扰。
开发流程建议：从 0 到 1 的正确路径
明确应用可见范围：在后台配置应用时，必须确保相关的员工在“可见范围”内，否则 API 无法操作这些员工的客户群。
建立中心化 Token 管理：不要在每个发送函数里都调用
get_token，要用 Redis 或数据库做全局缓存和定时刷新。小规模灰度测试：先给自己建一个外部测试群，拉几个同事作为“外部联系人”，实测图片、链接和小程序的展示效果。
异常捕获机制：代码中必须处理
40014(Token过期)、45009(接口限频) 和84061(无权操作该客户) 等常见错误码。
结语：敬畏社交生态
企业微信的本质是**“有温度的服务”**。通过 API 推送时，应尽量模拟真实服务场景（如：服务进度通知、预约成功提醒），避免在深夜或休息时间推送，降低投诉率是 API 长久运行的唯一标准。