repository·main·Indexed 24 days ago
https://github.com/botuniverse/onebotA standardized API specification designed to unify chat bot development across various platforms, enabling code portability. It defines communication protocols including HTTP, HTTP Webhook, WebSocket, and Reverse WebSocket, providing guidelines for authentication via access tokens, event handling, and request/response formatting using JSON and MessagePack.
OneBot is an application interface standard for chat bots. It provides an abstraction for the APIs used to develop chat bots, standardizing communication methods, data formats, and fields.
By following this standard, developers can write their business logic once and deploy it across multiple different chat platforms.
Note: OneBot is a specification (a document), not a centralized software implementation. Implementations (such as LibOneBot) are created by the community for various languages, runtimes, and platforms.
An Event is an object pushed by OneBot to an application. It represents data spontaneously generated by OneBot or received from a robot platform.
Every event must be an object and must contain the following mandatory fields to be considered valid. If any of these fields are missing or have incorrect types, the data should not be treated as a valid event.
When implementing OneBot message segments, developers should follow these guidelines for parameter handling and error reporting:
10005 (Unsupported Segment).10007 (Unsupported Segment Data). If the parameter is non-essential, it may be ignored.34xxx error code indicating a message sending failure. If failure detection is difficult, the error may be ignored.If an access_token is configured and is not an empty string, the OneBot implementation must perform authentication using the following priority:
Authorization header. The value must exactly match Bearer <access_token> (whitespace trimming is not required on either side).access_token query parameter. Its value must exactly match <access_token>.If neither is present or they do not match, the request must fail with an HTTP 401 Unauthorized status code.
The OneBot ecosystem consists of three primary layers that interact via the OneBot Standard:
telegram, discord, qq).Developers typically build OneBot Applications using a OneBot SDK (like NoneBot or Koishi) to avoid handling low-level communication logic.
OneBot communication is built around three core data types:
Params).bytes data type must be represented as a Base64 encoded string within the JSON payload.WebSocket is recommended when the application can actively access the OneBot implementation (e.g., via public IP or local network), when an unknown number of applications need to connect to a single OneBot instance, or when high performance is required.
To implement WebSocket support, the OneBot implementation should start a WebSocket server listening on a configured <host>:<port> and accept connection requests at the / path. The server pushes events to the application and parses incoming messages as action requests.
The message.private event is triggered when a user sends a private message. These events are based on the OneBot Connect - Event specification, where the top-level type field must be message and the detail_type field must be private.
When implementing handlers for these events, note that if a sub_type is not explicitly mentioned in documentation, its value should be an empty string ("").
OneBot Connect (OBC) defines how Implementations and Applications connect over a network. It consists of two parts: Communication Methods and Data Protocols.
Request)Response)All notice events in OneBot are based on the OneBot Connect - Event protocol. To identify a notice event, the type field must be set to notice.
Specific event details are distinguished by the detail_type field. If a sub_type is not explicitly defined for an event, its value should be an empty string ("").