Using the imhelper SDK
Relevant source files
The following files were used as context for generating this wiki page:
The imhelper SDK provides a unified client interface and receiving mechanism for interacting with the OneBots gateway or other compatible IM protocol implementations. It abstracts protocol-specific details into a common core, allowing developers to consume events and call APIs across OneBot v11/v12, Satori v1, and Milky v1 protocols using a consistent development pattern.
Sources: README.en.md, packages/imhelper/package.json
SDK Architecture
The SDK follows a modular design consisting of the core imhelper package and protocol-specific SDKs. The core package manages the lifecycle of event ingestion and transport, while the protocol-specific packages (e.g., @imhelper/onebot-v11) provide typed client instances and protocol-native API mappings.
The diagram shows the flow from the consumer application through the SDK layers to the OneBots gateway.
Sources: AGENTS.md, CONTRIBUTING.md, tests/unit/client-sdk-docs-contracts.spec.ts
Client Initialization
To interact with a specific protocol, you use factory functions provided by the respective protocol SDK. These factories create client instances pre-configured for the target protocol's data structures and API contracts.
| Factory Function | Target Protocol | Description |
|---|---|---|
createOnebot11Client | OneBot v11 | Creates a client for the OneBot v11 ecosystem. |
createOnebot12Client | OneBot v12 | Creates a client for the OneBot v12 ecosystem. |
createSatoriClient | Satori v1 | Creates a client for the Satori protocol. |
createMilkyClient | Milky v1 | Creates a client for the Milky v1 protocol. |
Sources: tests/unit/client-sdk-docs-contracts.spec.ts:98-103, protocols/onebot-v11/sdk/CHANGELOG.md
Event Receiving Modes
The SDK supports multiple transport mechanisms to receive events from the gateway. You configure these modes during client initialization to match the deployment environment of your service.
Supported Transport Modes
- ws / wss: Establishes a WebSocket connection to the gateway. This is the default mode and supports continuous reconnection.
- sse: Uses Server-Sent Events for one-way event streaming from the gateway.
- webhook: Configures the client to receive pushed events via HTTP POST requests (requires
acceptHttp). - manual: Allows manual event injection via the
ingestmethod, suitable for custom integration scenarios.
Sources: tests/unit/client-sdk-docs-contracts.spec.ts:104-110, protocols/onebot-v11/sdk/CHANGELOG.md
Key Features and Data Handling
Data Transfer Objects (DTO)
The SDK enforces a strict DTO boundary. Protocol entities and message queries are projected into stable behavior instances bound to the current client. This ensures that protocol-specific data structure errors do not appear as empty lists or undefined values.
Identity Mapping
Events passed through the SDK are processed by an identity map. This map stabilizes identifiers for users, groups, channels, and members before they are delivered to the application. This ensures that entity getters (e.g., for user profiles) do not rely on pre-emptive directory queries and maintain consistency throughout the event lifecycle.
Connection and Security
- Reconnection: WebSocket receivers include built-in logic for persistent reconnection to maintain link stability.
- Authentication: Clients support
access_tokenconfiguration for secure communication with the gateway. - Logging: The SDK uses a structured logging system; developers should utilize the provided logger rather than standard console output for runtime information.
Sources: protocols/onebot-v11/sdk/CHANGELOG.md:5-7, protocols/onebot-v12/sdk/CHANGELOG.md:10-15, AGENTS.md
Implementation Example
The following sequence illustrates a typical interaction using the SDK to receive a message and respond.
The sequence demonstrates the client creation, the WebSocket handshake, event ingestion, and a subsequent API action.
Sources: architecture-diagrams.md, tests/PROTOCOL_AUTH_HEARTBEAT.md
The imhelper SDK acts as the primary bridge for developers to build applications on top of the OneBots ecosystem. By providing protocol-specific clients with a shared transport management core, it reduces the complexity of handling multiple IM platforms and wire formats.