JavaScript plugin proactive push

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

Function	Purpose	Parameters	Returns
`push(imType, groupCode, userID, title, content, options?, timeout?)`	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; `options`: optional; `timeout`: optional milliseconds.	`Promise<number>`, number of successfully sent targets, usually `0` or `1`.
`pushImage(imType, groupCode, userID, title, imageUrl, options?, timeout?)`	Push an image.	First four parameters are the same; `imageUrl`: required image source; `options`: optional media parameters; `timeout`: optional milliseconds.	`Promise<number>`
`pushVoice(imType, groupCode, userID, title, voiceUrl, options?, timeout?)`	Push voice/audio.	`voiceUrl`: required voice source; `options`: optional media parameters; `timeout`: optional milliseconds.	`Promise<number>`
`pushVideo(imType, groupCode, userID, title, videoUrl, options?, timeout?)`	Push a video.	`videoUrl`: required video source; `options`: optional media parameters; `timeout`: optional milliseconds.	`Promise<number>`
`pushFile(imType, groupCode, userID, title, fileUrl, options?, timeout?)`	Push a file.	`fileUrl`: required file source; `options` can pass account, filename, and MIME type; `timeout`: optional milliseconds.	`Promise<number>`
`pushMixed(imType, groupCode, userID, title, items, options?, timeout?)`	Push a mixed message.	`items`: required mixed items; `options`: optional account parameters; `timeout`: optional milliseconds.	`Promise<number>`

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

string

required

Target IM type, such as qq, weixin, or qx, depending on enabled adapters.

string

required

Group ID / group number. Required for group push; pass an empty string for private chat.

string

required

User ID. Required for private push; group push can pass an empty string.

string

required

Push title or note. In text push, if content is empty, title is used as the text.

string

required

Text content. The runtime also supports text / message fields, but the helper always sends content.

object

Optional extension fields. middleware.js shallow-merges this object into the top-level request body.

string

Target account ID. You can also write accountID or accountId. Explicit values have the highest priority.

number

default:"5000"

Request timeout in milliseconds.

const { push } = require('./middleware.js')

const sent = await push('qq', '123456', '', 'Daily report', 'Tasks done today', {
  account_id: 'bot_qq_ops',
})

if (sent === 0) {
  console.log('Not sent: check the 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:

If options contains account_id, use it.
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.
If this is cron / fake, use the target IM default account.
For cross-IM push, use the target IM default account.
If the target IM has no default account, the runtime selects the first online account that can send. If there is no available sending account, it returns 0 or throws an adapter-offline error.

When you know which sending account to use, pass options.account_id explicitly. This is more stable than depending on the current chat account or target IM default account.

// 1. Explicit account wins.
await push('qq', '123456', '', 'Notice', 'Done', {
  account_id: 'bot_qq_ops',
})

// 2. The message comes from qq:bot_qq_2 and target IM is also qq: bot_qq_2 is used by default.
await push('qq', '123456', '', 'Notice', 'Done')

// 3. cron / fake: use the qq default account.
await push('qq', '123456', '', 'Scheduled notice', 'Good morning')

// 4. Cross-IM: the current message comes from qq but pushes to weixin; use the weixin default account.
await push('weixin', '', 'wxid_user', 'Notice', 'Done')

Media push

await pushImage('qq', '123456', '', 'Daily image', './daily.png', {
  account_id: 'bot_qq_ops',
})
await pushVoice('qq', '123456', '', 'Voice reminder', './notice.wav', {
  accountId: 'bot_qq_ops',
}, 15000)
await pushVideo('qq', '123456', '', 'Demo video', './demo.mp4', {
  account_id: 'bot_qq_ops',
})
await pushFile('qq', '123456', '', 'Daily file', './daily.csv', {
  account_id: 'bot_qq_ops',
  filename: 'daily.csv',
  mimeType: 'text/csv',
})
await pushMixed('qq', '123456', '', 'Result', [
  { type: 'text', text: 'Result:' },
  { type: 'image', source: './result.png' },
], {
  account_id: 'bot_qq_ops',
})

Media push helpers also 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 functions return a number: the count of targets that the runtime considers successfully sent.

1: usually means the message was submitted to one target.
0: usually means no available adapter, invalid target, or not sent.
Adapter request failures may throw Error.

Mixed items

pushMixed(...) items are the same as replyMixed(...): they support text, markdown, image, voice, video, and file.

await pushMixed('qq', '123456', '', 'mixed demo', [
  { type: 'text', text: 'See the image:' },
  { type: 'image', source: 'https://example.com/a.png', name: 'a.png' },
])

Plugin SDK

JavaScript plugin proactive push

Function overview

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

Push account selection

Media push

Return value

Mixed items

Next steps

Runtime context

Media files

​Function overview

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

​Push account selection

​Media push

​Return value

​Mixed items

​Next steps

Runtime context

Media files

Function overview

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

Push account selection

Media push

Return value

Mixed items

Next steps