SDKsAndroidIncludes Enterprise features

Message overview

Learn about the Android SDK Message model, message lifecycle, and message listener.

The Android SDK uses the Message model to represent an individual message. Creating, sending, receiving, querying, and updating message states are distinct stages in the messaging lifecycle: creating a Message object does not transmit it to the server, and a successful send callback indicates server ingestion, not immediate receipt by recipient clients.

Message lists use clientMsgID as the client-side deduplication and update key, combined with the conversation context to distinguish between single (C2C) and group chats. The Message entity itself does not store a conversationID; the conversation context is derived from the active conversation, query arguments, or message event context.

Message lifecycle stages

Stage	Android API or callback	Description
Create	Message construction methods (such as Create a text message)	Constructs a local `Message` entity. Does not upload data to the server or trigger new-message callbacks.
Send	Send a message or Send a message without OSS upload	Pass `recvUid` for single chat or `recvGid` for group chat.
Receive	`OnAdvanceMsgListener`	Handles incoming real-time, offline, and online messages, as well as revokes, deletions, and read receipts.
Query	History retrieval, search, or find-by-ID APIs	Retrieves a point-in-time snapshot of stored messages; does not replace real-time event listeners.
Update	Revoke, delete, modify, pin, read receipts, and local extension APIs	Updates individual messages via API callbacks, async events, and list re-queries.

Incoming message events are documented in detail on the Receive messages page. Applications should configure OnAdvanceMsgListener once within a shared messaging repository or service layer and dispatch updates to active UI controllers.

Message model fields

All creation, transmission, reception, and retrieval operations interact with Message objects. Common fields include:

Field	Type	Description
`clientMsgID`	`String`	Client-generated unique message identifier, used for local deduplication and state updates.
`serverMsgID`	`String`	Server-assigned message ID. May be empty until the message is acknowledged by the server.
`sessionType`	`int`	Session type, used with `recvID` and `groupID` to determine single or group chat.
`sendID`	`String`	Sender user ID.
`recvID`	`String`	Recipient user ID for single chat conversations.
`groupID`	`String`	Group ID for group chat conversations.
`msgFrom`	`int`	Distinguishes between user-generated and system-generated messages.
`contentType`	`int`	Message content type, matching constants in `MessageType`.
`createTime`	`long`	Timestamp in nanoseconds when the message object was created.
`sendTime`	`long`	Timestamp in milliseconds when the message was sent.
`seq`	`int`	Server-assigned sequence number.
`status`	`int`	Message delivery status, matching constants in `MessageStatus`.
`isRead`	`boolean`	Local read status on the current client.
`platformID`	`int`	Platform identifier of the sending client.
`senderNickname`	`String`	Sender nickname recorded when the message was created or sent.
`senderFaceUrl`	`String`	Sender avatar URL recorded when the message was created or sent.
`offlinePush`	`OfflinePushInfo`	Push notification configuration for offline recipients.
`attachedInfo`	`String`	SDK internal attachment string.
`ext`	`Object`	Additional message extension attributes.
`ex`	`Object`	Custom business extension attributes.
`localEx`	`Object`	Local extension attributes persisted only on the local device.

Message content payloads are stored in specific element fields corresponding to contentType:

Content type	Element field
Text, rich text	`textElem`, `advancedTextElem`
Image, sound, video, file	`pictureElem`, `soundElem`, `videoElem`, `fileElem`
`@` mentions, replies	`atTextElem`, `quoteElem`
Merged forward	`mergeElem`
Contact card, location, custom faces	`cardElem`, `locationElem`, `faceElem`
Custom business message	`customElem`
Notifications, typing indicator, attached status	`notificationElem`, `typingElem`, `attachedInfoElem`

Creating and sending messages

Sending any message requires two steps:

Call the corresponding message creation method (such as Create a text message) to generate a Message object.
Pass the Message instance to Send a message, specifying recvUid for single chat or recvGid for group chat.

Supported message creation guides:

Content type	Guide
Plain text & Rich text	Create a text message, Create an advanced text message
`@` Mention messages	Create a text-at message
Media (Image, Audio, Video, File)	Create an image message, Create a sound message, Create a video message, Create a file message
Contact cards, Location, Custom faces	Create a card message, Create a location message, Create a face message
Replies, Forwarding, Merged forwarding	Create a quote message, Create a forward message, Create a merger message
Custom business payloads	Create a custom message

When sending media messages initialized from a local file path, use Send a message so the SDK automatically uploads the binary payload. When creating media messages with pre-uploaded remote URLs, use the corresponding URL creation method and send with Send a message without OSS upload to skip redundant file uploads.

Common messaging tasks

Task	Guide
Send messages	Send a message, Send a message without OSS upload
Receive messages	Receive messages, Receive custom business messages
Load message history	Load older messages, Load newer messages
Search and locate messages	Find messages by ID, Search messages
Revoke, delete, modify, or pin messages	Revoke a message, Delete saved messages, Modify a message, Pin or unpin a message
Read receipts and unread tracking	Mark conversation as read, Send group read receipts, Get group message readers
Typing indicators	Update typing status, Get typing status
Local-only messages & Local extensions	Insert local single message, Delete local message, Set message local extra data

State synchronization model

State change	Event / Callback	Synchronization approach
New and offline messages	Receive messages	Determine the conversation context, then deduplicate and insert by `clientMsgID`.
Message revocation	`onRecvMessageRevokedV2`	Update the revoked message state in-place using the message ID from the revoke payload.
Message deletion	`onMsgDeleted`Enterprise	Remove the matching message from the local UI cache using `clientMsgID`.
C2C and group read receipts	`onRecvC2CReadReceipt`, `onRecvGroupMessageReadReceipt`Enterprise	Update the read status and reader counts for matching messages.
Message extension updates	`onRecvMessageExtensionsChanged`	Update the extension fields for the targeted message ID without replacing the message body.
Typing indicator	Update typing status	Maintain transient typing state per conversation without inserting into the message list.

Always process the immediate API callback result before waiting for listener events from OnAdvanceMsgListener. When local caches diverge after reconnection, re-query the message list to calibrate state.

Was this page helpful?