ErisPulse API Action Standard
Tip
When to read this: When you are implementing Api DSL standard actions (get_user_info / delete_message, etc.) in an adapter, or calling these standard actions across platforms from a module and need to confirm parameters and data fields, refer to this document. Skip it otherwise.
This document defines the unified interface specification for OneBot12 standard API actions in ErisPulse adapters, allowing module developers to program against standard interfaces while adapters are responsible for mapping to platform-native APIs.
Coverage: Among OneBot12 standard actions,
ApiDSLprovides strongly-typed methods for the user / group / guild / message management / Meta regular interfaces (send_messageis handled bySendDSL.Raw_ob12). File resource actions (upload_file/get_file/ fragmented transfer) are kept only as degraded pass-through; see the notes in §3.5. Platform extension actions are invoked via theApi.call("prefix.action", ...)escape hatch. Action parameters and return structures follow the OneBot12 specification (onebot/specs/interface/in the repository).
1. Design Background
In ErisPulse, message segments (message sending/receiving) and event formats already fully follow the OneBot12 standard, but API action calls (such as getting user info, getting the group list, recalling messages, etc.) were previously not unified—module developers had to write different call_api calls for each platform.
ApiDSL solves this problem by providing strongly-typed standard action methods:
Module code (cross-platform unified) Adapter implementation (platform-specific)
───────────────── ──────────────────
adapter.Api.get_user_info("123") → Adapter call_api / override
adapter.Api.get_group_list() → Adapter call_api / override
adapter.Api.delete_message("id") → Adapter call_api / override
2. Three Parallel DSL Layers
ErisPulse adapters have three parallel DSL inner classes, each with its own responsibility:
BaseAdapter
├── Send(SendDSL) ← Message sending (Text/Image/Raw_ob12)
├── Request(RequestDSL) ← Request handling (accept/reject)
└── Api(ApiDSL) ← Standard API actions (user/group/guild/message management/file/meta) ★
| DSL | Responsibility | Method Style | Return Value |
|---|---|---|---|
Send |
Sending messages | Chained + asyncio.Task |
Standard response |
Request |
Handling request events | asyncio.Task |
Standard response |
Api |
Query/management operations | async methods |
Standard response |
3. Standard Action List
3.1 User-Related
| Method | OB12 Action | Parameters | data Returns |
|---|---|---|---|
get_self_info() |
get_self_info |
None | user_id, user_name, user_displayname |
get_user_info(user_id) |
get_user_info |
user_id: str |
user_id, user_name, user_displayname, user_remark |
get_friend_list() |
get_friend_list |
None | list[get_user_info response] |
3.2 Group-Related
| Method | OB12 Action | Parameters | data Returns |
|---|---|---|---|
get_group_info(group_id) |
get_group_info |
group_id: str |
group_id, group_name |
get_group_list() |
get_group_list |
None | list[get_group_info response] |
get_group_member_info(group_id, user_id) |
get_group_member_info |
group_id: str, user_id: str |
user_id, user_name, user_displayname |
get_group_member_list(group_id) |
get_group_member_list |
group_id: str |
list[get_group_member_info response] |
set_group_name(group_id, group_name) |
set_group_name |
group_id: str, group_name: str |
None |
leave_group(group_id) |
leave_group |
group_id: str |
None |
3.3 Message Management
| Method | OB12 Action | Parameters | Description |
|---|---|---|---|
delete_message(message_id) |
delete_message |
message_id: str |
Recall/delete a message |
Sending messages (
send_message) is handled bySendDSL'sRaw_ob12and is not duplicated inApiDSL.
3.4 Guild-Related
The OneBot12 guild system has two levels: guild and channel.
| Method | OB12 Action | Parameters | data Returns |
|---|---|---|---|
get_guild_info(guild_id) |
get_guild_info |
guild_id: str |
guild_id, guild_name |
get_guild_list() |
get_guild_list |
None | list[get_guild_info response] |
set_guild_name(guild_id, guild_name) |
set_guild_name |
guild_id: str, guild_name: str |
None |
get_guild_member_info(guild_id, user_id) |
get_guild_member_info |
guild_id: str, user_id: str |
user_id, user_name, user_displayname |
get_guild_member_list(guild_id) |
get_guild_member_list |
guild_id: str |
list[get_guild_member_info response] |
leave_guild(guild_id) |
leave_guild |
guild_id: str |
None |
get_channel_info(guild_id, channel_id) |
get_channel_info |
guild_id: str, channel_id: str |
channel_id, channel_name |
get_channel_list(guild_id, *, joined_only) |
get_channel_list |
guild_id: str, joined_only: bool=false |
list[get_channel_info response] |
set_channel_name(guild_id, channel_id, channel_name) |
set_channel_name |
guild_id, channel_id, channel_name |
None |
get_channel_member_info(guild_id, channel_id, user_id) |
get_channel_member_info |
guild_id, channel_id, user_id |
user_id, user_name, user_displayname |
get_channel_member_list(guild_id, channel_id) |
get_channel_member_list |
guild_id, channel_id |
list[get_channel_member_info response] |
leave_channel(guild_id, channel_id) |
leave_channel |
guild_id, channel_id |
None |
The guild system and groups are independent of each other: platforms such as Discord / QQ Guild / Kook implement the guild interfaces, while traditional QQ / WeChat implement the group interfaces; the two may coexist or only one of them may exist.
3.5 File Resource Operations
Warning
The file resource model (two-stage file_id) is "degraded availability" in ErisPulse:
File sending/receiving in ErisPulse does not follow the "upload first to get a file_id, then reference it" model—modules send files with
SendDSL.File(file, filename) (URL / path / bytes are transmitted directly at send time, see the
Send Method Specification).
The upload_file / get_file / fragmented transfer actions in this section depend on the platform-specific file_id file resource
capability, which is not universally applicable; they may only be passed through when the adapter backend natively provides this capability. Built-in framework
adapters do not implement and are not recommended to implement them, and calls typically return retcode=10002.
When a module needs to transfer files across platforms, use SendDSL.File and do not rely on file_id.
Outlook: Standardizing the file_id resource model at the framework layer is a future direction; the current version does not provide it.
Whole-file transfer (small files):
| Method | OB12 Action | Parameters | data Returns |
|---|---|---|---|
upload_file(*, type, name, ...) |
upload_file |
type, name, url/path/data, headers?, sha256? |
file_id |
get_file(file_id, type) |
get_file |
file_id: str, type: str |
name, url/path/data |
The type parameter of upload_file:
"url": Upload via URL (urlmust be provided)"path": Upload via local path (pathmust be provided)"data": Upload via binary data (datamust be provided)
3.5.1 Fragmented Transfer (Large Files, Within the Degraded Scope Above)
OneBot12 fragmented actions distinguish phases by stage. ApiDSL splits the three/two phases of the same action into separate methods
(offset is the byte offset, and data is Base64 in JSON); the tables below are kept for reference only.
Adapters do not need to and should not force-implement them:
Fragmented upload in three steps: prepare → transfer (looping chunk by chunk) → finish
| Method | Corresponding stage | Parameters | data Returns |
|---|---|---|---|
upload_file_fragmented_prepare(name, total_size) |
prepare |
name: str, total_size: int |
file_id (for use during transfer) |
upload_file_fragmented_transfer(file_id, offset, data) |
transfer |
file_id, offset: int, data: bytes |
None |
upload_file_fragmented_finish(file_id, sha256) |
finish |
file_id, sha256: str (whole-file checksum) |
file_id |
total = os.path.getsize(path)
r = await adapter.Api.upload_file_fragmented_prepare(os.path.basename(path), total)
fid = r["data"]["file_id"]
offset = 0
with open(path, "rb") as f:
while chunk := f.read(65536):
await adapter.Api.upload_file_fragmented_transfer(fid, offset, chunk)
offset += len(chunk)
sha256 = hashlib.sha256(open(path, "rb").read()).hexdigest()
await adapter.Api.upload_file_fragmented_finish(fid, sha256)
Fragmented download in two steps: prepare → transfer (looping to fetch chunks)
| Method | Corresponding stage | Parameters | data Returns |
|---|---|---|---|
get_file_fragmented_prepare(file_id) |
prepare |
file_id |
name, total_size, sha256 |
get_file_fragmented_transfer(file_id, offset, size) |
transfer |
file_id, offset: int, size: int |
data (bytes of the current chunk) |
3.6 Meta Actions
Meta actions do not target a specific account and do not require Using() to specify a Bot.
| Method | OB12 Action | Parameters | data Returns |
|---|---|---|---|
get_latest_events(limit, timeout) |
get_latest_events |
limit: int=0, timeout: int=0 |
Array of event objects (excluding meta events) |
get_supported_actions() |
get_supported_actions |
None | list[str] of supported action names |
get_status() |
get_status |
None | good: bool, bots: list[{self, online, ...}] |
get_version() |
get_version |
None | impl, version, onebot_version |
3.7 Generic Extension Actions
| Method | Description |
|---|---|
call(action, **params) |
Escape hatch for platform extension actions, following the OB12 extension naming rule {prefix}.{action} |
4. Usage
4.1 Basic Calls
from ErisPulse import adapter
# Get user info (cross-platform unified)
result = await adapter.myplatform.Api.get_user_info("123456")
if result["status"] == "ok":
user_name = result["data"]["user_name"]
print(f"Username: {user_name}")
# Get the group list
result = await adapter.myplatform.Api.get_group_list()
groups = result["data"]
# Recall a message
await adapter.myplatform.Api.delete_message("msg_123456")
4.2 Specifying a Bot Account (Multi-Account Mode)
# Perform operations with a specified Bot account
info = await adapter.myplatform.Api.Using("bot1").get_self_info()
4.3 Platform Extension Actions
# Call platform-specific extension actions ({prefix}.{action} naming recommended)
result = await adapter.telegram.Api.call(
"telegram.send_sticker",
sticker_id="CAACAgIAAxkBAA...",
)
4.4 Using in Event Handlers
from ErisPulse.Core.Event import message
@message()
async def handle(event):
# Get sender details
user_id = event.get_user_id()
platform = event.get_platform()
result = await getattr(adapter, platform).Api.get_user_info(user_id)
if result["status"] == "ok":
user_name = result["data"]["user_name"]
await event.reply(f"Hello, {user_name}!")
5. Adapter Implementation
5.1 Default Behavior (Zero Configuration)
The default implementation of ApiDSL passes the standard action name directly to adapter.call_api() as the endpoint:
# Equivalent to the ApiDSL default implementation:
async def get_user_info(self, user_id: str) -> dict:
return await self._adapter.call_api("get_user_info", user_id=user_id, account_id=self._account_id)
Account field: The framework automatically adapts account binding based on how the adapter's
call_apiactually consumes it (standard nameaccount_id; legacy name_account_idautomatically rewritten;params.popin the function body is also recognized). When the field is not consumed, it is stripped to avoid leaking into platform parameters, with a one-time prompt—see Adapter Development - Account Resolution for details on consumption forms.
Applicable scenarios: When the adapter's underlying backend itself follows the OneBot12 standard action protocol,
call_api naturally supports standard action names (e.g., directly connecting to a server that follows this protocol).
5.2 Overriding Standard Methods (Mapping to Platform-Native APIs)
Adapters can override individual standard methods, mapping them to platform-native APIs:
class MyAdapter(BaseAdapter):
class Api(BaseAdapter.Api):
"""MyPlatform standard API action implementation"""
async def get_user_info(self, user_id: str) -> dict:
# Map to the platform-native API
raw = await self._adapter._request("GET", f"/users/{user_id}")
if raw.get("code") != 0:
# Platform-side error: use the low three digits from the 341xx–345xx range (346xx is reserved by the framework, do not occupy it)
return self._adapter.make_error(retcode=34400, message="User not found")
user = raw["data"]
return self._adapter.make_response(
data={
"user_id": str(user["id"]),
"user_name": user.get("nick", ""),
"user_displayname": user.get("display_name", ""),
"user_remark": user.get("remark", ""),
},
raw=raw,
)
async def get_friend_list(self) -> dict:
raw = await self._adapter._request("GET", "/friends")
friends = [
{
"user_id": str(u["id"]),
"user_name": u.get("nick", ""),
"user_displayname": u.get("display_name", ""),
"user_remark": u.get("remark", ""),
}
for u in raw.get("data", [])
]
return self._adapter.make_response(data=friends, raw=raw)
5.3 Unsupported Actions
Standard methods not overridden by the adapter fall back to the default implementation (delegated to call_api). If call_api does not support the action either, it should return a standard error response:
async def call_api(self, endpoint: str, **params):
if endpoint not in self._supported_endpoints:
return self.make_error(retcode=10002, message=f"Unsupported action: {endpoint}")
# ... platform API call
Module developers can determine whether an action is supported via the retcode of the return value:
result = await adapter.myplatform.Api.get_friend_list()
if result["retcode"] == 10002:
print("This platform does not support getting the friend list")
6. Response Format
All ApiDSL methods return the standard API response format (see the API Response Standard for details):
{
"status": "ok",
"retcode": 0,
"data": { ... },
"message_id": "",
"message": "",
"myplatform_raw": { ... }
}
Note: For information query actions,
message_idis an empty string (only message sending actions have amessage_id).
7. Relationship with SendDSL / RequestDSL
| Scenario | DSL to Use | Example |
|---|---|---|
| Sending messages | Send |
adapter.Send.To("group", "123").Text("hi") |
| Accepting/rejecting requests | Request |
adapter.Request("req_id").accept() |
| Getting user/group info | Api |
adapter.Api.get_user_info("123") |
| Recalling messages | Api |
adapter.Api.delete_message("msg_id") |
| Leaving a group | Api |
adapter.Api.leave_group("group_id") |
8. Adapter Implementation Checklist
Standard Actions
-
call_apican handle standard action names (or the correspondingApiDSLmethods are overridden) - Unsupported actions return
retcode=10002 - Return values follow the standard API response format
- The
datafield contains the fields defined by the OB12 standard - Guild platforms need to implement
get_guild_*/get_channel_*/leave_guild/leave_channel - Meta actions (
get_status/get_version/get_supported_actions) are recommended to be implemented - Use
SendDSL.File(direct transfer) for file sending/receiving; file resource actions (upload_file/get_file/fragmented transfer) are not required to be implemented; pass-through is only needed when the backend has thefile_idresource capability
Extension Actions
- Platform extension actions use the
{prefix}.{action}naming - Extension action parameters and responses still follow the OB12 action request/response structure
9. Related Documents
Companion reference when implementing Api DSL return values:
- API Response Standard - Adapter API response format standard
Other DSLs of the same adapter:
- Send Method Specification - Method naming and parameter specification for the Send class
- Request Action Specification - Usage of the Request DSL
Event-side companion:
- Event Conversion Standard - Event format and message segment standard