JavaScript events, media, and files

This page covers event fields, sender.getMediaItems(), file downloads, and group member lists. When handling user-uploaded files, prefer normalized MediaItem objects and do not manually assemble platform download URLs.

Event methods

Method	Purpose	Parameters	Returns
`getPluginName()`	Get the current plugin title; returns the plugin name when no title exists.	None	`Promise<string>`
`getPluginVersion()`	Get the current plugin version.	None	`Promise<string>`
`getEventType()`	Get the current event type.	None	`Promise<string>`
`setEventType(eventType)`	Set the event type in the current runtime context.	`eventType`: required.	`Promise<boolean>`
`getEventData()`	Get current event data. Returns `{}` when absent.	None	`Promise<any>`
`setEventData(eventData)`	Set current event data.	`eventData`: required, any JSON-like data.	`Promise<boolean>`
`getMediaItems()`	Get media items from the current event or latest waited input.	None	`Promise<MediaItem[]>`

`getMediaItems()`

getMediaItems() lookup order:

last_input_media_items: media captured by the latest listen(...) / input(...).
media_items / mediaItems: media array in the current runtime context.
event_data.media_items / event_data.mediaItems: media array in current event data.
Returns [] when none exist.

Each object in the returned array is normalized to:

type

string

required

Media type, such as image, voice, video, or file. Only media items that have both type and source are kept.

source

string

required

Media source. It may be a URL, local path, platform file ID, temporary resource ID, or adapter file identifier.

name

string

Filename. The runtime chooses from name, filename, and file_name.

mime_type

string

MIME type. The runtime chooses from mime_type or mimeType.

platform_payload

object

Adapter raw file information. Keeping it improves adapter resolution success when downloading user-uploaded files.

[
  {
    "type": "file",
    "source": "file_123",
    "name": "card_keys.csv",
    "mime_type": "text/csv",
    "platform_payload": {
      "file_id": "file_123",
      "group_id": "123456"
    }
  }
]

const items = await sender.getMediaItems()
const image = items.find((item) => item.type === 'image')
const file = items.find((item) => item.type === 'file')

if (image) {
  await sender.replyImage(image.source, { filename: image.name, mimeType: image.mime_type })
}

if (file) {
  const saved = await downloadAdapterFile(file, { path: 'uploads' })
  await sender.reply(`File saved to ${saved.path}`)
}

Do not discard platform_payload before downloading. Some adapters need it to resolve platform file IDs into temporary download URLs.

`fileDownload(url, path?)`

Save a remote URL, file://, base64://..., or data:*;base64,... to a local file.

url

string

required

File source. Supports http://, https://, file://, base64://..., and data URI.

path

string

Save directory. If omitted, saves to the runtime download root. Relative paths are placed under the download root. Absolute paths are used as-is. Relative paths cannot escape the download root.

const file = await fileDownload('https://example.com/report.csv', 'reports')
await sender.replyFile(file.path, { filename: file.file_name, mimeType: file.mime_type })

Return value:

{
  "path": "/opt/autclaw/file/reports/report.csv",
  "file_path": "/opt/autclaw/file/reports/report.csv",
  "file_name": "report.csv",
  "mime_type": "text/csv",
  "file_size": 12345
}

`downloadAdapterFile(file, options?, timeout?)`

Download a file uploaded by a user to an IM platform. Prefer passing the whole MediaItem returned by sender.getMediaItems().

file

MediaItem | object | string

required

User-uploaded file item. An object can contain source, url, file_id, id, file, path, or platform_payload. A string is treated as the file source. If you only have a normal URL, you can also call fileDownload(url) directly.

options.path

string

Save directory. Same rules as fileDownload(..., path).

options.fileName

string

Saved filename. You can also write file_name, filename, or name.

options.mimeType

string

MIME type. You can also write mime_type.

options.imType

string

Optional IM type. You can also write imtype or im_type. If omitted, the current runtime context is used.

options.account_id

string

Optional account ID. You can also write accountID or accountId. If omitted, the current runtime context account is used.

timeout

number

default:"30000"

Request timeout in milliseconds. You can also pass a number directly as the second parameter, such as downloadAdapterFile(file, 60000).

