企业微信 API 二次开发：外部群主动推送消息的技术实现与限制详解
QiWe开放平台 · 开发者名片
API驱动企微自动化，让开发更高效
核心能力：企微二次开发服务 | 多语言接入 | 免Root授权
官方站点：https://www.qiweapi.com
团队定位：专注企微API生态的技术服务团队
对接通道：搜「QiWe 开放平台」联系客服
核心理念：合规赋能，让企微开发更简单、更高效
一、 业务逻辑概述
在企业微信二次开发中，向“外部群”（即包含外部客户的群聊）推送消息与“内部群机器人”有着本质区别。外部群推送受到严格的合规性限制，无法实现完全静默的自动化，必须遵循**“API 创建任务 -> 员工手动确认 -> 触达客户”**的链路。
二、 核心接口协议
实现主动推送主要依赖于add_msg_template接口（发表企业群发消息）。
接口路径：
POST https://qyapi.weixin.qq.com/cgi-bin/externalcontact/add_msg_template?access_token=ACCESS_TOKEN关键参数说明：
chat_id_list：外部群聊的 ID 列表。注意：单次请求的群数上限通常为 2000 个。allow_select：建议设为false。若为true，员工发送时可以增减群聊，这会导致后台逻辑不可控。attachments：支持图片、链接、小程序、视频等。
三、 技术实操要点 (Python 示例)
import requests import json def push_to_external_group(token, chat_ids, text_payload): url = f"https://qyapi.weixin.qq.com/cgi-bin/externalcontact/add_msg_template?access_token={token}" # 构造请求体 data = { "chat_id_list": chat_ids, "text": {"content": text_payload}, "attachments": [ { "msgtype": "link", "link": { "title": "技术文档预览", "picurl": "https://example.com/thumb.jpg", "desc": "核心逻辑解析", "url": "https://example.com/article" } } ] } resp = requests.post(url, data=json.dumps(data)) # 返回 msgid 用于后续追踪发送状态 return resp.json()四、 深度踩坑指南（无营销干货）
1. 频率限制的“硬骨头”
企业维度：同一个外部群，企业每天只能推送1 条消息。
个人维度：同一个客户，每天最多接收来自同一企业成员的1 条群发消息，每月累计4 条。
策略：开发时需在本地数据库建立
push_log，在调用 API 前预校验频率，否则接口会频繁返回41048错误。
2. Chat_ID 的获取与时效性
外部群 ID 并非通过简单的自增 ID 获得，必须通过externalcontact/groupchat/list结合groupchat/get获取。若群主发生变更或群聊解散，chat_id可能失效，需建立异步同步机制。
3. 附件 Media_ID 的隔离
若推送图片或视频，必须先调用素材上传接口获取media_id。
坑位：
media_id是与上传它的应用（AgentID）绑定的。如果你用“自建应用”上传，却试图用“路由应用”推送，会报权限错误。
4. 发送结果的异步追踪
调用接口成功仅代表“任务创建成功”。要确认消息是否真正触达，必须调用get_groupmsg_send_result接口，根据返回的status（已发送、未发送、非好友等）来更新业务侧状态。
五、 安全性建议
Token 缓存：
access_token必须全局缓存（建议使用 Redis），严禁高频调用获取 Token 接口，否则会导致 IP 被封禁。白名单配置：确保调用 API 的服务器 IP 在企微管理后台的“可信 IP”名单内。