Skip to main content
主动推送不依赖 Sender 的回复目标。你需要指定目标 IM、群或用户。群推送传 groupCode;私聊推送传 userID

函数总览

push(imType, groupCode, userID, title, content, options?, timeout?)

string
必填
目标 IM 类型,例如 qqweixinqx,以已启用适配器为准。
string
必填
群 ID / 群号。群推送必填;私聊传空字符串。
string
必填
用户 ID。私聊推送必填;群推送可传空字符串。
string
必填
推送标题或备注。文本推送中如果 content 为空,会用 title 作为文本。
string
必填
文本内容。运行时也兼容 text / message 字段,但 helper 固定传 content
object
可选扩展字段。middleware.js 会把该对象浅合并到顶层请求体。
string
目标账号 ID。也可写作 accountIDaccountId。显式传入时优先级最高。
number
默认值:"5000"
请求超时时间,单位毫秒。

推送账号选择

以下规则适用于 push(...)pushImage(...)pushVoice(...)pushVideo(...)pushFile(...)pushMixed(...) 选择规则:
  1. 如果 options 中有 account_id,使用它。
  2. 如果是消息触发,并且目标 IM 与当前会话 IM 一致,默认使用当前会话账号。
  3. 如果是 cron / fake,使用目标 IM 的默认账号。
  4. 如果跨 IM 推送,使用目标 IM 的默认账号。
  5. 如果目标 IM 没有默认账号,运行时会选择第一个在线可发送账号;没有可发送账号时返回 0 或抛出适配器离线错误。
能确定发送账号时,优先显式传 options.account_id。这比依赖“当前会话账号”或“目标 IM 默认账号”更稳定。

媒体推送

媒体推送 helper 也支持 optionstimeoutoptions.account_id / accountID / accountId 可显式指定发送账号;filename / fileName / file_namemimeType / mime_type 用于补充媒体元数据。

返回值

主动推送函数返回数字,表示运行时认为发送成功的目标数。
  • 1:通常表示已提交给一个目标。
  • 0:通常表示没有可用适配器、目标无效或未发送。
  • 适配器请求失败时可能抛出 Error

mixed items

pushMixed(...)itemsreplyMixed(...) 相同:支持 textmarkdownimagevoicevideofile

下一步

运行上下文

查看消息、cron、路由和跨 IM 的上下文差异。

媒体文件

查看媒体来源、下载和用户上传文件处理。
最后修改于 2026年6月3日