成为赞助商——支持中文 Agent 生态

了解赞助
库Agent场景库
← 返回用例列表

企微应用消息发送失败分诊

按可见范围/许可、频率限制、重复检查与部分失败字段,生成应用消息推送失败分诊表;不代发生产消息。

企业微信DeepSeekClaudeChatGPT⚡ 效率办公🏢 企业协作

场景说明

面向企业自动化与独立开发者:把企微「接口返回 ok 但人没收到 / 全失败」写成可对账清单,区别于飞书邮件或通用 Webhook。

案例叙事

01他们做了什么

业务说「企微机器人没推到」,研发一看日志却是 errcode=0——其实无效接收人被塞进了 invaliduser,人照样收不到。

企业微信《发送应用消息》说明:应用可经 POST `https://qyapi.weixin.qq.com/cgi-bin/message/send` 推送文本/图片/语音/视频/文件/文本卡片/图文/markdown/小程序通知/模板卡片等。touser/toparty/totag 可组合;touser 最多 1000 人,"@all" 向该应用全部成员发送且忽略部门/标签参数。返回示例可含 invaliduser、invalidparty、invalidtag、unlicenseduser、msgid;部分接收人无权限或不存在时发送仍执行,但返回无效部分——常见原因是接收人不在应用可见范围;权限含应用可见范围与基础接口权限,unlicenseduser 表示在可见范围内但无基础接口许可(含过期)。若全部接收人无权限或不存在则调用失败,errcode 为 81013。频率限制:每应用不可超过账号上限数×200 人次/天(一次发给 1000 人计 1000 人次);每应用对同一成员不可超过 30 次/分钟、1000 次/小时,超过部分丢弃不下发。建议避开每小时 0 分与 30 分高峰调用。enable_duplicate_check 开启后,在 duplicate_check_interval(默认 1800 秒)内同样内容(请求 JSON)不会重复收到。本场景据此输出分诊表。禁止声称「已代发成功」。

02实际效果

  • 源未披露量化「invaliduser 平均占比」;公开文只描述返回字段、81013、限频与重复检查。
  • 能把「接口成功」与「成员实收」拆开对账。
  • 限频与整点挤占有规避提醒,减少静默丢弃。

03值得知道

  • 第三方应用与自建应用的 agentid/授权获取路径不同,以当前文档为准。
  • 限频丢弃可能无单独「已丢弃名单」回包,需结合业务侧对账。
  • 上面写的是文档能力说明,不是你的企微租户实时配额。

04可复制提示词

企微应用消息失败分诊表

你是企微应用消息分诊助手。只根据返回与配置提问,不要编造已发送成功。

接口返回摘要:{{api_response}}
接收人设定:{{audience}}
应用可见范围说明:{{visible_scope}}
发送时段:{{send_time}}

输出 Markdown:
1. 归类(部分无效 / 全失败 81013 / 疑似限频丢弃 / 重复检查未下发)
2. 对照字段(invaliduser/party/tag、unlicenseduser、msgid)
3. 管理端核对提问(可见范围、基础接口许可)
4. 重试与避峰建议
禁止代调 API;禁止索要 corpsecret。

推送未达复盘提纲

业务反馈未收到企微应用消息,请写复盘提纲。

预期接收人:{{expected}}
实际返回:{{actual_response}}
时间线:{{timeline}}

输出:
1. 根因分层(可见范围、许可、限频、重复检查、@all 范围误解)
2. 证据要留什么
3. 临时缓解
4. 防再发
不要伪造「全员已达」。

05一手来源

怎么做

  1. 粘贴接口返回(errcode/invalid*)、接收人类型、应用可见范围说明与发送时段
  2. Agent 按部分失败/全失败/限频丢弃/重复检查输出分诊与提问清单
  3. 人工在企微管理端与业务侧核对;Agent 不代调 message/send

实用提示

  • 返回 ok 仍可能带 invaliduser:部分人不可达,常见原因是不在应用可见范围
  • 与 feishu-mail-* / webhook-signature-verify-fail-triage 不同:本条是企微应用消息发送接口的分诊
#企业微信#应用消息#推送#可见范围#频率限制