SDKsiOSIncludes Enterprise features

Messages overview

Understand message creation, sending, reception, and local storage in OpenIM iOS SDK.

Message capabilities in the OpenIM iOS SDK center on the OIMMessageInfo model. Plain text messages and media messages created from local files are initialized via corresponding OIMMessageInfo factory class methods, then sent through Send a message. If media files have already been uploaded by your application to object storage and public URLs are available, create messages using URL-based factory methods and send them via Send a message without OSS.

Both delivery pathways support one-to-one and group chats. Incoming messages, message revocations, deletions, read receipts, media upload progress, and conversation updates synchronize to the application through listener protocols and delegates.

Client-side message interfaces and state stores maintain the following core identifiers:

Identifier	Description
`clientMsgID`	Stable client-generated unique message identifier, used for list deduplication, state updates, queries, and pagination cursors.
`conversationID`	Conversation record identifier, used for history queries, searching, and unread count tracking. Take directly from conversation data rather than deriving from array indices.
`recvID`	Recipient user ID for one-to-one messages. Pass `nil` when sending group messages.
`groupID`	Target group ID for group messages. Pass `nil` when sending one-to-one messages.

Message types

Initialize OIMMessageInfo instances for each content type using dedicated class methods. The sending layer dispatches all message models uniformly without requiring separate transport channels for different formats.

Message type comparison

Content type	Typical use case	Guide
Plain text	Standard text chat messages.	Create a text message
@ Mention text	Mention one or more members in a group chat.	Create an @ message
Image	Create image messages from local files or hosted URLs.	Create an image message from a local path
Audio	Create voice and sound recording messages.	Create an audio message from a local path
Video	Create video messages with video snapshot covers.	Create a video message from a local path
File	Create general file attachments.	Create a file message from a local path
Custom message	Structured business payloads (cards, red packets, orders).	Create a custom message
Markdown	Rich text formatted with Markdown syntax.	Create a Markdown message

When the SDK should handle media uploads, use path-based factory methods and Send a message. When your backend already hosts the files, use URL-based creation methods and Send a message without OSS to bypass the built-in upload pipeline. Store data that must be shared across devices inside the message payload, and store private rendering state in localEx.

Common OIMMessageInfo properties

Property	Type	Description
`clientMsgID`	`NSString * _Nullable`	Client message ID used as the primary deduplication and merge key.
`serverMsgID`	`NSString * _Nullable`	Server message ID, which does not replace `clientMsgID` for local merging.
`sessionType`	`OIMConversationType`	Conversation type (one-to-one or group) used to route the message.
`sendID`	`NSString * _Nullable`	User ID of the message sender.
`recvID`	`NSString * _Nullable`	User ID of the recipient in one-to-one chats.
`groupID`	`NSString * _Nullable`	Group ID in group chats.
`contentType`	`OIMMessageContentType`	Content type enumeration determining which element to parse and render.
`sendTime`	`NSTimeInterval`	Timestamp when the message was sent, used for chronological sorting.
`status`	`OIMMessageStatus`	Message dispatch status (sending, succeeded, failed).
`isRead`	`BOOL`	Read receipt status of the message.

Specific content properties such as textElem, pictureElem, soundElem, videoElem, fileElem, atTextElem, and customElem are populated based on contentType. Validate that both contentType and the corresponding element are non-nil when rendering views, providing fallback placeholders if content is absent.

Message handling pipeline

Construct the message object locally using an OIMMessageInfo factory method.
Call Send a message or Send a message without OSS to dispatch to a user or group.
On the sender client, update UI bubble states using clientMsgID upon success or progress callbacks; receiving clients capture new messages via OIMAdvancedMsgListener.
When opening a conversation view, fetch an initial history snapshot, then maintain state by listening for incoming messages, revocations, deletions, and read receipts.

Message creation factory methods instantiate models in local memory without initiating network requests or triggering events. Callback completion, asynchronous listener notifications, and cache reconciliation queries operate as three distinct stages.

Conversation routing rules

When sending one-to-one messages, supply recvID and set groupID to nil. When sending group messages, supply groupID and set recvID to nil. Deduplicate messages in local storage using clientMsgID scoped to conversationID; never use array positions or text summaries as primary keys.

Sending and receiving

Send a message: Dispatch local message instances with built-in upload and progress tracking.
Send a message without OSS: Dispatch messages initialized with pre-hosted media URLs.
Receive messages: Register message listeners to handle incoming real-time and synchronized messages.
Receive custom business messages: Receive standalone business notification signals outside conversation message streams.

Retrieval and searching

Load older messages: Retrieve historical messages by scrolling upward from an anchor message.
Load newer messages: Retrieve newer messages downward from a historical anchor.
Load message context: Read surrounding messages before and after a specified message.
Find messages by ID: Retrieve specific messages by clientMsgID within a conversation.
Search messages: Search locally synchronized chat history by keyword.

Message management and read status

Revoke a message: Revoke a sent message and notify connected clients.
Delete a message: Delete a single locally stored message.
Delete messages in batches: Delete multiple historical messages in a batch.
Modify a message Commercial: Edit text content of a previously sent message.
Pin or unpin a message Commercial: Pin or unpin a message within a conversation.
Retrieve pinned messages Commercial: Query the list of pinned messages in a conversation.
Set local message extension: Store device-local private metadata on a message.
Send group message read receipts: Acknowledge read status for messages in a group chat.
Retrieve group message readers: Query read and unread member breakdowns for a group message.

Composition and transcription

Update typing status: Send typing indicators to the peer during input changes.
Retrieve typing status: Inspect whether the other participant is actively typing.
Transcribe audio Commercial: Convert voice messages to text.
Save local transcript Commercial: Persist transcribed speech text into local message extension storage.
Check speech-to-text availability Commercial: Check whether voice transcription is supported on the server.
Set the app badge count: Synchronize total unread message counts to the system push badge.

Was this page helpful?