消息推送（原群机器人）

企业微信从客户端 v4.1.41 起将“群机器人”更名为“消息推送”。它适合向固定的企业内部群发送告警和通知。本文依据企业微信开发者中心和帮助中心整理，核验日期为 2026-09-08；未使用真实企业账号执行发送验证。

能力边界

问题	结论
哪些群可以添加	内部群聊，包括全员群、自建应用创建的内部群和 JS-SDK 创建的内部群
外部群或客户群能否添加	不能。企业微信帮助中心明确说明外部群暂不支持消息推送
能否从 Web 管理后台直接创建并绑定到群	不能。创建和添加入口在企业微信电脑端或手机端的内部群聊中
Web 管理后台能做什么	管理员可启停“消息推送”应用，并设置“可创建消息推送的成员”范围
是否支持接收群消息或回调	不支持消息回调；它是主动推送能力，不是可对话机器人

如果目标群里包含微信客户或其他外部联系人，应先把它视为外部群处理，不要复用内部群的 Webhook 方案。

准备条件

开始前逐项确认：

1. 使用较新的企业微信电脑端或手机端。旧版本仍可能显示“群机器人”，v4.1.41 及以后显示“消息推送”。
2. 目标群是内部群。群信息中若显示外部联系人、微信用户或外部群标识，则不满足条件。
3. 当前账号在管理员配置的“可创建消息推送的成员”范围内。
4. 如果该群启用了“仅群主管理”，需要由群主完成添加；此时群管理员和普通群成员都不会看到添加入口。
5. 企业管理员没有停用“消息推送”应用。
6. 发送端能够通过 HTTPS 访问 qyapi.weixin.qq.com，并能在服务端安全保存完整 Webhook URL。

如何判断自己有没有权限

最可靠的判断方式是检查实际入口，因为企业微信没有公开一张“所有角色固定拥有哪些权限”的矩阵。

在电脑端打开目标内部群，依次进入右上角 ... → 消息推送：

• 能看到“添加”并能进入创建页：当前账号具备创建或添加权限。
• 能看到已有项但没有“添加”：先检查是否开启“仅群主管理”，再让管理员检查可创建成员范围。
• 完全没有“消息推送”：检查群是否为外部群、客户端版本，以及企业是否已停用该应用。
• 创建后看不到 Webhook：官方帮助中心明确说明创建人可在消息推送资料中取得对应 Webhook URL；非创建人看不到时，应联系创建人处理。

管理员可登录 企业微信管理后台的应用管理页，在应用管理 → 自建 → 消息推送中检查启停状态和“可创建消息推送的成员”。未登录时该地址会先跳转到扫码登录页。

配置步骤

电脑端创建

1. 打开需要接收通知的内部群聊。
2. 点击右上角 ...，进入消息推送 → 添加。
3. 选择创建新的自定义消息推送；也可以添加企业内已经发布的消息推送。
4. 填写名称、头像等页面要求的信息并完成创建。
5. 进入刚创建的消息推送详情，复制完整的 Webhook URL。
6. 将 Webhook 写入服务端密钥存储，先发送一条最小文本消息。

手机端创建

1. 打开目标内部群聊。
2. 进入右上角三个点 → 消息推送 → 添加。
3. 创建消息推送并保存。
4. 进入消息推送 → 对应消息推送 → Webhook 地址查看地址。

手机端可以新建消息推送，但企业微信帮助中心说明：已经“发布到企业”的消息推送仅支持在电脑端添加。

可选：发布给企业内其他群复用

创建人可在原内部群中进入消息推送 → 对应消息推送 → 发布到企业。发布后，同事可以在其他内部群添加它。发布是复用配置，不会让外部群获得该能力。

Web 页面能否完成配置

群绑定和创建目前没有公开的独立 Web 配置地址，必须从企业微信电脑端或手机端的群聊入口完成。下面两个 Web 页面用途不同：

• 企业微信管理后台：应用管理：供管理员控制消息推送应用的启停和可创建成员范围，不能替代群内添加。
• 企业微信帮助中心：如何设置“消息推送”：查看官方操作路径、支持群类型和权限排查，不是配置控制台。

外部群与客户群怎么办

外部群暂不支持添加消息推送，Web 管理后台也不能绕过这一限制。若需求是向客户群发送运营通知，可评估官方的创建企业群发接口，但它与实时机器人有明显区别：

