OpenIMSDKDocs

Type at least two characters to search titles and routes.

EN

Language

ENEnglishEnglish docs简中简体中文中文文档
Browse OpenIMSDK Guides
GUIDESOpenIMSDK Guides

OpenIMSDK guides organized by implementation stage, from product concepts and deployment to integration, extension, operations, and reliability.

Guides

Core Concepts

Core user, administrator, notification account, and group concepts.

Copy

User types

OpenIMSDK defines three user identities: regular users, App Administrators, and system notification accounts.

Regular user

  • Core fields: userID, faceURL, nickname, and ex.
  • Purpose: Regular users are typically imported from external business systems and represent the end users logging in through OpenIMClientSDK. The ex field stores business-specific extension metadata.

App Administrator

  • Privileges: Possesses server-side administrative authority.
  • Purpose: Business backends invoke REST APIs as App Administrators to manage resources within OpenIMServer.
  • Built-in administrator: OpenIMServer provides a built-in App Administrator whose userID is imAdmin.

System notification account

  • Capabilities: App Administrators can send notification messages using system notification accounts without being restricted by friend relationships or group permissions. REST APIs can create notification accounts and update their nicknames and avatars.
  • User experience: When clients receive these messages, the conversation displays the notification account's avatar and nickname.

Groups

Group types

OpenIMServer currently uses a unified group model without differentiating between small and large groups.

Group member limits

A single group supports up to 100,000 members.

Join a group

Users can join a group through three methods:

  1. Member invitation: An existing member invites a new member directly.
  2. Join application: A user submits an application and awaits approval from the group owner or an administrator.
  3. Open joining: The group allows any user to join directly without requiring approval.

Group roles and permissions

A group contains three roles, ordered from highest to lowest privilege:

  1. Group Owner
  2. Administrator
  3. Regular Member

Group Owner

The Group Owner holds the highest permissions and can:

  • Appoint multiple administrators; all administrators share equal permissions.
  • Dissolve the group.
  • Transfer group ownership to another member.
  • Review and process join applications.
  • Update group metadata such as announcements and group names.

The Group Owner must transfer ownership before leaving the group.

Administrator

Administrators have lower permissions than the Group Owner and can:

  • Review and process join applications.
  • Update group metadata such as announcements and group names.
  • Remove or mute regular members.

Administrators do not have a hierarchical relationship among themselves.

Regular Member

Regular members can participate in group conversations, view group announcements, and send messages.

Messages and notifications

Messages

Messages are the actual content sent by users or the system, including text, images, videos, and other media types. OpenIMClientSDK handles creating, receiving, storing, and rendering messages on the client side.

Notifications

Notifications synchronize state changes triggered by user or system operations, such as group membership updates and friend relationship changes. Some notifications are rendered directly to users (such as join notifications and system announcements), while others are consumed internally by the client for state synchronization without appearing as normal chat messages.

Message push delivery

Online delivery

When a user is online, OpenIMServer delivers messages over the persistent long connection maintained by OpenIMClientSDK:

  • Real-time delivery: Messages reach the receiving client immediately.
  • Reliability: The long connection carries both real-time messages and state notifications reliably.

Offline push notifications

When a user is offline or the application process has terminated, the OpenIMClientSDK long connection cannot receive messages directly, requiring third-party push notification services:

  • iOS typically uses APNs.
  • Mainland China environments typically use vendor push services such as GeTui.
  • Environments outside mainland China typically use Firebase Cloud Messaging (FCM).

Message storage types

Local messages

Except for the pure JavaScript SDK, OpenIMClientSDK pulls messages on demand and persists synchronized messages in a local database. These are collectively referred to as local messages.

Multi-device synchronized messages

When a user sends a message from Device A, it synchronizes to Device B logged in with the same account. These are called multi-device synchronized messages.

Offline messages

Messages received while a user is offline are pulled from OpenIMServer and loaded on demand after the user signs in again.

Roaming messages

When a user switches devices or reinstalls the application, OpenIMClientSDK pulls and synchronizes historical message records from OpenIMServer. These are referred to as roaming messages.

Object storage

Object storage is used to store unstructured data such as images, audio, video, and general files. Each object comprises payload data, extensible metadata, and a globally unique key.

When sending file, image, or video messages, OpenIMClientSDK typically uploads the file to the configured object storage first, obtains the access URL, and then sends the message payload. Deploying teams must configure a supported object storage provider for OpenIMServer, such as MinIO, Alibaba Cloud OSS, Tencent Cloud COS, or AWS S3.