Conversation overview
Understand ConversationInfo, conversationID, conversation settings, and event handling in the OpenIM Android SDK.
A conversation maintains chat-list state for the authenticated user in a direct or group chat, represented by a ConversationInfo entity. It tracks unread counts, latest messages, pinning status, drafts, message reception options, and custom extension fields. A conversationID uniquely identifies a conversation and serves as the primary key when querying conversation metadata and updating conversation settings. In direct chats, the target is the peer userID; in group chats, the target is the groupID.
Group profiles, membership rosters, and permission management belong to group capabilities. Group chat screens use groupID when calling Group APIs, and use conversationID when managing conversation settings, unread counts, drafts, and message purging.
Conversation identifiers
| Identifier | Purpose |
|---|---|
conversationID | Unique conversation record ID for the current account, used for conversation settings, unread states, and message history. |
userID | Target user ID in a direct chat. |
groupID | Target group ID in a group chat, also used as the target identifier in Group APIs. |
sourceId | Target passed when generating or querying conversation IDs: userID for direct chats, groupID for group chats. |
Conversation data
| Field | Description |
|---|---|
conversationID | Unique conversation identifier. |
conversationType | Conversation type: ConversationType.SINGLE_CHAT for direct chats; ConversationType.GROUP_CHAT or ConversationType.SUPER_GROUP_CHAT for group chats. |
userID / groupID | userID identifies the peer user in direct chats; groupID identifies the destination group in group chats. Exactly one is populated. |
showName | Conversation display name: peer user's nickname or remark in direct chats; group name or remark in group chats. |
faceURL | Conversation avatar URL. |
unreadCount | Unread message count for this conversation. |
latestMsg | JSON string representation of the latest message. |
latestMsgSendTime | Unix timestamp (in milliseconds) of the latest message. |
recvMsgOpt | Message reception option for this conversation. |
groupAtType | Group mention reminder status. |
draftText | Draft message text. |
draftTextTime | Unix timestamp when the draft was last updated. |
isPinned | Whether the conversation is pinned to the top of the list. |
isPrivateChat Enterprise | Whether burn-after-reading mode is enabled. |
burnDuration Enterprise | Reading duration (in seconds) before messages are destroyed in burn-after-reading mode. |
isMsgDestruct Enterprise | Whether scheduled server-side message deletion is active. |
msgDestructTime Enterprise | Retention duration for scheduled server-side message deletion. |
ext | Reserved conversation extension string. |
ex | Custom application-defined extension string. |
isNotInGroup | Indicates whether the current user is no longer a member of the group. |
Navigation by task
| Task | Documentation page |
|---|---|
| Query a single conversation, batch conversations, or paginated lists | Get a conversation by target, Get conversations by ID, Get the conversation list |
| Generate a conversation ID | Generate a conversation ID |
| Organize conversation listings | Pin or unpin a conversation, Hide a conversation |
| Manage drafts and extension fields | Set a conversation draft, Set conversation extension data |
| Configure message reception and retention rules | Set conversation message reception, Enable or disable burn after reading, Set burn-after-reading duration, Schedule server message deletion |
| Manage unread counters and group mentions | Mark a conversation as read, Get the total unread count, Reset group mention status |
| Delete or purge conversation data | Delete a conversation and its messages, Clear messages in a conversation |
State updates
After registering OnConversationListener at the application layer, the client receives real-time event notifications for conversation list modifications and total unread count adjustments. Merge incremental changes and deduplicate items using conversationID as the primary key. For complete listener configuration, see Get the conversation list:
onNewConversation: Delivers newly created conversations to insert at the top or into custom sorted order.onConversationChanged: Delivers conversations with modified attributes, such as unread count, latest message, pinning status, or draft changes.onTotalUnreadMessageCountChanged: Delivers updates to the overall unread message counter for badge rendering.
ConversationManager retains a single listener instance; subsequent calls replace previously registered listeners. When logging out or switching accounts, reset event dispatching logic accordingly.
Was this page helpful?