Skip to main content
Proactive push does not depend on the reply target of Sender. You need to specify the target IM, group, or user. For group push, pass groupCode; for private push, pass userID.

​
Function overview

FunctionPurposeParametersReturns
push(imType, groupCode, userID, title, content, options=None, timeout=None)Push text.imType: required; groupCode: group ID, pass "" for private chat; userID: user ID, pass "" for group push; title: title or fallback text; content: text.int, number of successfully sent targets, usually 0 or 1.
pushImage(imType, groupCode, userID, title, imageUrl, options=None, timeout=None)Push an image.First four parameters are the same; imageUrl: image source; options: optional media parameters.int
pushVoice(imType, groupCode, userID, title, voiceUrl, options=None, timeout=None)Push voice/audio.voiceUrl: voice source; options: optional media parameters.int
pushVideo(imType, groupCode, userID, title, videoUrl, options=None, timeout=None)Push a video.videoUrl: video source; options: optional media parameters.int
pushFile(imType, groupCode, userID, title, fileUrl, options=None, timeout=None)Push a file.fileUrl: file source; options can pass account, filename, and MIME type.int
pushMixed(imType, groupCode, userID, title, items, options=None, timeout=None)Push a mixed message.items: mixed items; options: optional account parameters.int

​
push(...)

​
imType
str
required
Target IM type, such as qq, weixin, or qx, depending on enabled adapters.
​
groupCode
str
required
Group ID. Required for group push; pass an empty string for private push.
​
userID
str
required
User ID. Required for private push; can be empty for group push.
​
options.account_id
str
Target account ID. Also accepted as accountID or accountId. Explicit values have highest priority.
​
timeout
int
Request timeout. Pass milliseconds.
from middleware import push

sent = push("qq", "123456", "", "Daily report", "Today's tasks are complete", {
    "account_id": "bot_qq_ops",
})

if sent == 0:
    print("Not sent: check target, adapter status, or whether the account is online")

​
Push account selection

These rules apply to push(...), pushImage(...), pushVoice(...), pushVideo(...), pushFile(...), and pushMixed(...). Selection rules:
  1. If options contains account_id, use it.
  2. If this is a message trigger and the target IM is the same as the current chat IM, use the current chat account by default.
  3. If this is cron / fake, use the target IM default account.
  4. For cross-IM push, use the target IM default account.
  5. If the target IM has no default account, the runtime chooses the first online account that can send. If no account can send, it returns 0 or raises an adapter offline error.
When you know the sending account, pass options.account_id explicitly. It is more stable than depending on the current chat account or target IM default account.

​
Media push

from middleware import pushImage, pushVoice, pushVideo, pushFile, pushMixed

pushImage("qq", "123456", "", "Daily image", "./daily.png", {
    "account_id": "bot_qq_ops",
})
pushVoice("qq", "123456", "", "Voice reminder", "./notice.wav", {
    "accountId": "bot_qq_ops",
}, 15000)
pushVideo("qq", "123456", "", "Demo video", "./demo.mp4", {
    "account_id": "bot_qq_ops",
})
pushFile("qq", "123456", "", "Daily file", "./daily.csv", {
    "account_id": "bot_qq_ops",
    "filename": "daily.csv",
    "mimeType": "text/csv",
})
pushMixed("qq", "123456", "", "Result", [
    {"type": "text", "text": "Result:"},
    {"type": "image", "source": "./result.png"},
], {
    "account_id": "bot_qq_ops",
})
All proactive push helpers support options and timeout. Use options.account_id / accountID / accountId to choose the sending account explicitly. Use filename / fileName / file_name and mimeType / mime_type to add media metadata.

​
Return value

Proactive push returns the number of successfully sent targets, usually 0 or 1. If the adapter returns an error, the SDK raises Exception. 
try:
    sent = push("qq", "123456", "", "Notice", "Task complete")
    if sent == 0:
        print("No available account or target unreachable")
except Exception as error:
    print(error)

​
Next steps

Last modified on June 3, 2026