简体中文 English 繁體中文 日本語 Русский
本文为静态镜像，内容以交互版为准 在交互式文档中心打开 →

ErisPulse PlatformFeatures Documentation

Base Protocol: OneBot12

This document is a platform-specific feature guide, including:

  • Examples of Send method chain calls supported by each adapter
  • Platform-specific event/message format descriptions

General usage methods are referenced in:

Platform-Specific Features

This section is maintained by each adapter developer to document differences and extension features of the adapter compared to the OneBot12 standard. Please refer to the detailed documentation for each platform below:

Additionally, there is a sandbox adapter, but this adapter does not require a platform-specific features documentation.

General Interface

Send Method Chaining

All adapters support the following standard calling methods:

Note: The {AdapterName} in the documentation should be replaced with the actual adapter name (e.g., yunhu, telegram, onebot11, email, etc.).

  1. Specify type and ID: To(type, id).Func()
    # Get adapter instance
my_adapter = adapter.get("{AdapterName}")

# Send message
await my_adapter.Send.To("user", "U1001").Text("Hello")

# Example:
yunhu = adapter.get("yunhu")
await yunhu.Send.To("user", "U1001").Text("Hello")
  2. Specify ID only: To(id).Func()
    my_adapter = adapter.get("{AdapterName}")
await my_adapter.Send.To("U1001").Text("Hello")

# Example:
telegram = adapter.get("telegram")
await telegram.Send.To("U1001").Text("Hello")
  3. Specify sender account: Using(account_id)
    my_adapter = adapter.get("{AdapterName}")
await my_adapter.Send.Using("bot1").To("U1001").Text("Hello")

# Example:
onebot11 = adapter.get("onebot11")
await onebot11.Send.Using("bot1").To("U1001").Text("Hello")
  4. Direct call: Func()
    my_adapter = adapter.get("{AdapterName}")
await my_adapter.Send.Text("Broadcast message")

# Example:
email = adapter.get("email")
await email.Send.Text("Broadcast message")

Asynchronous Sending and Result Handling

The methods of the Send DSL return an asyncio.Task object, which means you can choose whether to wait for the result immediately:

# Get adapter instance
my_adapter = adapter.get("{AdapterName}")

# Do not wait for result, message is sent in the background
task = my_adapter.Send.To("user", "123").Text("Hello")

# If you need to get the sending result, you can wait later
result = await task

Send Rule Decorators

In practical development, you often need to: execute subsequent logic only after successful sending, automatically retry on failure, cancel on timeout, monitor sending progress, etc. The Send DSL includes a set of built-in send rule decorators, which can be attached via chained methods:

Method Description
.Hook(callback) Callback executed after successful sending (can be called multiple times)
.Retry(times=1) Automatic retry N times on failure (total of N+1 attempts including the first)
.Timeout(seconds) Single send timeout, cancel on timeout (can be stacked with Retry)
.Defer(seconds) Delay sending (in-process timer, not persisted)
.OnProgress(callback) Progress callback at each stage, passing in SendContext
.OnError(callback) Error callback on final failure (triggers only once) 
yunhu = adapter.get("yunhu")

# Deduct points only after successful sending
await (yunhu.Send.To("user", "123")
       .Hook(lambda r: deduct_points("123"))
       .Text("Success"))

# Retry on failure + timeout cancellation + progress monitoring
def on_progress(ctx):
    print(f"Stage: {ctx.stage}, Attempt: {ctx.attempt + 1}/{ctx.max_attempts}")

task = (yunhu.Send.To("user", "123")
        .Retry(3)              # Retry up to 3 times
        .Timeout(10)           # Timeout of 10 seconds per attempt
        .OnProgress(on_progress)
        .OnError(lambda ctx: notify_admin(ctx.error))
        .Text("Important notification"))

Rule methods return self, and must be called before the sending methods (Text/Image, etc.). SendContext includes fields such as stage (pending/sending/retrying/success/failed/timeout), attempt, elapsed, error, and result, which are useful for monitoring.

Batch Build Mode (Build)

Build multiple sending methods in a single chain, then execute them all at once. This is suitable for scenarios where you need to send multiple messages in one go:

yunhu = adapter.get("yunhu")

