Conversation overview
Understand ConversationItem, conversationID, conversation settings, and conversation events in the WASM SDK.
In OpenIMSDK, a conversation is the client-side chat state maintained for a one-to-one or group chat. The signed-in user has one ConversationItem record for each conversation. It stores list state such as unread count, latest message, pinning, drafts, message reception options, and extension data. A conversation record and its chat target have separate identifiers: conversationID identifies the current account's conversation state, while a one-to-one target uses the other user's userID and a group target uses groupID.
Both one-to-one and group chats use conversation records for chat-list state. Group profiles, membership, and permissions remain under the group APIs. A group chat page uses groupID for group capabilities and conversationID for conversation settings, unread counts, drafts, and message history.
Conversation identifiers
A one-to-one conversation uses the target user ID as sourceID with SessionType.Single. A group conversation uses groupID as sourceID with SessionType.WorkingGroup. Call getConversationIDBySessionType() to obtain a stable conversationID, then use it for conversation settings, read state, hiding, and deletion.
| Identifier | Purpose |
|---|---|
conversationID | The current account's conversation record ID, used for conversation settings, message history, and unread state. |
userID | The other user's ID in a one-to-one conversation. |
groupID | The group ID for a group conversation and the target identifier for group APIs. |
sourceID | The chat target passed to a type-based conversation query: userID for a one-to-one conversation and groupID for a group conversation. |
Conversation data
ConversationItem contains both list display information and the current account's conversation settings. Its fields can be grouped by responsibility:
| Responsibility | Fields | Description |
|---|---|---|
| Identity and type | conversationID, conversationType | Locate the conversation record and distinguish one-to-one from group conversations. |
| List display | showName, faceURL, latestMsg, latestMsgSendTime | Render the conversation name, avatar, and latest message. |
| Unread state and reminders | unreadCount, groupAtType | Display the unread count and group mention reminders. |
| List organization | isPinned, isMarked, draftText, remark | Maintain pinning, marks, drafts, and a remark set by the current user. |
| Message policy | recvMsgOpt, isPrivateChat, burnDuration, isMsgDestruct, msgDestructTime | Control message reception, burn after reading, and scheduled server-message deletion. |
| Application extension | ex | Store the complete extension string defined by the application. |
Find pages by task
| Task | Pages |
|---|---|
| Get one, several, or a paginated list of conversations | Get a conversation by target, Get conversations by ID, Get the conversation list |
| Organize the conversation list | Pin or unpin a conversation, Mark or unmark a conversation, Conversation groups |
| Maintain drafts, remarks, and extension data | Set a conversation draft, Set a conversation remark, Set conversation extension data |
| Set message reception and retention policy | Set conversation message reception, Enable or disable burn after reading, Schedule server message deletion |
| Handle unread counts and group reminders | Mark a conversation as read, Track the total unread count, Reset group mention status |
Delete and clear data
Hiding, deleting, and clearing affect different scopes:
| Operation | Effect |
|---|---|
| Hide a conversation | Hide the record from the current client's conversation list. It may reappear when a new message arrives. |
| Delete a conversation and its messages | Delete the conversation record and its message data. |
| Clear messages in a conversation | Keep the conversation record but clear its messages. |
State updates
Queries provide the data shown when a page first opens, while events update later changes:
- Get the conversation list owns new-conversation and conversation-property events.
- Track the total unread count owns changes to the current account's total unread count.
- Conversation group overview owns conversation group changes.
The overview only links to the pages that explain each event and does not register handlers. An operation request succeeding, its related event arriving, and a later query returning the latest data are three separate stages. Do not infer the final conversation state from the user action alone.
Was this page helpful?