如何通过 API 主动向外部群发送消息

1. 核心链路：如何通过代码"说话"？

在企业微信 API 体系中，主动向外部群发消息主要依赖于 "群机器人（Webhook）" 或者 "应用消息（App Message）"。

方案 A：群机器人 Webhook（最推荐，门槛低）

如果你的目的是在特定群聊中同步业务告警、数据日报或欢迎语，Webhook 是最便捷的路径。

实现原理 ：在群聊中开启机器人，获取唯一的 webhook_url。
请求方式：向该 URL 发送 POST 请求，携带 JSON 格式的消息体。
支持格式：文本、Markdown、图片、图文卡片（news）、文件。

方案 B：应用消息推送

如果你需要基于特定业务逻辑（如：某个客户经理名下的所有群同步消息），则通常需要通过自建应用调用 externalcontact/send_by_groupchat 接口。

2. 实战示例：Python 调用 Webhook 逻辑

以下是一个标准的 Markdown 格式消息推送示例。Markdown 的好处在于可以实现字体颜色标注 和链接跳转，非常适合做业务通知。

复制代码

import requests
import json

def send_wechat_group_msg(webhook_url, content):
    headers = {"Content-Type": "application/json"}
    payload = {
        "msgtype": "markdown",
        "markdown": {
            "content": f"""实时业务看板 <font color=\"warning\">【待处理】</font>
            > 订单编号：<font color=\"comment\">ORD_20231024</font>
            > 客户等级：VIP
            > 状态：[点击前往系统查看](https://your-system.com)
            
            请相关负责人 <@WuYanZu> 及时跟进。"""
        }
    }
    
    response = requests.post(webhook_url, data=json.dumps(payload), headers=headers)
    return response.json()

# 调用示例
# webhook_url = "在群设置->智能群助手->添加机器人后获得"
# send_wechat_group_msg(webhook_url, "测试消息")

3. 避坑指南：二次开发中的"潜规则"

在实际开发中，如果不了解企业微信的限制，很容易出现消息发送失败或接口报错。

① 频率限制（Rate Limit）

企业微信对 API 调用有严格的频率控制。

群机器人：每个机器人每分钟最多发送 20 条消息。
应用接口：根据企业规模（认证人数）有不同的日调用上限。

② 外部群的特殊性

如果群内包含微信个人用户，API 的限制会比纯内部群更多：

文件大小限制：发送的文件或图片不能超过 20MB。
不可撤回性：通过 Webhook 发送的消息，目前无法通过 API 直接撤回，测试时请务必谨慎。

③ 媒体素材预上传

如果你想发送图片或文件，不能直接传本地路径。需要先调用 media/upload 接口将文件上传到企业微信服务器，换取一个 media_id，再将这个 ID 填入消息体中。

4. 架构建议：如何构建稳定的推送系统

对于企业级应用，不建议直接在业务代码里硬编码 webhook_url。

统一路由层：建立一个中间层（如消息网关），业务系统只管发消息内容和目标群 ID，由中间层去匹配对应的 Webhook 或 AccessToken。
异步队列：使用 Redis 或 RabbitMQ 进行缓冲。当瞬时业务高峰（如双11）产生大量通知时，避免接口限频导致的消息丢失。
日志追踪 ：记录每一次 API 的 request_id 和返回码，方便在出问题时快速定位是代码 bug 还是腾讯服务器波动。

总结

企业微信 API 的二次开发本质上是业务逻辑与通讯能力的桥接。主动调用外部群能力，能够极大地提升私域运营的响应速度，减少人工搬运信息的操作成本。