DOCSEARCHbyAlgolia
Submit Docs

OneBot 11

repository·master·Indexed 20 days ago

https://github.com/botuniverse/onebot-11

A standardized interface for chat robot applications evolved from the CQHTTP protocol. OneBot 11 provides a consistent set of APIs, message formats, and event types to ensure cross-platform compatibility. It supports four communication modes: HTTP (API calling), HTTP POST (event pushing), Forward WebSocket, and Reverse WebSocket. The documentation covers API structures, asynchronous and rate-limited calls, event handling, and specific message-sending and group management operations.

Tokens
16.7K
Snippets
71
Records
99
Agent score
71%

What's inside onebot-11

  1. Supported communication modes in OneBot 11

    master

    OneBot 11 supports four distinct communication modes for API calls and event delivery. All data transmitted across these modes is encoded using UTF-8.

    1. HTTP (API Calling)

    OneBot acts as an HTTP Server. You call its APIs by sending HTTP requests to the OneBot service.

    2. HTTP POST (Event Pushing)

    OneBot acts as an HTTP Client. It pushes events to a URL configured by the user and processes the responses returned by that URL. This mode is specifically used for event reporting.

    3. Forward WebSocket (API Calling & Event Pushing)

    OneBot acts as a WebSocket Server. It accepts incoming WebSocket connections from clients, providing both API calling capabilities and event push services over the connection.

    4. Reverse WebSocket (API Calling & Event Pushing)

    OneBot acts as a WebSocket Client. It actively initiates a connection to a URL configured by the user, providing both API calling and event push services through that established connection.

  2. What is the OneBot standard?

    master
    OneBot is a universal interface standard for chat robot applications. It is derived from the CQHTTP plugin interface originally used for the CKYU platform. The standard aims to provide a unified, evolving interface that allows developers to write robot logic once and migrate it seamlessly across different robot platforms that implement the OneBot standard. It covers communication protocols (HTTP, WebSocket), message formats, APIs, and event types.

  3. Understand OneBot HTTP POST Event Reporting

    master

    OneBot sends event data to a configured URL using HTTP POST requests whenever an event occurs. The event data is formatted as a JSON object. After the request is processed, OneBot handles any "Quick Actions" (快速操作) returned in the HTTP response, such as quick replies or bans.

    Key characteristics:

    • Format: JSON
    • Headers: Includes X-Self-ID (the robot's QQ number) and optionally X-Signature for security.
    • Response: The backend must return an HTTP response to prevent OneBot from waiting until a timeout occurs.

  4. Handle OneBot API responses

    master

    Successful API calls return a JSON response. The data field contains the actual payload returned by the API.

    Note: In the API documentation, descriptions under the "响应数据" (Response Data) heading refer specifically to the contents of the data field and do not repeat the status or retcode fields.

  5. Understand the Message Segment (Array Format) structure

    master

    In the OneBot 11 array format, messages are represented as an array of message segment objects. This format is more powerful than the string-based CQ code format because it supports nesting and explicit data types.

    Each segment object consists of:

    • type (string): The functional name of the segment (e.g., image, text, face). This corresponds to the function name in a CQ code.
    • data (object or null): The parameters for the segment. For most segments, the values within this object are strings to maintain compatibility with CQ codes.

    Because segments separate plain text from multimedia, values are treated as literal values and do not require escaping.

    {
    "type": "image",
    "data": {
        "file": "123.jpg"
    }
}

  6. Understand the `message` Data Type

    master

    The message data type in OneBot 11 is polymorphic and depends on your configuration:

    1. In Event Data: The format is determined by event.message_format. It will be either a string or an array of message segments.
    2. In Quick Operations: The message field is more flexible and accepts three types of data: a string, an array of message segments, or a single message segment object.

  7. Parse OneBot HTTP response bodies

    master

    When the HTTP status code is 200, the response body is a JSON object. The structure is as follows:

    {
    "status": "ok",
    "retcode": 0,
    "data": { ... }
}

    Field Definitions

    • status: Indicates the processing state:
      • ok: Operation successful; retcode will be 0.
      • async: Request submitted for asynchronous processing; retcode will be 1. Success/failure cannot be determined from this response.
      • failed: Operation failed; retcode will be something other than 0 or 1. Check implementation logs for details.
    • retcode: The return code (e.g., 0 for success, 1 for async).
    • data: The payload returned by the API.
      • For operations without data (e.g., kicking a user), this is null.
      • For data-retrieval operations, this contains the requested object.
      • Note: For asynchronous API calls, data is always null, even if the synchronous version of the API returns data.
    {
    "status": "ok",
    "retcode": 0,
    "data": {
        "id": 123456,
        "nickname": "滑稽"
    }
}

  8. Use the String Message Format

    master

    The String Message Format is the native format used by CKYU and maintained here for compatibility. In this format, a single message is represented as a single string containing both plain text and multimedia content (images, emojis, links, etc.).

    To send a message using this format, include the combined string in the message field of your JSON payload.

    {
    "user_id": 10001000,
    "message": "[CQ:face,id=178]看看我刚拍的照片[CQ:image,file=123.jpg]"
}

  9. Understand OneBot 11 Event Types

    master

    Events are data pushed from OneBot to the user. All events are represented in JSON format across all communication methods (HTTP POST, Forward WebSocket, and Reverse WebSocket). Events are categorized into four main types based on the post_type field:

    • message: Message events (e.g., private chats, group messages).
    • notice: Notification events (e.g., group member changes, friend changes).
    • request: Request events (e.g., group join requests, friend requests).
    • meta_event: Meta events (e.g., OneBot lifecycle events, heartbeats).

  10. Understand Meta Events in OneBot 11

    master
    Meta Events are internal events generated by the OneBot implementation itself rather than from chat software interactions (like messages or notifications). They are used to monitor the operational state of the OneBot instance. Meta events are reported using the same mechanism as standard events (e.g., via WebSocket or HTTP POST).

  12. Understand OneBot 11 message formats

    master

    In the OneBot 11 standard, messages are a fundamental data type used in both sending message APIs and receiving message events. Messages currently support two distinct formats:

    1. String format: A plain text representation of the message.
    2. Array format: A structured representation (often used for mixed media or complex message segments).

    When interacting with the API, you must ensure the format matches the expected type for the specific endpoint or event you are handling.