加载中…

推送通知API

让你的业务系统通过 API,把到期提醒、账单通知、发货进度等消息推送到客户的企微群或 QQ 群。平台负责找到目标群、排队发送,并记录每个群的投递结果。

本功能适用于专业版 / 旗舰版(Pro / Ultra),支持纯文本(可包含链接)、@姓名,以及最多 10 个附件(图片、文件、链接卡片)。业务系统负责判断何时提醒并提交通知,平台不会自行计算合同到期日或自动触发提醒。

开通与使用步骤

  1. 创建 API 密钥:进入 外部拓展 → API 设置,创建一个供业务系统调用的密钥。密钥应保存在业务系统后端。
  2. 开启推送通知:进入 系统设置 → 开放 API 权限,打开「推送通知」,勾选允许使用的 API Key 并保存。
  3. 设置推送时段:在系统设置的「允许推送时段」中配置,按北京时间执行。默认是 09:00–11:00、14:00–17:00;删除全部时段表示随时可发。
  4. 绑定客户群:进入 合作管理,在「合作公司」导入客户信息,再到「群管理」自动匹配或手工绑定公司。按公司发送时,该公司绑定的全部目标群都会收到通知;也可以由业务系统直接指定一个群。
  5. 开通 QQ 群主动推送:使用 QQ 渠道时,请群主在群内打开「机器人主动在群聊内发言」,再到「群管理」进行检测。操作详见 QQ机器人。
  6. 让业务系统发送通知:完成 API 对接后,由业务系统提交通知。普通通知在允许时段内排队发送,紧急通知不受时段限制,但仍受发送额度和频控限制。

查看结果与补发

进入 合作管理 → 投递记录,按公司名、群名或业务消息号查找,查看各群的发送状态:

  • 排队中:等待推送时段、实例恢复在线或可用发送额度。
  • 已发送:平台已成功发送到该群。
  • 失败 / 已跳过:查看该行原因,先处理实例离线、机器人不在群或 QQ 主动推送未开通等问题;带附件的通知部分送达时会显示「附件未送达(已送达 N/M)」。
  • 已撤回:通知被撤回后尚未发出的群显示为已撤回。

「后续检测」只重置群状态,由下一条真实通知验证;QQ「实时检测」会当场向群里发送一条测试消息。

可补发的记录会显示「重投」,点击后按推送时段重新排队;带附件的通知重投时只补发未送达的部分。所属通知已撤回的记录显示「不可重投」。若上次发送结果不确定,请先到群里核实,避免客户收到重复消息。

企微的消息群发与推送通知共用每日发送额度。额度不足时,通知会顺延。关闭「推送通知」后,已排队但尚未发出的通知也会停止,重新开启后不会自动恢复。

消息里如何 @ 联系人

在姓名前写 @,姓名后加空格,例如:如需续费请联系@张三 ,谢谢!。姓名后连写标点或其他文字可能无法识别;未找到联系人或存在同名歧义时,保留原文发送,并在投递记录中显示提醒。

QQ 提及需要联系人在本群有发言记录。若未能提及,可参考 QQ机器人 中的消息模式与身份绑定说明。

在通知里带附件

一条通知最多带 10 个附件,通过请求体的 attachments 数组提交;带附件时 text 可以省略:

  • { "type": "image", "url": "…" }:图片,url 与 base64 二选一,file_name 可选。
  • { "type": "file", "url": "…", "file_name": "…" }:文件,url 与 base64 二选一,file_name 必填(最长 100 个字符)。
  • { "type": "link", "title": "…", "url": "…" }:链接卡片,title 最长 64 个字符,description(≤ 200 个字符)与 image_url 可选;url 与 image_url 各不超过 1024 个字符。

图片支持 jpg / jpeg / png / gif / webp / bmp,单个不超过 10MB;文件支持 pdf / doc / docx / xls / xlsx / ppt / pptx / txt / csv / zip / rar,单个不超过 20MB。平台按文件实际内容判断类型,改扩展名无效;可执行文件一律拒绝。被拒绝的请求返回 400 attachment_rejected(reason 说明原因),且不占用 biz_msg_id,修正后可用同一个键重新提交。

完整请求示例:

{
  "biz_msg_id": "renew-ACME01-2026-10-24-d7",
  "target": { "company_code": "ACME01" },
  "text": "贵司服务将于 7 天后到期,续费资料见附件。",
  "attachments": [
    { "type": "file", "url": "https://example.com/quote.pdf", "file_name": "续费报价单.pdf" },
    { "type": "link", "title": "在线续费", "url": "https://example.com/renew" }
  ]
}