• 请求使用 externalcontact/add_msg_template，客户群场景设置 chat_type=group。
• 接口只创建群发任务，不会直接把消息发到客户群，需要指定成员确认后发送。
• 客户群场景必须提供 sender；chat_id_list 一次最多指定 2000 个客户群。
• 每位客户或每个客户群每月最多接收的群发条数默认为当月天数，企业可按官方规则调整。
• 调用需要使用已配置到“可调用应用”列表中的自建应用 Secret 获取 Token，并受应用可见范围约束。

因此，告警、故障通知等需要实时自动投递的场景，不应把“企业群发”当作等价替代方案。

凭据说明

字段	必需	说明
WEBHOOK_KEY	是	Webhook 查询参数中的 Key，视为密钥
WEBHOOK_URL	是	https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=...

Webhook 与创建的消息推送绑定。删除或停用消息推送后，应同时停止调用并清理保存的地址。

最小请求

JavaScript 示例需要 Node.js 20 或更新版本；Python 示例需要安装 requests。

curl

curl -X POST 'https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=WEBHOOK_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"msgtype":"text","text":{"content":"通知渠道连通性测试"}}'

JavaScript

const url = new URL('https://qyapi.weixin.qq.com/cgi-bin/webhook/send');
url.searchParams.set('key', process.env.WEBHOOK_KEY);
const response = await fetch(url, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    msgtype: 'text',
    text: { content: '通知渠道连通性测试' },
  }),
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
const result = await response.json();
if (result.errcode !== 0) throw new Error(JSON.stringify(result));
console.log(result);

Python

import os
import requests

response = requests.post(
    "https://qyapi.weixin.qq.com/cgi-bin/webhook/send",
    params={"key": os.environ["WEBHOOK_KEY"]},
    json={"msgtype": "text", "text": {"content": "通知渠道连通性测试"}},
    timeout=15,
)
response.raise_for_status()
result = response.json()
if result.get("errcode") != 0:
    raise RuntimeError(result)
print(result)

验证结果

响应中的 errcode 应为 0，并且目标群出现测试消息。只看到 HTTP 200 不代表业务成功，调用方还必须检查响应 JSON。

消息没有出现在群里时，按以下顺序排查：Webhook 是否属于当前群中的消息推送、消息推送是否被移除或停用、群是否开启全员禁言、请求体是否符合对应消息类型。官方帮助中心说明，群开启全员禁言时消息推送也可能无法发出。

消息类型与限制

官方配置说明当前列出 8 种类型：text、markdown、markdown_v2、image、news、file、voice、template_card。常用限制包括：

• text.content 最长 2048 字节，必须使用 UTF-8。
• markdown 和 markdown_v2 内容最长 4096 字节。
• 每个消息推送每分钟不能超过 20 条消息。
• 官方配置说明描述了文本和 Markdown 的成员提醒语法，但帮助中心 FAQ 又写明暂不支持通过消息推送 @ 成员。两处官方资料存在差异，依赖提醒效果前应在实际企业和客户端版本中验证。

安全建议

• 不在浏览器端、公开仓库、截图、工单或日志中暴露完整 Webhook URL。
• 使用密钥管理服务或受控环境变量保存地址，并限制读取主体。
• 不把真实 Webhook 粘贴到在线调试网站；本地测试也应避免进入 Shell 历史。
• 地址泄露后，应移除原消息推送并重新创建，不能只修改调用方变量名。
• 为调用方设置速率限制和失败退避，不要在超限时无限重试。

常见问题

群里没有“消息推送”入口：确认它是内部群；升级客户端；检查“仅群主管理”；请管理员检查应用是否停用以及当前账号是否在可创建成员范围。

外部群能否通过 Webhook 或 Web 后台添加：不能。官方帮助中心明确写明外部群暂不支持添加消息推送，Web 后台只能做企业级管理，不能改变群类型限制。

invalid webhook url：检查完整地址和 Key 是否被截断、消息推送是否被移除或停用。

HTTP 成功但业务失败：检查响应 JSON 的 errcode 和 errmsg，不要只判断 HTTP 状态码。

消息格式错误：msgtype 必须与同名消息对象一致，例如 msgtype=text 时必须提交 text 对象。

频率限制：单个消息推送每分钟不超过 20 条；按返回码退避，并在业务侧合并重复告警。

官方资料

• 企业微信帮助中心：如何设置“消息推送”
• 企业微信开发者中心：消息推送配置说明
• 企业微信开发者中心：创建企业群发