Message overview

The uni-app / uni-app x plugin represents every message with OpenIMMessageItem. Sending has two phases: create an outgoing message object for the desired content, then send that object to a user or group. A create method does not send anything, and a successful send Promise does not prove that another client has received the message.

Realtime delivery, history, search, and message management are all conversation-scoped. Merge send results, realtime events, and history idempotently with the composite key conversationID:clientMsgID: conversationID identifies the conversation and clientMsgID identifies the message.

Message processing flow

Messages created from a readable native image, audio, video, or file path are uploaded by sendMessage(). If your application already uploaded the media and has a URL, use the corresponding create*MessageByURL() method and send it with sendMessageNotOss() to avoid uploading it again.

OpenIMMessageItem structure

Read message bodies from the elem that matches contentType: textElem for text; pictureElem, soundElem, videoElem, and fileElem for media; atTextElem and quoteElem for mentions and replies; mergeElem and customElem for merged and custom messages; cardElem, locationElem, and faceElem for cards, locations, and emoji; and advancedTextElem, typingElem, and notificationElem for advanced text, typing, and notifications. Do not infer the message type from display text or array position.

conversationID identifies the containing conversation but is not an OpenIMMessageItem field. Obtain it from the active conversation, query condition, search result, or event context, then merge state by conversationID:clientMsgID.

Create messages with different content types

Put device-only presentation state in localEx, not in business content that must synchronize to other users. See Set a local message extension.

Progress events for message sends, file uploads, and log uploads belong to this page:

import {
  off,
  onSendMessageProgress,
  onUploadFileProgress,
  onUploadLogsProgress,
  type OpenIMSDKEventSubscription,
} from '@/uni_modules/unix-openim-sdk'

const sendProgressSubscription = onSendMessageProgress((event) => {
  updateMessageProgress(event.clientMsgID, event.progress)
})
const subscriptions : Array<OpenIMSDKEventSubscription> = [
  sendProgressSubscription,
  onUploadFileProgress((event) => updateCurrentUpload(event.progress)),
  onUploadLogsProgress((event) => updateLogUpload(event.progress)),
]

function removeProgressListeners() {
  subscriptions.forEach((subscription) => off(subscription))
}

Progress may repeat, skip values, or arrive before or after the final Promise. Display it monotonically and use the API result as the source of truth. Call removeProgressListeners() when logging out, switching accounts, or disposing the progress state.

A local media path must be readable by the native layer. Resolve unifile:// to a real sandbox path; use the by-URL create method for network URLs.

Find a page by task

State synchronization boundaries

The complete listeners for new messages, deletion, revocation, modification, pinning, group read status, and typing status live on their task pages. Message creation and pure query methods only establish snapshots from their Promise result and do not emit shared message events. For mutations, treat Promise completion, event delivery, and reconciliation queries as separate phases.

Conversation unread counts, total unread counts, and group mention reminders are conversation state. Maintain them with Mark a conversation as read, Maintain the total unread count, and the events on Retrieve the conversation list.