Conversation overview
Understand conversations, conversation state, message options, and conversation grouping in the OpenIM React Native SDK.
In the OpenIM React Native SDK, a conversation represents the state of a chat session maintained by the currently authenticated account. Both direct one-to-one chats and group chats map to a ConversationItem, which encapsulates list display metadata, unread counters, drafts, and message reception preferences.
Conversations and chat targets use distinct identifiers: conversationID identifies the conversation record for the current account and acts as the unique primary key for client-side state merging; direct chat targets use the peer's userID, and group chat targets use the groupID. Group profiles, members, and permissions remain managed through group-specific APIs.
Conversation identifiers
| Identifier | Description |
|---|---|
conversationID | Unique primary key for the conversation record of the current account; used for settings, message history, and unread reconciliation. |
userID | Target user ID in direct 1-on-1 chats. |
groupID | Target group ID in group chats. |
sourceID | Target identifier when querying by type: supply userID for direct chats, or groupID for group chats. |
To compute the conversationID from a chat target without a network round-trip, invoke Get conversation ID with sourceID and sessionType.
Conversation properties
A ConversationItem contains display fields alongside account-level conversation settings:
| Category | Fields | Description |
|---|---|---|
| Identity & type | conversationID, conversationType | Locates the conversation and distinguishes between direct and group chats. |
| List display | showName, faceURL, latestMsg, latestMsgSendTime | Displays conversation title, avatar, and preview of the latest message. |
| Unread & mentions | unreadCount, groupAtType | Reflects unread badge counts and @ mention notifications. |
| Organization | isPinned, draftText, isMarkedEnterprise <span className="enterprise-field-badge">Commercial</span>, remarkEnterprise <span className="enterprise-field-badge">Commercial</span> | Controls pin-to-top, marking, message drafts, and custom remarks for the current user. |
| Message policy | recvMsgOpt, isPrivateChatEnterprise <span className="enterprise-field-badge">Commercial</span>, burnDurationEnterprise <span className="enterprise-field-badge">Commercial</span>, isMsgDestructEnterprise <span className="enterprise-field-badge">Commercial</span>, msgDestructTimeEnterprise <span className="enterprise-field-badge">Commercial</span> | Configures notification options, burn-after-reading, and automated message retention policies. |
| State & extensions | isNotInGroup, attachedInfo, ex | Indicates group membership status, SDK internal metadata, and custom business extensions. |
Browse by task
| Task | Guide |
|---|---|
| Retrieve conversations | Get conversation by target, Get conversations by ID, Retrieve conversation list |
| Organize conversations | Pin a conversation, Mark a conversation, Conversation groups overview |
| Manage drafts & remarks | Set conversation draft, Set conversation remark, Set conversation extension |
| Message policies | Set message receive options, Set burn duration, Automate server message destruction |
| Unread & mention handling | Mark conversation as read, Get total unread count, Clear group mentions |
Hiding, deleting, and clearing
Hiding, deleting, and clearing have distinct scopes:
| Action | Effect |
|---|---|
| Hide a conversation | Hides a single conversation from the current account's list; it reappears when a new message arrives. |
| Hide all conversations | Hides all conversation entries from the local list for the current account. |
| Delete conversation with messages | Removes the conversation entry and permanently deletes local and server messages for this account. |
| Clear conversation messages | Preserves the conversation entry while wiping all message records for this account. |
Event listeners
Conversation state mutations trigger asynchronous push events:
- Retrieve conversation list documents
OnNewConversationandOnConversationChangedlisteners. - Get total unread count documents
OnTotalUnreadMessageCountChanged. - Conversation groups overview documents group lifecycle and membership events.
Was this page helpful?