# Build multiple messages and send them all at once
results = await (yunhu.Send.To("user", "123")
                .Build()                     # Enter build mode
                .Text("Notification 1")
                .Image("pic.jpg")
                .Text("Notification 2")
                .send_all())                 # Execute all at once
# results = [Text result, Image result, Text result]

.send_all() executes by default in parallel (concurrent sending, high efficiency). To ensure the order of message arrival, call .Sequential() for sequential execution:

# Sequential execution (ensures order) + retry on failure
await (yunhu.Send.To("group", "456")
       .Build()
       .Sequential()                # Send in order
       .Retry(2)                     # Retry failed items individually
       .Text("First message").Text("Second message")
       .send_all())

Batch execution uses a fail-continue strategy: failure of one message does not interrupt others, and failed items are automatically retried. The batch also supports Hook (triggered after all succeed), OnError (triggered when any fail), and OnProgress (progress callback) for the entire batch.

For more detailed rules and batch build instructions, refer to SendDSL Detailed Explanation.

Event Listening

There are three ways to listen for events:

  1. Platform-native event listening:

    from ErisPulse.Core import adapter, logger

@adapter.on("event_type", raw=True, platform="{AdapterName}")
async def handler(data):
    logger.info(f"Received native {AdapterName} event: {data}")

  2. OneBot12 standard event listening:

    from ErisPulse.Core import adapter, logger

# Listen for OneBot12 standard events
@adapter.on("event_type")
async def handler(data):
    logger.info(f"Received standard event: {data}")

# Listen for standard events from a specific platform
@adapter.on("event_type", platform="{AdapterName}")
async def handler(data):
    logger.info(f"Received {AdapterName} standard event: {data}")

  3. Event module listening: Events provided by the Event module are based on the adapter.on() function, so the event format provided by Event is a OneBot12 standard event.

    from ErisPulse.Core.Event import message, notice, request, command

message.on_message()(message_handler)
notice.on_notice()(notice_handler)
request.on_request()(request_handler)
command("hello", help="Send greeting message", usage="hello")(command_handler)

async def message_handler(event):
    logger.info(f"Received message: {event}")
async def notice_handler(event):
    logger.info(f"Received notice: {event}")
async def request_handler(event):
    logger.info(f"Received request: {event}")
async def command_handler(event):
    logger.info(f"Received command: {event}")

Among these, it is most recommended to use the Event module for event handling, as the Event module provides a rich set of event types and methods for handling events.

Standard Format

For easy reference, a simple event format is provided here. For detailed information, please refer to the links above.

Note: The following format is the basic OneBot12 standard format. Each adapter may have extended fields based on this format. For details, please refer to the specific feature documentation of each adapter.

Standard Event Format

The event transformation format that all adapters must implement:

{
  "id": "event_123",
  "time": 1752241220,
  "type": "message",
  "detail_type": "group",
  "platform": "example_platform",
  "self": {"platform": "example_platform", "user_id": "bot_123"},
  "message_id": "msg_abc",
  "message": [
    {"type": "text", "data": {"text": "Hello"}}
  ],
  "alt_message": "Hello",
  "user_id": "user_456",
  "user_nickname": "ExampleUser",
  "group_id": "group_789"
}

Standard Response Format

Message Sent Successfully

{
  "status": "ok",
  "retcode": 0,
  "data": {
    "message_id": "1234",
    "time": 1632847927.599013
  },
  "message_id": "1234",
  "message": "",
  "echo": "1234",
  "{platform}_raw": {...}
}

Message Sent Failed

{
  "status": "failed",
  "retcode": 10003,
  "data": null,
  "message_id": "",
  "message": "Missing required parameters",
  "echo": "1234",
  "{platform}_raw": {...}
}

ErisPulse Project:

Related Official Documentation:

Contributing

We welcome more developers to contribute to and maintain adapter documentation! Please follow these steps to submit your contribution:

  1. Fork the ErisPulse repository.
  2. Create a Markdown file in the docs/platform-features/ directory, naming it in the format <Platform Name>.md.
  3. Add a link to your contributed adapter and the relevant official documentation in this README.md file.
  4. Submit a Pull Request.

Thank you for your support!