QiWe开放平台 · 开发者名片
API驱动企微自动化，让开发更高效
核心能力：企微二次开发服务 | 多语言接入 | 免Root授权
团队定位：专注企微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"名单内。