企业微信 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"名单内。

---