Download flow

If source is already http://, https://, data:, base64://, or file://, the runtime downloads it directly.
If source is a platform file ID or another identifier that cannot be downloaded directly, the runtime calls adapter resolveFileURL.
After successful download, it saves the file to the runtime file directory and returns the local path.

const items = await sender.getMediaItems()
const fileItem = items.find((item) => item.type === 'file')

if (fileItem) {
  const saved = await downloadAdapterFile(fileItem, {
    path: 'imports',
    fileName: fileItem.name || 'upload.bin',
    mimeType: fileItem.mime_type,
  })
  await sender.reply(`Saved: ${saved.file_name}`)
}

Return value:

{
  "ok": true,
  "action": "resolveFileURL",
  "url": "https://adapter.example/temp/file.csv",
  "path": "/opt/autclaw/file/imports/file.csv",
  "file_path": "/opt/autclaw/file/imports/file.csv",
  "file_name": "file.csv",
  "mime_type": "text/csv",
  "file_size": 2048
}

boolean

true when downloadAdapterFile(...) succeeds.

action

string

Usually resolveFileURL if an adapter was called to resolve the download URL first. It may be empty for direct downloads.

url

string

Actual download URL or resolved temporary URL.

path

string

Saved local path.

file_path

string

Same as path.

file_name

string

Saved filename.

mime_type

string

MIME type.

file_size

number

File size in bytes.

`getGroupMemberList(groupIDOrOptions?, options?, timeout?)`

Get a group member list. The adapter must support getGroupMemberList.

const result = await getGroupMemberList('123456', {
  imType: 'qq',
  account_id: 'bot_qq_ops',
  noCache: true,
})

for (const member of result.members) {
  console.log(member.user_id, member.display_name)
}

groupIDOrOptions

string | object

A string means group ID. An object can contain group_id, groupID, groupCode, group, chat_id, imType, account_id, and other fields. If no group ID is passed, the runtime tries to use the current group chat context.

options.imType

string

Target IM type. You can also write im_type. If omitted, the current context IM is used. Cron / fake contexts must pass it.

options.account_id

string

Target account ID. You can also write accountID or accountId. If omitted, the current context account or target IM default account is used.

options.noCache

boolean

Whether to bypass adapter cache. You can also write no_cache.

options.raw

boolean

Whether to include raw member data in each member object. You can also write includeRaw or include_raw.

options.rawResult

boolean

Whether to include the adapter raw result in returned raw / data. You can also write raw_result or includeRawResult.

timeout

number

default:"30000"

Request timeout in milliseconds.

Return value:

{
  "ok": true,
  "im_type": "qq",
  "account_id": "bot_qq_ops",
  "group_id": "123456",
  "members": [
    {
      "group_id": "123456",
      "user_id": "10001",
      "nickname": "Alice",
      "card": "Alice A.",
      "display_name": "Alice A.",
      "role": "member",
      "join_time": 1710000000,
      "last_sent_time": 1710003600
    }
  ],
  "raw": {},
  "data": {}
}

boolean

true when the list is fetched successfully.

im_type

string

Actual requested IM type.

account_id

string

Actual requested account ID. It may be empty if not specified.

group_id

string

Actual requested group ID.

members

GroupMember[]

Normalized member array.

raw

unknown

Contains the adapter raw result only when rawResult / raw_result / includeRawResult is passed.

JavaScript events, media, and files

Event methods

`getMediaItems()`

`fileDownload(url, path?)`

`downloadAdapterFile(file, options?, timeout?)`

Download flow

`getGroupMemberList(groupIDOrOptions?, options?, timeout?)`

Next steps

Send media

Proactive push

​Event methods

​getMediaItems()

​fileDownload(url, path?)

​downloadAdapterFile(file, options?, timeout?)

​Download flow

​getGroupMemberList(groupIDOrOptions?, options?, timeout?)

​Next steps

Send media

Proactive push

Event methods

`getMediaItems()`

`fileDownload(url, path?)`

`downloadAdapterFile(file, options?, timeout?)`

Download flow

`getGroupMemberList(groupIDOrOptions?, options?, timeout?)`

Next steps