Messages overview

Message capabilities in OpenIM iOS SDK center on OIMMessageInfo. Create regular messages and media messages backed by local files through the corresponding OIMMessageInfo class methods, then send them with sendMessage:recvID:groupID:isOnlineOnly:offlinePushInfo:onSuccess:onProgress:onFailure:. If your application has already uploaded a media file and obtained its URL, create the message with the corresponding URL-based class method and send it with sendMessageNotOss:recvID:groupID:offlinePushInfo:onSuccess:onFailure:. Both paths support one-to-one and group chats. The application synchronizes new messages, revocations, deletions, read receipts, upload progress, and conversation changes through the appropriate listener or delegate.

A message page normally retains these identifiers:

Message types

Create an OIMMessageInfo for each content type through the corresponding class method. The sending layer consistently uses sendMessage:...; it does not need a separate entry point for every content type.

Message-type comparison

When the SDK should upload local media, use a path-based creation method and sendMessage:.... When your application already has a remote URL, use the matching URL-based method and sendMessageNotOss:... to avoid entering the built-in upload flow again. Put application data that must be shared in the message content; put device-local display state in localEx.

Common OIMMessageInfo properties

The pinned SDK exposes these commonly used routing, rendering, and state-merging properties:

Content properties such as textElem, pictureElem, soundElem, videoElem, fileElem, atTextElem, and customElem may be nil. Check both contentType and the corresponding element when rendering. If the expected content is absent, show a fallback instead of force-unwrapping it.

Message flow

1. Create a local OIMMessageInfo with a class method such as createTextMessage: or createImageMessageFromFullPath:.
2. Send it with sendMessage:recvID:groupID:isOnlineOnly:offlinePushInfo:onSuccess:onProgress:onFailure:.
3. On the sending client, merge the final message from the success callback by clientMsgID. On receiving clients, merge incremental updates through OIMAdvancedMsgListener.
4. When opening a chat page, establish a snapshot with a history query, then continue merging message, revocation, deletion, and read-receipt events.

Message factories only create in-memory objects. They neither send messages nor trigger receiving events. A successful send, arrival of the remote event, and a subsequent history query are three separate stages.

Conversation routing

For a one-to-one message, provide recvID and pass nil as groupID. For a group message, provide groupID and pass nil as recvID. After a message enters the state layer, deduplicate it by its conversation and clientMsgID; never use an array position or display text as the key.

Browse capabilities by topic

Send messages

Create a message first, then send it to a one-to-one or group chat. Provide recvID for one-to-one and groupID for a group, passing nil for the other target. When the SDK should upload a media file, use a local-path factory and sendMessage:.... When your application has already uploaded it, use the URL factory and sendMessageNotOss:....

The send success callback may return nil. If it returns a message, replace the local pending item by clientMsgID. See Send a message for complete parameters and error handling. Image, audio, video, file, and rich-message factories are separated by type under the Creating messages menu.

Receive messages

Receive regular and online-only messages through OIMAdvancedMsgListener. Each callback in the pinned iOS SDK carries one nullable OIMMessageInfo. There is no separate offline-new-message selector; the SDK synchronizes offline changes after a new login. Resolve the message's conversation first, then merge it idempotently by conversationID:clientMsgID.

For the complete receiving flow and listener lifecycle, see Receive messages.

Retrieve messages

Retrieve message history by conversationID and startClientMsgID with getAdvancedHistoryMessageList:onSuccess:onFailure:. Pass nil as startClientMsgID for the first page, then use the boundary message's clientMsgID for later pages. Deduplicate history results and delegate updates with the same identifier.

See Load message history for lists and Find messages by ID for individual messages.

Search messages

searchLocalMessages:onSuccess:onFailure: searches only messages already synchronized to the current account's local storage. For a group-chat search, use the group conversation's conversationID, not the groupID used when sending.

See Search messages.

Manage messages

According to the available capability, sent messages can be forwarded, merged, deleted, revoked, or cleared from history. You can also insert messages for local display only or report typing status. Apply revocation and deletion updates to the original bubble by conversationID:clientMsgID; register each complete event handler only on its owning page.

Related pages include Create a forwarded message, Create a merged message, Modify a message, Pin or unpin a message, Delete a message, Revoke a message, Insert a local one-to-one message, Clear all local messages, and Report typing status.

Mark messages as read

markConversationMessageAsRead:onSuccess:onFailure: clears a conversation's unread count. Merge one-to-one and group read receipts through the message listener. A successful call only means that the read operation completed; it does not mean that the sender's UI or every signed-in client has already updated.

For one-to-one receipts, see Mark a conversation as read. For member-level group capabilities, see Report group-message read status and Retrieve group-message readers.

Mention other users

Create a group @ message with createTextAtMessage:atUsersID:atUsersInfo:message:, then send it to the group. atUsersID contains stable user IDs, while atUsersInfo supplies display information. Receiving clients use the conversation's groupAtType to display mention indicators.

See Create an @ message.

Retrieve unread counts

Conversation lists, total unread counts, and @ indicators come from Conversation APIs and OIMConversationListener. Merge conversation-layer changes by conversationID and update the global badge with the latest total-unread value. Message pages do not register the conversation delegate again.

See Retrieve and maintain the total unread count.

Custom messages and extension data

Use createCustomMessage:extension:description: for structured data that other members must receive. Use setMessageLocalEx:clientMsgID:localEx:onSuccess:onFailure: for additional state that affects only the current device. A local extension is not synchronized to other clients and does not produce a shared message event.

See Create a custom message and Set a message's local extension.

Transcribe audio

The commercial OpenIMCore SDK can check transcription support and transcribe a local audio path or Base64-encoded audio data. The transcript is not an OIMSoundElem property. To retain it only on the current device, merge it into the message's existing localEx without overwriting fields owned by other features.

For supported formats, size and duration limits, and local persistence, see Transcribe audio.

Modify and pin messages

modifyMessageWithConversationID:message:onSuccess:onFailure: updates message content in a specified conversation. Other clients merge onMessageModified: by conversationID + clientMsgID. setConversationPinnedMsgWithConversationID:clientMsgID:pinned:onSuccess:onFailure: pins or unpins a message in a conversation. getConversationPinnedMsgWithConversationID:onSuccess:onFailure: establishes the pinned-list snapshot, and onChangedPinnedMsg: supplies subsequent updates.

For permissions, result stages, and event payloads, see Modify a message and Pin or unpin a message.

Event ownership

Message events are owned by their respective capability pages; this overview only documents navigation and ownership. New-message events belong to Receive messages, deletions to Delete messages in batches, revocations to Revoke a message, one-to-one read receipts to Mark a conversation as read, group read receipts to Report group-message read status, and typing status to Report typing status. For complete conversation-change handling, see Retrieve the conversation list.

Message creation and pure queries establish objects or snapshots directly from callback results; do not describe them as triggering shared events. For state-changing calls, handle the success callback, delegate update, and reconciliation query separately.

Message modification, pinned conversation messages, and audio transcription come from the enterprise SDK and are marked as commercial on their respective pages. The current high-level iOS API has no OIMMessageInfo factory selector fully equivalent to the WASM targeted-group-message factory. Do not simulate that capability with an ordinary group message or local insertion.