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.

Send messages, replies, and threads

The standard send_message API returns a MessageResult, whose message_id identifies the sent message when the platform provides one. self.plugin.send_message() returns its serialized dictionary, so read result["message_id"] rather than an object attribute. The ID may be None or empty when the platform does not return one.

Use the standard Quote component to express a reply or thread reference in a message chain. Quote.id is the referenced message or thread root ID; origin is the quoted message chain and may be empty. Support and reply/thread behavior depend on the adapter. For example, Slack returns the message ts as message_id, sends a chain with Quote(id=ts) into that thread, and appends Quote(id=thread_ts) to inbound channel thread replies. This uses standard message APIs, not a Slack-specific action.

from langbot_plugin.api.entities.builtin.platform.message import MessageChain, Plain, Quote

result = await self.plugin.send_message(
    bot_uuid=bot_uuid,
    target_type="group",
    target_id=group_id,
    message_chain=MessageChain([Plain(text="Support request")]),
)
message_id = result.get("message_id") if result else None
if message_id is not None and message_id != "":
    await self.plugin.send_message(
        bot_uuid=bot_uuid,
        target_type="group",
        target_id=group_id,
        message_chain=MessageChain([
            Plain(text="Follow-up"),
            Quote(id=message_id, origin=MessageChain([])),
        ]),
    )

Use IDs from the same bot and conversation. Quote preserves reference metadata in serialization but adds no text to str(message_chain), so it does not change command or keyword matching.

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

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))