IMSDK
IM features a comprehensive suite of solutions including global access, one-to-one chat, group chat, message push, profile and relationship chain hosting, and account authentication. It also provides complete app access and backend management APIs.
V2TIMManager(Conversation)

Instance Methods

(void) - addConversationListener:
 
(void) - removeConversationListener:
 
(void) - getConversationList:count:succ:fail:
 
(void) - getConversation:succ:fail:
 
(void) - getConversationList:succ:fail:
 
(void) - getConversationListByFilter:nextSeq:count:succ:fail:
 
(void) - deleteConversation:succ:fail:
 
(void) - deleteConversationList:clearMessage:succ:fail:
 
(void) - setConversationDraft:draftText:succ:fail:
 
(void) - setConversationCustomData:customData:succ:fail:
 
(void) - pinConversation:isPinned:succ:fail:
 
(void) - markConversation:markType:enableMark:succ:fail:
 
(void) - getTotalUnreadMessageCount:fail:
 
(void) - getUnreadMessageCountByFilter:succ:fail:
 
(void) - subscribeUnreadMessageCountByFilter:
 
(void) - unsubscribeUnreadMessageCountByFilter:
 
(void) - cleanConversationUnreadMessageCount:cleanTimestamp:cleanSequence:succ:fail:
 
(void) - setConversationListener:
 
(void) - createConversationGroup:conversationIDList:succ:fail:
 
(void) - getConversationGroupList:fail:
 
(void) - deleteConversationGroup:succ:fail:
 
(void) - renameConversationGroup:newName:succ:fail:
 
(void) - addConversationsToGroup:conversationIDList:succ:fail:
 
(void) - deleteConversationsFromGroup:conversationIDList:succ:fail:
 

Member Typedef Documentation

◆ V2TIMConversationResultSucc

- (typedef void(^ V2TIMConversationResultSucc) (NSArray< V2TIMConversation * > *list, uint64_t nextSeq, BOOL isFinished))
protected

Callback definition on get conversation list successfully.

◆ V2TIMConversationSucc

- (typedef void(^ V2TIMConversationSucc) (V2TIMConversation *conv))
protected

Callback definition on get single conversation successfully.

◆ V2TIMConversationListSucc

- (typedef void(^ V2TIMConversationListSucc) (NSArray< V2TIMConversation * > *list))
protected

Callback definition on get specified conversation list successfully.

◆ V2TIMTotalUnreadMessageCountSucc

- (typedef void(^ V2TIMTotalUnreadMessageCountSucc) (UInt64 totalUnreadCount))
protected

Callback definition on get total count of unread messages successfully.

◆ V2TIMConversationGroupListSucc

- (typedef void(^ V2TIMConversationGroupListSucc) (NSArray< NSString * > *groupList))
protected

Callback definition on get conversation group list successfully.

◆ V2TIMConversationOperationResultSucc

- (typedef void(^ V2TIMConversationOperationResultSucc) (NSArray< V2TIMConversationOperationResult * > *result))
protected

Callback definition on operation conversation result.

Member Enumeration Documentation

◆ V2TIMConversationType

- (enum V2TIMConversationType) :
protected

Enumeration definition of conversation type.

Enumerator
V2TIM_UNKNOWN 

unknown

V2TIM_C2C 

One-to-one chat.

V2TIM_GROUP 

Group chat.

◆ V2TIMGroupAtType

- (enum V2TIMGroupAtType) :
protected

Enumeration definition of @ type.

Enumerator
V2TIM_AT_ME 

@me

V2TIM_AT_ALL 

@all

V2TIM_AT_ALL_AT_ME 

@all in the group and @me alone

◆ V2TIMConversationMarkType

- (enum V2TIMConversationMarkType) :
protected

Enumeration definition of conversation mark type.

Enumerator
V2TIM_CONVERSATION_MARK_TYPE_STAR 

Mark a conversation as star.

V2TIM_CONVERSATION_MARK_TYPE_UNREAD 

Mark a conversation as unread.

V2TIM_CONVERSATION_MARK_TYPE_FOLD 

Fold a conversation.

V2TIM_CONVERSATION_MARK_TYPE_HIDE 

Hide a conversation.

Method Documentation

◆ addConversationListener:()

- (void) addConversationListener: (addConversationListener(listener:))  NS_SWIFT_NAME

1.1 Add the conversation listener

◆ removeConversationListener:()

