mirror of
https://github.com/langbot-app/LangBot.git
synced 2026-10-30 04:15:45 +08:00
79 lines
3.1 KiB
Plaintext
79 lines
3.1 KiB
Plaintext
---
|
|
title: "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
|
|
|
|
```python
|
|
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.
|
|
|
|
```python
|
|
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:
|
|
|
|
```python
|
|
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`.
|
|
|
|
## Calling from an event processor
|
|
|
|
Runner can also call these platform APIs through `self.plugin`, specifying the bot and target explicitly. To use the current event grants and record actions in its run trace, use `ctx.api` or `ctx.reply()`:
|
|
|
|
```python
|
|
tools = {tool.tool_name for tool in ctx.api.get_allowed_tools()}
|
|
if "event_get_actor" in tools:
|
|
actor = await ctx.api.call_tool("event_get_actor", {})
|
|
await ctx.log(str(actor))
|
|
```
|
|
|
|
See [Run Context APIs](/en/plugin/dev/apis/agent-run) for access, permissions, and replies. Event debugging mocks platform tools; `self.plugin.call_platform_api()` in regular components performs real calls.
|