Core Concepts

User types

OpenIMSDK has three user types: regular users, App Administrators, and system notification accounts.

Regular users

• Fields: userID, faceURL, nickname, and ex
• Description: Regular users are usually imported from an external business system and represent standard end users in OpenIMSDK. The ex field is available for business-specific extensions.

App Administrator

• Privileges: Has super-administrator privileges.
• Usage: Calls REST APIs as an App Administrator to operate the OpenIMSDK system directly.
• Built-in administrator: OpenIMServer includes an App Administrator whose userID is imAdmin.

System notification account

• Function: An App Administrator can send notification messages as a system notification account without friend-relationship or group-permission restrictions. REST APIs can add notification accounts and update their nicknames and avatars.
• User experience: Messages appear in a conversation with the notification account's avatar and nickname.

Groups

Group type

• Single group type: The system currently supports one group type and does not distinguish between small and large groups.

Group member limit

• Maximum members: Groups support up to 100,000 members.

Ways to join a group

Users can join a group in three ways:

1. Invitation by a group member: An existing member invites a new member to join directly.
2. Join request: A user submits a request and waits for approval from the group owner or an administrator.
3. Open membership: Any user can join without approval.

Group roles and permissions

Groups have three roles, listed from highest to lowest privilege:

1. Group owner
2. Administrator
3. Regular member

Group owner

• Privileges: Has the highest level of authority.
• Management capabilities:
• Appoint multiple administrators, all with equal permissions.
• Dissolve the group.
• Transfer ownership to another group member.
• Transfer ownership before leaving the group.
• Process join requests.
• Manage settings such as the group announcement and group name.

Administrator

• Privileges: Has the same permissions as other administrators and fewer privileges than the group owner.
• Management capabilities:
• Process join requests.
• Manage settings such as the group announcement and group name.
• Manage regular members, including removing and muting them.

Regular member

• Privileges: Has basic group usage permissions.
• Capabilities: Participate in group chat, view announcements, and send messages.

Permission management

• Actions by higher-privilege roles: Group owners and administrators can act on lower-privilege roles, for example by removing or muting members.
• Equal administrator permissions: Administrators have no hierarchy among themselves.

Owner and administrator management capabilities

• Process join requests: Group owners and administrators can review and process user requests to join the group.
• Manage group settings: This includes editing the group announcement and changing the group name.

Messages and notifications

Messages

• Definition: Actual content sent by a user or the system, including text, images, video, and other media.
• Functions:
• Content delivery: Delivers message content to recipients.
• Display and rendering: Presents the content clearly on the receiving client.

Notifications

• Definition: Events triggered by a user or the system and delivered to the relevant parties as notifications.
• Uses:
• System synchronization: Synchronizes state or operations, such as group membership and friend lists.
• Information display: Some notifications present important events or operation results to users, such as join-group notices and system announcements. Others exist only for system synchronization and are not displayed as messages.

Message push

Online push

• Definition: When a user is online, OpenIM first delivers messages through its own long-lived connection. This is called online push.
• Characteristics:
• Real-time delivery: Messages reach the recipient immediately.
• Reliability: The long-lived connection provides a reliable delivery channel.

Offline push

• Definition: When the user is offline or the app process has been terminated, the OpenIMSDK long-lived connection cannot deliver the message, so a third-party push service is required.
• Implementation:
• Vendor push: Uses vendor services such as APNs (Apple Push Notification service).
• Within mainland China: GeTui is commonly used.
• Outside mainland China: Firebase is commonly used.
• Characteristics:
• Broad coverage: Supports varied network conditions so users can be notified when they return online.

Message storage types

Local messages

Except in the JS SDK, OpenIMSDK fetches and loads messages as needed. Messages already fetched by a client are stored locally and are collectively called local messages.

Multi-device synchronized messages

Users commonly use multiple devices. When a user sends a message from device A and it is synchronized to device B, it is a multi-device synchronized message.

Offline messages

Messages received while a user is offline are synchronized from the server and loaded as needed after the user signs in again. These are offline messages.

Roaming messages

When a user changes devices or reinstalls the application, the system fetches and synchronizes historical messages. These are roaming messages.

Object storage

Object storage is an architecture for storing large volumes of unstructured data. It stores information as independent objects, each containing the data, extensible metadata, and a globally unique key.

Files, images, and videos are generally uploaded to object storage to obtain a URL before the message is sent. OpenIMSDK handles this flow internally, but you must configure one supported object storage service, such as MinIO, OSS, COS, or S3.