Conversations overview
Understand the responsibilities of OIMConversationInfo, conversationID, conversation settings, and conversation events in OpenIM iOS SDK.
In the OpenIM architecture, a conversation encapsulates the local client state maintained for a direct 1-on-1 chat or group session, represented by an OIMConversationInfo object. It tracks list presentation states including unread counts, latest messages, pinned statuses, drafts, message reception preferences, and custom extension strings. Conversation records are identified separately from their underlying chat targets: conversationID identifies the authenticated user's personal conversation session, whereas direct chat targets use the recipient's userID and group chat targets use groupID.
Both direct and group chats maintain chat-list states via conversation records. Group metadata, member lists, and role permissions remain managed under the Group API domain. Group chat views consume groupID for group member capabilities, while utilizing conversationID for conversation settings, unread counts, drafts, and message history.
Conversation identifiers
Direct 1-on-1 conversations use the peer user ID as sourceID with conversation type OIMConversationTypeC2C. Group conversations use groupID as sourceID with conversation type OIMConversationTypeGroup. Invoke Generate a conversation ID to obtain a deterministic conversationID for conversation settings, read marks, hiding, and message clearance.
| Identifier | Purpose |
|---|---|
conversationID | Personal conversation record ID for the signed-in account; routes settings, message history, and unread states. |
userID | Target peer user ID for direct 1-on-1 conversations. |
groupID | Target group ID for group chats, serving as the entity key for Group APIs. |
sourceID | Target entity ID used in type-based queries: userID for 1-on-1 chats, or groupID for group chats. |
OIMConversationInfo properties
| Property | Description |
|---|---|
conversationID | Unique conversation identifier. |
conversationType | OIMConversationType enum indicating conversation category. |
userID / groupID | Target peer user ID or group ID for the conversation. |
showName / faceURL | Resolved display name and avatar URL for UI rendering. |
unreadCount | Unread message count for this conversation. |
latestMsg / latestMsgSendTime | Last message content preview and its send timestamp in milliseconds. |
recvMsgOpt | OIMReceiveMessageOpt message reception and notification setting. |
groupAtType | OIMGroupAtType mention state (e.g., at-all, at-me). |
draftText / draftTextTime | Draft message text and last update timestamp. |
isPinned | Whether the conversation is pinned to the top of the chat list. |
isPrivateChatEnterprise / burnDuration Enterprise | Burn-after-reading private chat toggle and countdown duration in seconds. |
isMsgDestructEnterprise / msgDestructTime Enterprise | Scheduled server message deletion toggle and destruction cycle. |
isNotInGroup | Whether the current user has left or been removed from the group. |
attachedInfo | Reserved SDK metadata string. |
ex | Custom application-defined extension string. |
Feature navigation
- Retrieve a conversation by chat target
- Retrieve conversations by ID
- Retrieve the conversation list
- Pin or unpin a conversation
- Set message reception for a conversation
- Enable or disable burn after reading
- Set the burn-after-reading duration
- Periodically delete server-side messages
- Set the server message deletion cycle
- Reset group-mention state
- Set the conversation extension field
- Set a conversation draft
- Mark a conversation as read
- Maintain the total unread count
Conversation lifecycle
- Hide a conversation
- Hide all conversations
- Delete a conversation and its messages
- Clear conversation messages
Conversation groups
Conversation groups overview explains how to classify conversations into user-defined folders. Members are referenced by conversationID, while the group itself uses conversationGroupID. Conversation grouping reorganizes personal chat presentation without creating group chats or altering groupID, group metadata, or membership.
The iOS SDK exposes conversation grouping through OpenIMCore JSON interfaces bundled with the SDK and tracks updates via a single conversation group listener. Query calls return current category snapshots. Group updates merge by conversationGroupID, and member associations merge by conversationGroupID and conversationID.
State synchronization
Query APIs establish initial data snapshots, while delegate methods merge subsequent changes:
- New conversations and property alterations are observed in Retrieve the conversation list.
- Account-level total unread changes are observed in Maintain the total unread count.
Treat API completion callbacks, asynchronous delegate events, and reconciliation queries as distinct operational phases. Never assume remote multi-terminal synchronization has completed solely because a local write callback returned successfully.
Was this page helpful?