IMSDK
即时通信 IM 提供全球接入、单聊、群聊、消息推送、资料关系链托管、账号鉴权等全方位解决方案,并提供完备的 App 接入、后台管理接口。
V2TIMManager(Conversation)

构造函数

(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:
 

成员类型定义说明

◆ V2TIMConversationResultSucc

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

获取会话列表成功的回调,nextSeq:下一次分页拉取的游标 isFinished:会话列表是否已经拉取完毕

◆ V2TIMConversationSucc

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

获取单个会话成功回调

◆ V2TIMConversationListSucc

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

搜索会话列表成功回调

◆ V2TIMTotalUnreadMessageCountSucc

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

获取会话总未读数回调

◆ V2TIMConversationGroupListSucc

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

获取会话分组列表成功回调

◆ V2TIMConversationOperationResultSucc

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

会话操作成功回调

成员枚举类型说明

◆ V2TIMConversationType

- (enum V2TIMConversationType) :
protected

会话类型

枚举值
V2TIM_UNKNOWN 

未知

V2TIM_C2C 

单聊

V2TIM_GROUP 

群聊

◆ V2TIMGroupAtType

- (enum V2TIMGroupAtType) :
protected

@ 类型

枚举值
V2TIM_AT_ME 

@ 我

V2TIM_AT_ALL 

@ 群里所有人

V2TIM_AT_ALL_AT_ME 

@ 群里所有人并且单独 @ 我

◆ V2TIMConversationMarkType

- (enum V2TIMConversationMarkType) :
protected

会话标记类型

枚举值
V2TIM_CONVERSATION_MARK_TYPE_STAR 

会话标星

V2TIM_CONVERSATION_MARK_TYPE_UNREAD 

会话标记未读(重要会话)

V2TIM_CONVERSATION_MARK_TYPE_FOLD 

会话折叠

V2TIM_CONVERSATION_MARK_TYPE_HIDE 

会话隐藏

函数文档

◆ addConversationListener:()

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

1.1 添加会话监听器

◆ removeConversationListener:()

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

1.2 移除会话监听器

◆ getConversationList:count:succ:fail:()

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

1.3 获取会话列表

  • 一个会话对应一个聊天窗口,比如跟一个好友的 1v1 聊天,或者一个聊天群,都是一个会话。
  • 由于历史的会话数量可能很多,所以该接口希望您采用分页查询的方式进行调用,每次分页拉取的个数建议为 100 个。
  • 该接口拉取的是本地缓存的会话,如果服务器会话有更新,SDK 内部会自动同步,然后在 V2TIMConversationListener 回调告知客户。
  • 如果会话全部拉取完毕,成功回调里面 V2TIMConversationResult 中的 isFinished 获取字段值为 YES。
注意
会话排序规则
  • 5.5.892 及以后版本, 该接口获取的会话列表默认已经按照会话 orderKey 做了排序,orderKey 值越大,代表该会话排序越靠前。
  • 5.5.892 以前版本,该接口获取的会话列表默认已经按照会话 lastMessage -> timestamp 做了排序,timestamp 越大,会话越靠前。
参数
nextSeq分页拉取的游标,第一次默认取传 0,后续分页拉传上一次分页拉取成功回调里的 nextSeq
count分页拉取的个数,一次分页拉取不宜太多,会影响拉取的速度,建议每次拉取 100 个会话

◆ getConversation:succ:fail:()

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

1.4 获取单个会话

参数
conversationID会话唯一 ID, C2C 单聊组成方式:[NSString stringWithFormat:"c2c_%",userID];群聊组成方式为 [NSString stringWithFormat:"group_%",groupID]

◆ getConversationList:succ:fail:()

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

1.5 获取指定会话列表

参数
conversationIDList会话唯一 ID 列表,C2C 单聊组成方式:[NSString stringWithFormat:"c2c_%",userID];群聊组成方式为 [NSString stringWithFormat:"group_%",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 获取会话列表高级接口(从 6.5 版本开始支持)

参数
filter会话 filter
nextSeq分页拉取的游标
count分页拉取的个数

◆ deleteConversation:succ:fail:()

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

1.7 删除会话以及该会话中的历史消息

参数
conversationID会话唯一 ID,C2C 单聊组成方式:[NSString stringWithFormat:"c2c_%",userID];群聊组成方式为 [NSString stringWithFormat:"group_%",groupID]
注意
  • 该会话以及会话中的历史消息,会被 SDK 从本地和服务端一同删除掉,并且不可恢复。

◆ deleteConversationList:clearMessage:succ:fail:()

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

1.8 删除会话列表(7.1 及以上版本支持)

参数
conversationIDList会话唯一 ID 列表,C2C 单聊组成方式:[NSString stringWithFormat:"c2c_%",userID];群聊组成方式为 [NSString stringWithFormat:"group_%",groupID]
clearMessage是否删除会话中的消息;设置为 NO 时,保留会话消息;设置为 YES 时,本地和服务器的消息会一起删除,并且不可恢复
注意
每次最多支持删除 100 个会话

◆ setConversationDraft:draftText:succ:fail:()

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

1.9 设置会话草稿

参数
conversationID会话唯一 ID,C2C 单聊组成方式:[NSString stringWithFormat:"c2c_%",userID];群聊组成方式为 [NSString stringWithFormat:"group_%",groupID]

只在本地保存,不会存储 Server,不能多端同步,程序卸载重装会失效。

◆ setConversationCustomData:customData:succ:fail:()

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

1.10 设置会话自定义数据(从 6.5 版本开始支持)

参数
customData自定义数据,最大支持 256 bytes

◆ pinConversation:isPinned:succ:fail:()

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

1.11 设置会话置顶(5.3.425 及以上版本支持)

参数
conversationID会话唯一 ID,C2C 单聊组成方式:[NSString stringWithFormat:"c2c_%",userID];群聊组成方式为 [NSString stringWithFormat:"group_%",groupID]
isPinned是否置顶

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

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

1.12 标记会话(从 6.5 版本开始支持,需要您购买旗舰版套餐)

参数
conversationIDList会话列表
markType会话标记类型,取值详见 @V2TIMConversationMarkType。
enableMarkYES:设置标记 NO:取消标记

如果已有标记不能满足您的需求,您可以自定义扩展标记,扩展标记需要满足以下两个条件: 1、扩展标记值不能和 V2TIMConversationMarkType 已有的标记值冲突 2、扩展标记值必须是 0x1LL << n 的位移值(32 <= n < 64,即 n 必须大于等于 32 并且小于 64),比如扩展标记值 0x1LL << 32 表示 "iPhone 在线"

注意
: 扩展标记值不能设置为 0x1 << 32,要设置为 0x1LL << 32,明确告诉编译器是 64 位的整型常量。

◆ getTotalUnreadMessageCount:fail:()

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

1.13 获取所有会话的未读消息总数(5.3.425 及以上版本支持)

注意
  • 调用该接口以后,任意会话的未读数发生变化时,SDK 都会给您抛 onTotalUnreadMessageCountChanged 回调。
  • 未读总数会减去设置为免打扰的会话的未读数,即消息接收选项设置为 V2TIMMessage.V2TIM_NOT_RECEIVE_MESSAGE 或 V2TIMMessage.V2TIM_RECEIVE_NOT_NOTIFY_MESSAGE 或 V2TIMMessage.V2TIM_RECEIVE_NOT_NOTIFY_MESSAGE_EXCEPT_AT 的会话。

◆ getUnreadMessageCountByFilter:succ:fail:()

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

1.14 获取根据 filter 过滤的会话未读总数(7.0 及以上版本支持)

参数
filter会话 filter
注意
  • 未读总数会减去设置为免打扰的会话的未读数,即消息接收选项设置为 V2TIMMessage.V2TIM_NOT_RECEIVE_MESSAGE 或 V2TIMMessage.V2TIM_RECEIVE_NOT_NOTIFY_MESSAGE 或 V2TIMMessage.V2TIM_RECEIVE_NOT_NOTIFY_MESSAGE_EXCEPT_AT 的会话。

◆ subscribeUnreadMessageCountByFilter:()

- (void) subscribeUnreadMessageCountByFilter: (V2TIMConversationListFilter *)  filter

1.15 注册监听指定 filter 的会话未读总数变化(7.0 及以上版本支持)

参数
filter会话 filter
注意
  • 当您调用这个接口以后,该 filter 下的未读数发生变化时,SDK 会给您抛 onUnreadMessageCountChangedByFilter 回调。

◆ unsubscribeUnreadMessageCountByFilter:()

- (void) unsubscribeUnreadMessageCountByFilter: (V2TIMConversationListFilter *)  filter

1.16 取消监听指定 filter 的会话未读总数变化(7.0 及以上版本支持)

参数
filter会话 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 清理会话的未读消息计数(7.1 及以上版本支持)

参数
conversationID会话唯一 ID, C2C 单聊组成方式:[NSString stringWithFormat:"c2c_%",userID];群聊组成方式为 [NSString stringWithFormat:"group_%",groupID]
cleanTimestamp清理时间戳,单位为秒,仅对单聊会话生效,指定清理哪一个 timestamp 之前的未读消息计数;当传入为 0 时,对应会话所有的未读消息将被清理,会话的未读数会清 0
cleanSequence清理 sequence,仅对群聊会话生效,指定清理哪一个 sequence 之前的未读消息计数;当传入为 0 时,对应会话所有的未读消息将被清理,会话的未读数会清 0
注意
  • 当您想清理所有单聊会话的未读消息计数,conversationID 请传入 "c2c",即不指定具体的 userID; - 当您想清理所有群聊会话的未读消息计数,conversationID 请传入 @"group",即不指定具体的 groupID;
  • 当您想清理所有会话的未读消息计数,conversationID 请传入 @“” 或者 nil;
  • 该接口调用成功后,SDK 会通过 onConversationChanged 回调将对应会话的最新未读数通知给您。

◆ setConversationListener:()

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

1.18 设置会话监听器(待废弃接口,请使用 addConversationListener 和 removeConversationListener 接口)

◆ createConversationGroup:conversationIDList:succ:fail:()

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

2.1 创建会话分组

参数
groupName分组名(必填参数,长度要 > 0,最大支持 32 bytes)
conversationIDList会话 ID 列表(必填参数,不能为空)
注意
会话分组最大支持 20 个,不再使用的分组请及时删除。

◆ getConversationGroupList:fail:()

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

2.2 获取会话分组列表

注意
该接口获取的是本地缓存的会话分组,建议在 onSyncServerFinish 之后调用。

◆ deleteConversationGroup:succ:fail:()

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

2.3 删除会话分组

◆ renameConversationGroup:newName:succ:fail:()

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

2.4 重命名会话分组

◆ addConversationsToGroup:conversationIDList:succ:fail:()

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

2.5 添加会话到一个会话分组

◆ deleteConversationsFromGroup:conversationIDList:succ:fail:()

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

2.6 从一个会话分组中删除会话