企微群里会逐条发出原生的图片、文件和链接卡片(正文在前);QQ 群里则把正文和全部附件合成一条消息——图片与文件写成下载链接,链接卡片写成「标题:链接」,下载得到的文件名就是你给的 file_name。

目标含 QQ 群时,平台会按合成后的纯文本计算长度,超过 2000 字受理时就返回 400 qq_message_too_long(带实际长度),不会截断正文、也不会丢附件;目标只有企微群时不做这项校验。

指定群并在开头 @ 成员

除按公司发送外,也可以用会话串直接指定群,写在 target.conversation:

  • 企微群:R:{群ID}@{成员ID}@{成员ID}
  • QQ 群:{group_openid}@{成员ID}(不带 R: 前缀)
  • 多个群:用英文分号 ; 连接,如 R:{群ID}@{成员ID};R:{群ID}@{成员ID},一条消息推到多个群

平台按格式判断渠道(没写 channel 时以 R: 开头一律按企微群处理,QQ 群串误加 R: 会被当成企微群查找,通常返回 404);显式给了 channel 但与格式不符会报错。成员最多 20 个,不能有空段、重复或空白,并且与公司代码、公司全称、按群三种定位方式互斥。写不出合法格式或找不到这个群时分别返回 400 validation_error 与 404 room_not_found。示例里的 ID 均为占位,请换成你自己的:

{ "biz_msg_id": "notice-001", "target": { "conversation": "R:1078xxxxxxxxxxxx@1688xxxxxxxxxxxx" }, "text": "请查收本周对账单。" }

多个群时注意:

  • 最多 20 个群,整串不超过 4096 个字符;开头、结尾或连续多写的分号会自动忽略(R:1078xxx@1688xxx; 与不带分号等价)。
  • 每个群各自按上面的规则校验,出错时提示会写明是第几个群;同一个群写两次会报错。企微群和 QQ 群可以写在一起。
  • 每个群只 @ 自己那一段写的成员,各群各发一条。
  • 某个群找不到时跳过这个群,其余照常发送,返回结果的 unresolved 会列出被跳过的群;全部都找不到才返回 404 room_not_found;找到的群又全部无法推送(机器人不在群或未开放主动推送)时按原规则返回 409 all_targets_skipped,同样带上 unresolved。

会话串里的成员会在正文那一条消息的开头依次被 @(企微在群内 @,QQ 按出站提及格式),之后紧接正文,只发一条;正文里的 @姓名 照常解析,同一成员只 @ 一次。成员 ID 不在群内时消息照常发送,并在回执的 warnings 里记一条提醒;QQ 实例关闭 markdown 时会放弃提及。带附件时 @ 只附在正文那一条上,没有正文时开头只含 @。

撤回通知

通知还没发出去的部分可以撤回:

  • 业务系统:调用 POST /api/v1/notifications/{biz_msg_id}/cancel,请求体可带 reason(≤ 200 字)。接口幂等,重复撤回不会改变第一次的记录。
  • 运营人员:在 合作管理 → 投递记录 点某行的小眼睛打开通知预览,在预览里撤回整条通知,可选填原因。

撤回只取消尚未发出的群,已经发出的群无法撤回;排队中的群变为「已撤回」,部分送达的会保留「已送达 N/M」。撤回后整条通知作废,其中失败的群也不能再重投。撤回后用同一个 biz_msg_id 再提交,只会返回原来的回执;要重新发送请换一个新的 biz_msg_id。

请求体大小与并发

下发接口的请求体上限是 85MB,超限返回 413 payload_too_large。同一企业同时处理的大请求(超过 2MB)最多 4 个,超出返回 429 too_many_large_requests,稍后重试即可。同一个 biz_msg_id 并发提交时,后到的请求可能返回 409 notification_in_progress,稍等再查回执。

同一个 biz_msg_id 重复提交不会重复发送,返回 duplicate: true 和原受理结果:其中 summary 是首次受理时的快照,排队数不会随发送进展变化,不要拿它判断是否已发出;实时状态以返回中的 deliveries[].status 或回执查询 GET /api/v1/notifications/{biz_msg_id} 为准。

API 文档

完整接口、参数及调用示例:https://agent.likelic.com/doc/v1/#section-outbound