- (void) removeConversationListener: (removeConversationListener(listener:))  NS_SWIFT_NAME

1.2 Remove the conversation listener

◆ getConversationList:count:succ:fail:()

- (void) getConversationList: (uint64_t)  nextSeq
count: (int)  count
succ: (V2TIMConversationResultSucc succ
fail: (V2TIMFail)  fail 

1.3 Get the conversation list

  • Each conversation corresponds to a chat window. For example, a one-to-one chat or a chat group is a conversation.
  • Since there may be a large number of historical conversations, you are advised to call this API in query-by-page mode and pull 100 historical conversations per page at a time.
  • This API pulls locally cached conversations. If conversations on the server are updated, the SDK automatically synchronizes the updates internally and then notifies users via V2TIMConversationListener callback.
  • If all conversations are pulled, the value of the isFinished field in V2TIMConversationResult in the success callback is true.
Attention
Conversation sorting rules
  • For 5.5.892 and later versions, conversations on the conversion list obtained by this API are sorted by orderKey by default. The larger the orderKey value, the higher the order of the conversation.
  • For versions earlier than 5.5.892, conversations on the conversion list obtained by this API are sorted by "lastMessage -> timestamp" by default. The later the timestamp, the higher the order of the conversation.
Parameters
nextSeqPulling-by-page cursor. It is set to 0 when the information is pulled for the first time. The value of this field in the callback for the current paginated pulling is passed in for the next pull.
countNumber of conversations pulled per page. The value of this field cannot be too large; otherwise, the pulling speed is affected. We recommend that you pull 100 conversations per page.

◆ getConversation:succ:fail:()

- (void) getConversation: (NSString *)  conversationID
succ: (V2TIMConversationSucc succ
fail: (V2TIMFail)  fail 

1.4 Get a single conversation

Parameters
conversationIDUnique ID of a conversation. For one-to-one chats, the value format is String.format("c2c_%s", "userID"). For group chats, the value format is String.format("group_%s", "groupID").

◆ getConversationList:succ:fail:()

- (void) getConversationList: (NSArray< NSString * > *)  conversationIDList
succ: (V2TIMConversationListSucc succ
fail: (V2TIMFail)  fail 

1.5 Get a specified conversation list

Parameters
conversationIDListList of the unique IDs of conversations. For one-to-one chats, the value format is String.format("c2c_%s", "userID"). For group chats, the value format is String.format("group_%s", "groupID").

◆ getConversationListByFilter:nextSeq:count:succ:fail:()

- (void) getConversationListByFilter: (V2TIMConversationListFilter *)  filter
nextSeq: (uint64_t)  seq
count: (uint32_t)  count
succ: (V2TIMConversationResultSucc succ
fail: (V2TIMFail)  fail 

1.6 Get the conversation list (advanced API,supported only in 6.5 and later versions)

Parameters
filterThe conversation filter
seqThe pulling-by-page cursor
countNumber of conversations to be pulled per page

◆ deleteConversation:succ:fail:()

- (void) deleteConversation: (NSString *)  conversationID
succ: (V2TIMSucc)  succ
fail: (V2TIMFail)  fail 

1.7 Delete a conversation

Parameters
conversationIDUnique ID of a conversation. For one-to-one chats, the value format is String.format("c2c_%s", "userID"). For group chats, the value format is String.format("group_%s", "groupID").
Attention
  • When a conversation is deleted from local storage, it is also deleted from the server.
  • When messages in a conversation are deleted from local storage, they are also deleted from the server.

◆ deleteConversationList:clearMessage:succ:fail:()

- (void) deleteConversationList: (NSArray< NSString * > *)  conversationIDList
clearMessage: (BOOL)  clearMessage
succ: (V2TIMConversationOperationResultSucc succ
fail: (V2TIMFail)  fail 

1.8 Delete a list of conversations (Supported only in 7.1 and later versions)

Parameters
conversationIDListList of the unique IDs of conversations. For one-to-one chats, the value format is String.format("c2c_%s", "userID"). For group chats, the value format is String.format("group_%s", "groupID").
clearMessageWhether to delete messages in the conversation; if this is set to false, the messages are retained; if this is set to true, the messages will be deleted from local storage and the server and cannot be recovered.
Attention
A maximum of 100 conversations are supported at a time.

◆ setConversationDraft:draftText:succ:fail:()

- (void) setConversationDraft: (NSString *)  conversationID
draftText: (NSString *)  draftText
succ: (V2TIMSucc)  succ
fail: (V2TIMFail)  fail 

1.9 Set a draft for a conversation

Parameters
conversationIDUnique ID of a conversation. For one-to-one chats, the value format is String.format("c2c_%s", "userID"). For group chats, the value format is String.format("group_%s", "groupID").
draftTextDraft content. The value null indicates cancelling the draft.
Attention
Drafts are stored only locally. They are not stored on the server and cannot be synchronized across devices. If the app is reinstalled, drafts will be lost.

◆ setConversationCustomData:customData:succ:fail:()

- (void) setConversationCustomData: (NSArray< NSString * > *)  conversationIDList
customData: (NSData *)  customData
succ: (V2TIMConversationOperationResultSucc succ
fail: (V2TIMFail)  fail 

1.10 Set conversation custom data(supported only in 6.5 and later versions)

Parameters
customDataCustom data (max 256 bytes)

◆ pinConversation:isPinned:succ:fail:()

- (void) pinConversation: (NSString *)  conversationID
isPinned: (BOOL)  isPinned
succ: (V2TIMSucc)  succ
fail: (V2TIMFail)  fail 

1.11 Pin a conversion to the top (supported only in 5.3.425 and later versions)

Parameters
conversationIDUnique ID of a conversation. For one-to-one chats, the value format is String.format("c2c_%s", "userID"). For group chats, the value format is String.format("group_%s", "groupID").
isPinnedWhether to pin a conversation to the top

◆ markConversation:markType:enableMark:succ:fail:()

- (void) markConversation: (NSArray< NSString * > *)  conversationIDList
markType: (NSNumber *)  markType
enableMark: (BOOL)  enableMark
succ: (V2TIMConversationOperationResultSucc succ
fail: (V2TIMFail)  fail 

1.12 Mark a conversation(supported only in Chat Premium 6.5 and later versions)

Parameters
conversationIDListconversation list
markTypemark type of the conversation. For the valid values, see the V2TIMConversationMarkType definition.
enableMarktrue:mark false:unmark

If the existing mark does not meet your needs, you can customize the extension mark. The extension mark needs to meet the following two conditions:

1、Extended mark values ​​must not conflict with existing mark values ​​in V2TIIMConversationMarkType.

2、Extended mark values must be a 0x1LL << n (32 <= n < 64, that is, n must be greater than or equal to 32 and less than 64). For example, you can use the extension mark "0x1LL << 32" to mean "iPhone online".

Attention
: The extension mark value cannot be set to 0x1 << 32. It must be set to 0x1LL << 32, which explicitly tells the compiler that it is a 64-bit integer constant.

◆ getTotalUnreadMessageCount:fail:()

- (void) getTotalUnreadMessageCount: (V2TIMTotalUnreadMessageCountSucc succ
fail: (V2TIMFail)  fail 

1.13 Get the total message unread count of all conversations (supported only in 5.3.425 and later versions)

Attention
  • After you call this API to obtain the total count of unread messages for all conversations, the newest value will be notified to you through the onTotalUnreadMessageCountChanged callback when unread message count of any conversation changed.
  • The total unread message count excludes muted conversations (conversations whose message receiving option is V2TIM_NOT_RECEIVE_MESSAGE or V2TIM_RECEIVE_NOT_NOTIFY_MESSAGE or V2TIM_RECEIVE_NOT_NOTIFY_MESSAGE_EXCEPT_AT).

◆ getUnreadMessageCountByFilter:succ:fail:()

- (void) getUnreadMessageCountByFilter: (V2TIMConversationListFilter *)  filter
succ: (V2TIMTotalUnreadMessageCountSucc succ
fail: (V2TIMFail)  fail 

1.14 Get the total message unread count of conversations by filter (supported only in 7.0 and later versions)

Parameters
filterconversation filter
Attention
  • The total unread message count excludes muted conversations (conversations whose message receiving option is V2TIM_NOT_RECEIVE_MESSAGE or V2TIM_RECEIVE_NOT_NOTIFY_MESSAGE or V2TIM_RECEIVE_NOT_NOTIFY_MESSAGE_EXCEPT_AT).

◆ subscribeUnreadMessageCountByFilter:()

- (void) subscribeUnreadMessageCountByFilter: (V2TIMConversationListFilter *)  filter

1.15 Subscribe to changes in the total unread message count for specified conversations (supported only in 7.0 and later versions)

Parameters
filterconversation filter
Attention
  • After you call this API, the newest value of total unread message count for conversations that match the filter parameter will be notified to you through the onUnreadMessageCountChangedByFilter callback.

◆ unsubscribeUnreadMessageCountByFilter:()

- (void) unsubscribeUnreadMessageCountByFilter: (V2TIMConversationListFilter *)  filter

1.16 Unsubscribe from changes in the total unread message count for specified conversations (supported only in 7.0 and later versions)

Parameters
filterconversation filter

◆ cleanConversationUnreadMessageCount:cleanTimestamp:cleanSequence:succ:fail:()

- (void) cleanConversationUnreadMessageCount: (NSString *)  conversationID
cleanTimestamp: (uint64_t)  cleanTimestamp
cleanSequence: (uint64_t)  cleanSequence
succ: (V2TIMSucc)  succ
fail: (V2TIMFail)  fail 

1.17 Clear unread messages of a conversation (supported only in 7.1 and later versions)

Parameters
conversationIDUnique ID of a conversation. For one-to-one chats, the value format is [NSString stringWithFormat:"c2c_%",userID]. For group chats, the value format is [[NSString stringWithFormat:"group_%",groupID].
cleanTimestampThe timestamp (seconds) for clearing unread messages (only valid for one-to-one chats). Unread messages before the timestamp will be cleared. If the value is 0, all unread messages of the specified conversation will be cleared, and the unread message count will be set to 0.
cleanSequenceThe sequence for clearing unread messages (only valid for group chats). Unread messages before the specified message sequence will be cleared. If the value is 0, all unread messages of the specified conversation will be cleared, and the unread message count will be set to 0.
Attention
  • If you want to clear the unread messages of all a one-to-one conversation, set conversationID to "c2c", i.e., don't specify the userID.
  • If you want to clear the unread messages of all group conversations, set conversationID to "group", i.e., don't specify the groupID.
  • If you want to clear the unread messages of all conversations, set conversationID to "" or nil.
  • After the API is successfully called, you will receive the onConversationChanged callback that carries the latest unread message number of the corresponding conversation.

◆ setConversationListener:()

- (void) setConversationListener: (id< V2TIMConversationListener >)  listener

1.18 Set the conversation listener

Attention
It is deprecated and discouraged to call this function. Please call APIs ref addConversationListener and removeConversationListener instead.

◆ createConversationGroup:conversationIDList:succ:fail:()

- (void) createConversationGroup: (NSString *)  groupName
conversationIDList: (NSArray< NSString * > *)  conversationIDList
succ: (V2TIMConversationOperationResultSucc succ
fail: (V2TIMFail)  fail 

2.1 Create a conversation group.

Parameters
groupNamegroup name(Required, length must be greater than 0, max 32 bytes)
conversationIDListconversation ID list(Required, cannot be empty)
Attention
A maximum of 20 conversation groups are supported. Please delete the groups that are no longer in use.

◆ getConversationGroupList:fail:()

- (void) getConversationGroupList: (V2TIMConversationGroupListSucc succ
fail: (V2TIMFail)  fail 

2.2 Get a list of conversation groups.

Attention
This API pulls locally cached conversation groups. It is recommended to call after onSyncServerFinish.

◆ deleteConversationGroup:succ:fail:()

- (void) deleteConversationGroup: (NSString *)  groupName
succ: (V2TIMSucc)  succ
fail: (V2TIMFail)  fail 

2.3 Delete a conversation group.

◆ renameConversationGroup:newName:succ:fail:()

- (void) renameConversationGroup: (NSString *)  oldName
newName: (NSString *)  newName
succ: (V2TIMSucc)  succ
fail: (V2TIMFail)  fail 

2.4 Rename a conversation group.

◆ addConversationsToGroup:conversationIDList:succ:fail:()

- (void) addConversationsToGroup: (NSString *)  groupName
conversationIDList: (NSArray< NSString * > *)  conversationIDList
succ: (V2TIMConversationOperationResultSucc succ
fail: (V2TIMFail)  fail 

2.5 Add conversations to a group.

◆ deleteConversationsFromGroup:conversationIDList:succ:fail:()

- (void) deleteConversationsFromGroup: (NSString *)  groupName
conversationIDList: (NSArray< NSString * > *)  conversationIDList
succ: (V2TIMConversationOperationResultSucc succ
fail: (V2TIMFail)  fail 

2.6 Remove conversations from a group.