Conversations overview
Understand ConversationInfo, conversationID, conversation settings, and event responsibilities in the OpenIM Flutter SDK.
In OpenIM, a Conversation encapsulates the chat state maintained locally by the client for a single-chat or group-chat channel. It is represented by a ConversationInfo record scoped to the currently signed-in user. It holds list-level state including unread counts, latest messages, pin status, drafts, notification reception options, and custom extensions. A conversation record is distinguished from chat destinations: conversationID identifies the conversation state of the active account, single-chat targets use the counterparty's userID, and group-chat targets use groupID.
Both single-chat and group-chat channels project their list status onto conversation records; group metadata, membership relations, and permissions remain governed by Group APIs. A group chat view uses groupID to access group capabilities while using conversationID to manage conversation settings, unread counts, drafts, and message history.
Conversation identifiers
Single-chat conversations use the counterparty user ID as sourceID with conversationType set to ConversationType.single; group-chat conversations use groupID as sourceID with conversationType set to ConversationType.superGroup. Call Get conversation ID to obtain a deterministic conversationID before invoking conversation settings, read receipts, hiding, or message deletion.
| Identifier | Purpose |
|---|---|
conversationID | Local conversation record ID of the active account. Used for settings, history queries, and unread states. |
userID | Counterparty user ID in a single-chat conversation. |
groupID | Target group ID in a group-chat conversation; also used for Group APIs. |
sourceID | Target ID passed when querying by session type: userID for single chat, groupID for group chat. |
ConversationInfo
Key fields in ConversationInfo:
| Field | Description |
|---|---|
conversationID | Conversation ID. |
conversationType | Conversation type. |
userID | Counterparty user ID in single chats. |
groupID | Target group ID in group chats. |
showName | Display name of the conversation. |
faceURL | Display avatar URL of the conversation. |
unreadCount | Unread message count of this conversation. |
latestMsg | The most recent message payload. |
latestMsgSendTime | Timestamp when the latest message was sent. |
recvMsgOpt | Message reception option for this conversation. |
groupAtType | Mention notification state in group chats. |
draftText | Local draft message content. |
draftTextTime | Timestamp when the draft was updated. |
isPinned | Whether the conversation is pinned to the top. |
isPrivateChat Enterprise | Whether private chat mode is enabled. |
isMsgDestruct Enterprise | Whether message auto-destruction is enabled. |
burnDuration Enterprise | Self-destruct countdown duration in seconds. |
msgDestructTime Enterprise | Message destruction time configuration. |
ex | Custom business extension string. |
Queries and settings
- Get conversation by target
- Get conversations by ID
- Retrieve conversation list
- Pin or unpin a conversation
- Set conversation message receive option
- Set private chat
- Set message destruct
- Clear group mentions
- Set conversation extension
- Set conversation draft
- Mark conversation as read
- Get total unread count
Conversation lifecycle
Conversation groups
Conversation groups overview covers organizing conversations into custom folders or tags. Group entries use conversationID, while the group itself uses conversationGroupID. It only reorganizes conversations for the current account; it does not create chat groups or alter groupID membership or permissions.
The Flutter SDK provides this capability through ConversationGroupManager. Queries return folder hierarchies, group events update by conversationGroupID, and member events update by combining conversationGroupID with conversationID. The overview page provides data models, complete listener setup, and links to individual APIs.
State synchronization
Query methods load the initial snapshot required by the view, while events merge subsequent incremental changes:
- New conversations and conversation property changes are monitored centrally in Retrieve conversation list.
- Account-wide total unread changes are monitored centrally in Get total unread count.
Register listeners centrally within dedicated capability modules rather than fragmenting listeners across Widget trees. Future completion, subsequent event arrivals, and query recalibrations represent distinct lifecycle phases; handle each explicitly rather than assuming immediate state transitions based on local user interactions.
Was this page helpful?