SDKsuni-app / uni-app xIncludes Enterprise features

Message overview

Understand message creation, transmission, reception, querying, and lifecycle synchronization workflows.

The OpenIM UniApp SDK represents each message record using the OpenIMMessageItem interface. Message transmission operates in two distinct phases: first, construct an outgoing message data object using the appropriate creation method, and then transmit that object to a target user or group. Message creation methods do not send data over the network; likewise, Promise resolution from a send invocation does not guarantee that other devices have rendered the incoming message.

In message lists, locate individual messages using their owning conversation and clientMsgID. The conversationID is derived from the active conversation context, query filter, search result, or event payload, rather than being an intrinsic property of OpenIMMessageItem.

Message processing phases

Phase	Core operations	Description
Create	Invoke the corresponding message creation method	Returns an `OpenIMMessageItem` or `null`. Generates the local message data structure without transmitting data or triggering new message events.
Send	Invoke Send a message or Send a non-OSS message	Supply `recvID` for single chats, or `groupID` for group chats; pass an empty string `""` for the unneeded target field.
Receive	Listen for incoming message events	Identify the destination conversation and merge items by `clientMsgID`; ignore duplicate event deliveries.
Query	Load message history, search, or look up by ID	Retrieves messages stored locally at the time of invocation without emitting message events.
Update	Delete, revoke, edit, pin, or report read receipts	Manage Promise resolution, incoming update events, and state re-queries independently.

For local image, audio, video, and file media, Send a message handles automated upload to storage before message transmission. If assets are already uploaded to your business server and possess public remote URLs, create URL-based message items and transmit them via Send a non-OSS message to bypass duplicate file uploads.

Common message fields

Field	Type	Description
`clientMsgID`	`string \| null`	Client-generated message ID used for list deduplication and state tracking; verify existence in created objects.
`serverMsgID`	`string \| null`	Server-assigned message ID; null or empty while pending or if sending failed.
`sessionType`	`OpenIMSessionType`	Chat session type, such as single chat or group chat.
`sendID`	`string \| null`	User ID of the message sender.
`recvID`	`string \| null`	Recipient user ID for single chats; empty string in group chats.
`groupID`	`string \| null`	Target group ID for group chats; empty string in single chats.
`msgFrom`	`number`	Message origin indicator.
`contentType`	`OpenIMMessageType`	Message content type enum, determining which element field contains the payload.
`createTime`	`number`	Timestamp when the message object was created locally, in Unix milliseconds.
`sendTime`	`number`	Timestamp when the message was sent, in Unix milliseconds.
`seq`	`number`	Authoritative sequence number assigned by OpenIMServer; absent before transmission succeeds.
`senderPlatformID`	`OpenIMPlatform`	Operating platform constant of the sender device.
`senderNickname`	`string \| null`	Sender nickname recorded in the message snapshot.
`senderFaceUrl`	`string \| null`	Sender avatar URL recorded in the message snapshot.
`status`	`OpenIMMessageStatus`	Message dispatch status (sending, success, or failed).
`isRead`	`boolean`	Read receipt status at the time of receipt or query.
`offlinePush`	`OpenIMOfflinePush \| null`	Offline push notification configuration applied to this message.
`content`	`string \| null`	Serialized message body preserved by the SDK; prefer rendering the dedicated element property.
`attachedInfo`	`string \| null`	SDK internal auxiliary string; parse only according to confirmed business protocols.
`ex`	`string \| null`	Custom extension string synchronized with other participants across all clients.
`localEx`	`string \| null`	Extension string preserved exclusively in the local database of the current device.

The message body resides in the dedicated element property matching contentType:

Content payload	Dedicated property
Text	`textElem`
Image, audio, video, file	`pictureElem`, `soundElem`, `videoElem`, `fileElem`
`@` mentions, quote replies	`atTextElem`, `quoteElem`
Merged forward, custom	`mergeElem`, `customElem`
Contact card, location, face	`cardElem`, `locationElem`, `faceElem`
Advanced text, typing status	`advancedTextElem`, `typingElem`
System notifications, auxiliary state	`notificationElem`, `attachedInfoElem`

The constants OpenIMMessageTypeUserCommandAdded, OpenIMMessageTypeUserCommandDeleted, and OpenIMMessageTypeUserCommandUpdated are OpenIMMessageType values used to recognize UserCommand business notifications. They are identified by evaluating contentType, not through separate event names.

Never evaluate message identity using display strings, array indices, or paginated list offsets. Always merge message states using conversationID:clientMsgID. Write device-specific display flags to localEx, while using ex or message payloads for business data that must synchronize across participants.

Message operation guides

Message creation and read-only query operations return the snapshot result of that single call without triggering shared message events. For state-modifying actions, Promise resolution, event notification, and re-querying current data represent three distinct and decoupled execution phases.

Was this page helpful?