Platform APIs
Call platform adapter APIs using a bot UUID. Continue using self.plugin.send_message() for message chains; use the API below for groups, users, and other platform features.
Call a platform API
async def call_platform_api(
self,
bot_uuid: str,
action: str,
params: dict[str, Any] | None = None,
) -> Any:
...Call through self.plugin in Command, EventListener, Tool, and other regular components. Results are serialized dictionaries, lists, scalars, or None, depending on the action, rather than platform SDK objects.
group = await self.plugin.call_platform_api(
bot_uuid=bot_uuid,
action="get_group_info",
params={"group_id": "123456"},
)bot_uuid comes from await self.plugin.get_bots() or await event_context.get_bot_uuid() in a Pipeline event. Use platform IDs from real events or platform configuration.
Common actions
action | params |
|---|---|
get_user_info | user_id |
get_friend_list | {} |
get_group_info | group_id |
get_group_list | {} |
get_group_member_list | group_id |
get_group_member_info | group_id, user_id |
get_message / delete_message | chat_type, chat_id, message_id |
set_group_name | group_id, name |
mute_member | group_id, user_id, duration |
unmute_member / kick_member | group_id, user_id |
leave_group | group_id |
approve_friend_request | request_id, approve, remark |
approve_group_invite | request_id, approve |
get_file_url | file_id |
Supported actions vary by platform and may require bot administrator permissions. duration is in seconds; the meaning of 0 is platform-specific, not a universal permanent mute. Queries may depend on platform caches. Calls raise an exception if the bot is not running, the action is unsupported, or parameters are invalid.
Platform-specific APIs
Set the outer action to call_platform_api and put the platform action and parameters inside params. For example, read the bot account using OneBot Omni:
account = await self.plugin.call_platform_api(
bot_uuid=bot_uuid,
action="call_platform_api",
params={"action": "get_login_info", "params": {}},
)Only actions declared by the adapter are allowed; this is not unrestricted pass-through to every platform endpoint. Plugins call the Host through the runtime, rather than accessing ctx.query.adapter or adapter.bot.
Runner
During Runner execution, model, tool, knowledge-base, storage, and platform calls through self.plugin automatically use the current run and its authorization. Do not pass run_id. Concurrent runs remain isolated. Do not continue these run-bound calls after the handler returns.
Use await ctx.get_bot_uuid() for the current bot. Platform calls must match the tool grants for this invocation. Event-target grants cannot access another target. Ungranted actions, including platform-specific actions, are rejected. These calls also use Mock delivery in debug mode.
tools = await ctx.get_available_tools()
if any(tool["name"] == "event_get_actor" for tool in tools):
actor = await ctx.call_tool("event_get_actor")
await ctx.log(str(actor))