TIMConversationManagerFunction.h 文件参考

类型定义
typedef void(*	TIMConvEventCallback) (enum TIMConvEvent conv_event, const char *json_conv_array, const void *user_data)
typedef void(*	TIMConvTotalUnreadMessageCountChangedCallback) (int total_unread_count, const void *user_data)
typedef void(*	TIMConvTotalUnreadMessageCountChangedByFilterCallback) (const char *filter, int total_unread_count, const void *user_data)
typedef void(*	TIMConvConversationGroupCreatedCallback) (const char *group_name, const char *conversation_array, const void *user_data)
typedef void(*	TIMConvConversationGroupDeletedCallback) (const char *group_name, const void *user_data)
typedef void(*	TIMConvConversationGroupNameChangedCallback) (const char *old_name, const char *new_name, const void *user_data)
typedef void(*	TIMConvConversationsAddedToGroupCallback) (const char *group_name, const char *conversation_array, const void *user_data)
typedef void(*	TIMConvConversationsDeletedFromGroupCallback) (const char *group_name, const char *conversation_array, uint32_t reason, const void *user_data)

函数
TIM_API void	TIMSetConvEventCallback (TIMConvEventCallback cb, const void *user_data)
TIM_API void	TIMSetConvTotalUnreadMessageCountChangedCallback (TIMConvTotalUnreadMessageCountChangedCallback cb, const void *user_data)
TIM_API void	TIMSetConvUnreadMessageCountChangedByFilterCallback (TIMConvTotalUnreadMessageCountChangedByFilterCallback cb, const void *user_data)
TIM_API void	TIMSetConvConversationGroupCreatedCallback (TIMConvConversationGroupCreatedCallback cb, const void *user_data)
TIM_API void	TIMSetConvConversationGroupDeletedCallback (TIMConvConversationGroupDeletedCallback cb, const void *user_data)
TIM_API void	TIMSetConvConversationGroupNameChangedCallback (TIMConvConversationGroupNameChangedCallback cb, const void *user_data)
TIM_API void	TIMSetConvConversationsAddedToGroupCallback (TIMConvConversationsAddedToGroupCallback cb, const void *user_data)
TIM_API void	TIMSetConvConversationsDeletedFromGroupCallback (TIMConvConversationsDeletedFromGroupCallback cb, const void *user_data)
TIM_API int	TIMConvGetConvList (TIMCommCallback cb, const void *user_data)
TIM_API int	TIMConvGetConvInfo (const char *json_get_conv_list_param, TIMCommCallback cb, const void *user_data)
TIM_API int	TIMConvGetConversationListByFilter (const char *filter, uint64_t next_seq, uint32_t count, TIMCommCallback cb, const void *user_data)
TIM_API int	TIMConvDelete (const char *conv_id, enum TIMConvType conv_type, TIMCommCallback cb, const void *user_data)
TIM_API int	TIMConvDeleteConversationList (const char *conversation_id_array, bool clear_message, TIMCommCallback cb, const void *user_data)
TIM_API int	TIMConvSetDraft (const char *conv_id, enum TIMConvType conv_type, const char *json_draft_param)
TIM_API int	TIMConvCancelDraft (const char *conv_id, enum TIMConvType conv_type)
TIM_API int	TIMConvSetConversationCustomData (const char *conversation_id_array, const char *custom_data, TIMCommCallback cb, const void *user_data)
TIM_API int	TIMConvPinConversation (const char *conv_id, enum TIMConvType conv_type, bool is_pinned, TIMCommCallback cb, const void *user_data)
TIM_API int	TIMConvMarkConversation (const char *conversation_id_array, uint64_t mark_type, bool enable_mark, TIMCommCallback cb, const void *user_data)
TIM_API int	TIMConvGetTotalUnreadMessageCount (TIMCommCallback cb, const void *user_data)
TIM_API int	TIMConvGetUnreadMessageCountByFilter (const char *filter, TIMCommCallback cb, const void *user_data)
TIM_API int	TIMConvSubscribeUnreadMessageCountByFilter (const char *filter)
TIM_API int	TIMConvUnsubscribeUnreadMessageCountByFilter (const char *filter)
TIM_API int	TIMConvCleanConversationUnreadMessageCount (const char *conversation_id, uint64_t clean_timestamp, uint64_t clean_sequence, TIMCommCallback cb, const void *user_data)
TIM_API int	TIMConvCreateConversationGroup (const char *group_name, const char *conversation_id_array, TIMCommCallback cb, const void *user_data)
TIM_API int	TIMConvGetConversationGroupList (TIMCommCallback cb, const void *user_data)
TIM_API int	TIMConvDeleteConversationGroup (const char *group_name, TIMCommCallback cb, const void *user_data)
TIM_API int	TIMConvRenameConversationGroup (const char *old_name, const char *new_name, TIMCommCallback cb, const void *user_data)
TIM_API int	TIMConvAddConversationsToGroup (const char *group_name, const char *conversation_id_array, TIMCommCallback cb, const void *user_data)
TIM_API int	TIMConvDeleteConversationsFromGroup (const char *group_name, const char *conversation_id_array, TIMCommCallback cb, const void *user_data)

类型定义说明

TIMConvEventCallback

typedef void(* TIMConvEventCallback) (enum TIMConvEvent conv_event, const char *json_conv_array, const void *user_data)

1.1 会话事件回调

参数

conv_event	会话事件类型, 请参考 TIMConvEvent
json_conv_array	会话信息列表
user_data	ImSDK负责透传的用户自定义数据，未做任何处理

会话事件回调数据解析示例

void ConvEventCallback(TIMConvEvent conv_event, const char* json_conv_array, const void* user_data) {
    Json::Reader reader;
    Json::Value json_value;
    if (conv_event == kTIMConvEvent_Start) {
        // json_conv_array 为空字符串
    } else if(conv_event == kTIMConvEvent_Finish) {
        // json_conv_array 为空字符串
    }
    if (!reader.parse(json_conv_array, json_value)) {
        // Json 解析失败
        return;
    }
    for (Json::ArrayIndex i = 0; i < json_value.size(); i++) { // 遍历会话类别
        Json::Value& convinfo = json_value[i];
        // 区分会话事件类型
        if (conv_event == kTIMConvEvent_Add) {

        }
        else if (conv_event == kTIMConvEvent_Del) {

        }
    }

json_conv_array 示例 (Json Key 请参考 ConvInfo)

[{
  "conv_active_time": 4611686018427387909,
  "conv_id": "98826",
  "conv_is_has_draft": false,
  "conv_is_has_lastmsg": true,
  "conv_is_pinned": true,
  "conv_last_msg": {
      "message_client_time": 1620877708,
      "message_conv_id": "98826",
      "message_conv_type": 1,
      "message_custom_int": 0,
      "message_custom_str": "",
      "message_elem_array": [{
          "elem_type": 0,
          "text_elem_content": "11111"
      }],
      "message_is_from_self": false,
      "message_is_online_msg": false,
      "message_is_peer_read": false,
      "message_is_read": false,
      "message_msg_id": "144115233874815003-1620877708-1038050731",
      "message_platform": 0,
      "message_priority": 1,
      "message_rand": 1038050731,
      "message_sender": "98826",
      "message_sender_profile": {
          "user_profile_add_permission": 1,
          "user_profile_birthday": 0,
          "user_profile_custom_string_array": [],
          "user_profile_face_url": "test1-www.google.com",
          "user_profile_gender": 0,
          "user_profile_identifier": "98826",
          "user_profile_language": 0,
          "user_profile_level": 0,
          "user_profile_location": "",
          "user_profile_nick_name": "test change8888",
          "user_profile_role": 0,
          "user_profile_self_signature": ""
      },
      "message_seq": 15840,
      "message_server_time": 1620877708,
      "message_status": 2,
      "message_unique_id": 6961616747713488299
  },
  "conv_type": 1,
  "conv_unread_num": 1
}]

TIMConvTotalUnreadMessageCountChangedCallback

typedef void(* TIMConvTotalUnreadMessageCountChangedCallback) (int total_unread_count, const void *user_data)

1.2 会话未读消息总数变化

参数

total_unread_count	未读的消息总数
user_data	ImSDK负责透传的用户自定义数据，未做任何处理

TIMConvTotalUnreadMessageCountChangedByFilterCallback

typedef void(* TIMConvTotalUnreadMessageCountChangedByFilterCallback) (const char *filter, int total_unread_count, const void *user_data)

1.3 按会话 filter 过滤的未读消息总数变化

参数

filter	获取未读总数的 filter, Json Key 请参考 TIMConversationListFilter
total_unread_count	未读的消息总数
user_data	ImSDK负责透传的用户自定义数据，未做任何处理

TIMConvConversationGroupCreatedCallback

typedef void(* TIMConvConversationGroupCreatedCallback) (const char *group_name, const char *conversation_array, const void *user_data)

2.1 会话分组被创建

参数

group_name	分组名
conversation_array	会话列表
user_data	ImSDK负责透传的用户自定义数据，未做任何处理

TIMConvConversationGroupDeletedCallback

typedef void(* TIMConvConversationGroupDeletedCallback) (const char *group_name, const void *user_data)

2.2 会话分组被删除

参数

group_name	分组名
user_data	ImSDK负责透传的用户自定义数据，未做任何处理

TIMConvConversationGroupNameChangedCallback

typedef void(* TIMConvConversationGroupNameChangedCallback) (const char *old_name, const char *new_name, const void *user_data)

2.3 会话分组名变更

参数

old_name	分组名
new_name	分组名
user_data	ImSDK负责透传的用户自定义数据，未做任何处理

TIMConvConversationsAddedToGroupCallback

typedef void(* TIMConvConversationsAddedToGroupCallback) (const char *group_name, const char *conversation_array, const void *user_data)

2.4 会话分组新增会话

参数

group_name	分组名
conversation_array	会话列表
user_data	ImSDK负责透传的用户自定义数据，未做任何处理

TIMConvConversationsDeletedFromGroupCallback

typedef void(* TIMConvConversationsDeletedFromGroupCallback) (const char *group_name, const char *conversation_array, uint32_t reason, const void *user_data)

2.5 会话分组删除会话

参数

group_name	分组名
conversation_array	会话列表
user_data	ImSDK负责透传的用户自定义数据，未做任何处理

注意

• reason 表示会话从所在分组删除的原因，其取值有：
• 当 reason 为 0 时，表示由用户主动调用 deleteConversationsFromGroup 触发
• 当 reason 为 1 时，表示添加到分组的会话数量超过 1000，最早添加进分组的会话被淘汰

函数说明

TIMSetConvEventCallback()

TIM_API void TIMSetConvEventCallback	(	TIMConvEventCallback	cb,
		const void *	user_data
	)

3.1 设置会话事件回调

参数

cb	会话事件回调，请参考 TIMConvEventCallback
user_data	用户自定义数据，ImSDK只负责传回给回调函数cb，不做任何处理

注意

会话事件包括：

• 会话新增
• 会话删除
• 会话更新
• 会话开始
• 会话结束 任何产生一个新会话的操作都会触发会话新增事件，例如调用接口 TIMConvCreate 创建会话，接收到未知会话的第一条消息等。 任何已有会话变化的操作都会触发会话更新事件，例如收到会话新消息，消息撤回，已读上报等。 调用接口 TIMConvDelete 删除会话成功时会触发会话删除事件。

TIMSetConvTotalUnreadMessageCountChangedCallback()

TIM_API void TIMSetConvTotalUnreadMessageCountChangedCallback	(	TIMConvTotalUnreadMessageCountChangedCallback	cb,
		const void *	user_data
	)

3.2 设置全部会话未读消息总数变更的回调

参数

cb	会话未读消息总数变更的回调，请参考 TIMConvTotalUnreadMessageCountChangedCallback
user_data	用户自定义数据，ImSDK只负责传回给回调函数cb，不做任何处理

注意

• 当您调用 TIMConvGetTotalUnreadMessageCount 获取全部会话未读总数以后，任意会话的未读数发生变化时，SDK 都会通过该回调把最新的未读总数通知给您。
• 未读总数会减去设置为免打扰的会话的未读数，即消息接收选项设置为 kTIMRecvMsgOpt_Not_Receive 或 kTIMRecvMsgOpt_Not_Notify 或 kTIMRecvMsgOpt_Not_Notify_Except_At 的会话。

TIMSetConvUnreadMessageCountChangedByFilterCallback()

TIM_API void TIMSetConvUnreadMessageCountChangedByFilterCallback	(	TIMConvTotalUnreadMessageCountChangedByFilterCallback	cb,
		const void *	user_data
	)

3.3 设置按会话 filter 过滤的未读消息总数变更的回调

参数

cb	按会话 filter 过滤的未读消息总数变更的回调，请参考 TIMConvTotalUnreadMessageCountChangedByFilterCallback
user_data	用户自定义数据，ImSDK只负责传回给回调函数cb，不做任何处理

注意

• 您可以调用 TIMConvSubscribeUnreadMessageCountByFilter 注册监听指定 filter 下的未读总数变化，SDK 通过这个回调把最新的未读总数通知给您。
• 您可以注册监听多个不同 filter 下的未读总数变更，这个回调的 filter 参数就是注册监听时指定的 filter，该 filter 携带了 kTIMConversationListFilterConvType、kTIMConversationListFilterMarkType、kTIMConversationListFilterGroupName 三个字段，通过判断这三字段是不是都相同，来区分出不同的 filter。
• 未读总数会减去设置为免打扰的会话的未读数，即消息接收选项设置为 kTIMRecvMsgOpt_Not_Receive 或 kTIMRecvMsgOpt_Not_Notify 或 kTIMRecvMsgOpt_Not_Notify_Except_At 的会话。

TIMSetConvConversationGroupCreatedCallback()

TIM_API void TIMSetConvConversationGroupCreatedCallback	(	TIMConvConversationGroupCreatedCallback	cb,
		const void *	user_data
	)

4.1 设置会话分组被创建回调

参数

cb	会话未读消息总数变更的回调，请参考 TIMConvConversationGroupCreatedCallback
user_data	用户自定义数据，ImSDK只负责传回给回调函数cb，不做任何处理

TIMSetConvConversationGroupDeletedCallback()

TIM_API void TIMSetConvConversationGroupDeletedCallback	(	TIMConvConversationGroupDeletedCallback	cb,
		const void *	user_data
	)

4.2 设置会话分组被删除的回调

参数

cb	会话分组被删除的回调，请参考 TIMConvConversationGroupDeletedCallback
user_data	用户自定义数据，ImSDK只负责传回给回调函数cb，不做任何处理

TIMSetConvConversationGroupNameChangedCallback()

TIM_API void TIMSetConvConversationGroupNameChangedCallback	(	TIMConvConversationGroupNameChangedCallback	cb,
		const void *	user_data
	)

4.3 设置会话分组命名变更回调

参数

cb	会话分组命名变更回调，请参考 TIMConvConversationGroupNameChangedCallback
user_data	用户自定义数据，ImSDK只负责传回给回调函数cb，不做任何处理

TIMSetConvConversationsAddedToGroupCallback()

TIM_API void TIMSetConvConversationsAddedToGroupCallback	(	TIMConvConversationsAddedToGroupCallback	cb,
		const void *	user_data
	)

4.4 设置会话分组新增会话的回调

参数

cb	会话分组新增会话的回调，请参考 TIMConvConversationsAddedToGroupCallback
user_data	用户自定义数据，ImSDK只负责传回给回调函数cb，不做任何处理

TIMSetConvConversationsDeletedFromGroupCallback()

TIM_API void TIMSetConvConversationsDeletedFromGroupCallback	(	TIMConvConversationsDeletedFromGroupCallback	cb,
		const void *	user_data
	)

4.5 设置会话分组删除会话的回调

参数

cb	会话分组删除会话的回调，请参考 TIMConvConversationsDeletedFromGroupCallback
user_data	用户自定义数据，ImSDK只负责传回给回调函数cb，不做任何处理

TIMConvGetConvList()

TIM_API int TIMConvGetConvList	(	TIMCommCallback	cb,
		const void *	user_data
	)

5.1 获取会话列表

参数

cb	获取会话列表的回调。回调函数定义和参数解析请参考 TIMCommCallback
user_data	用户自定义数据，ImSDK只负责传回给回调函数cb，不做任何处理

返回

int 返回TIM_SUCC表示接口调用成功（接口只有返回TIM_SUCC，回调cb才会被调用），其他值表示接口调用失败。每个返回值的定义请参考 TIMResult

TIMConvGetConvInfo()

TIM_API int TIMConvGetConvInfo	(	const char *	json_get_conv_list_param,
		TIMCommCallback	cb,
		const void *	user_data
	)

5.2 查询一组会话列表

参数

json_get_conv_list_param	会话 ID 和会话类型的列表, Json Key 请参考 GetConversationListParam
cb	会话列表的回调。回调函数定义和参数解析请参考 TIMCommCallback
user_data	用户自定义数据，ImSDK只负责传回给回调函数cb，不做任何处理

返回

int 返回TIM_SUCC表示接口调用成功，其他值表示接口调用失败。每个返回值的定义请参考 TIMResult

示例

Json::Object json_obj;
json_obj[kTIMGetConversationListParamConvId] = "98826";
json_obj[kTIMGetConversationListParamConvType] = kTIMConv_C2C;

Json::Array json_array;
json_array.append(json_obj);

TIMConvGetConvInfo(json_array.toStyledString().c_str(),
   [](int32_t code, const char* desc, const char* json_param, const void* user_data) {
   printf("TIMConvGetConvInfo|code:%d|desc:%s\n", code, desc);
}, nullptr);

回调中的 json_param 示例 (Json Key 请参考 ConvInfo)

  [{
    "conv_active_time": 5,
    "conv_id": "98826",
    "conv_is_has_draft": false,
    "conv_is_has_lastmsg": true,
    "conv_is_pinned": false,
    "conv_last_msg": {
        "message_client_time": 1620877708,
        "message_conv_id": "98826",
        "message_conv_type": 1,
        "message_custom_int": 0,
        "message_custom_str": "",
        "message_elem_array": [{
            "elem_type": 0,
            "text_elem_content": "11111"
    }],
        "message_is_from_self": false,
        "message_is_online_msg": false,
        "message_is_peer_read": false,
        "message_is_read": false,
        "message_msg_id": "144115233874815003-1620877708-1038050731",
        "message_platform": 0,
        "message_priority": 1,
        "message_rand": 1038050731,
        "message_sender": "98826",
        "message_sender_profile": {
            "user_profile_add_permission": 1,
            "user_profile_birthday": 0,
            "user_profile_custom_string_array": [],
            "user_profile_face_url": "test1-www.google.com",
            "user_profile_gender": 0,
            "user_profile_identifier": "98826",
            "user_profile_language": 0,
            "user_profile_level": 0,
            "user_profile_location": "",
            "user_profile_nick_name": "test change8888",
            "user_profile_role": 0,
            "user_profile_self_signature": ""
}, *       "message_seq": 15840,
        "message_server_time": 1620877708,
        "message_status": 2,
        "message_unique_id": 6961616747713488299
     },
     "conv_type": 1,
     "conv_unread_num": 1
  }]

TIMConvGetConversationListByFilter()

TIM_API int TIMConvGetConversationListByFilter	(	const char *	filter,
		uint64_t	next_seq,
		uint32_t	count,
		TIMCommCallback	cb,
		const void *	user_data
	)

5.3 获取会话列表高级接口（从 6.5 版本开始支持）

参数

filter	获取会话列表高级接口的 filter, Json Key 请参考 TIMConversationListFilter
next_seq	分页拉取的游标
count	分页拉取的个数
cb	获取会话列表高级接口的回调。回调函数定义和参数解析请参考 TIMCommCallback
user_data	用户自定义数据，ImSDK只负责传回给回调函数cb，不做任何处理

返回

int 返回TIM_SUCC表示接口调用成功（接口只有返回TIM_SUCC，回调cb才会被调用），其他值表示接口调用失败。每个返回值的定义请参考 TIMResult

示例

json::Object filter;
filter[kTIMConversationListFilterConvType] = kTIMConv_Group;
filter[kTIMConversationListFilterMarkType] = kTIMConversationMarkTypeStar;
filter[kTIMConversationListFilterConversationGroup] = "my_group_name";
filter[kTIMConversationListFilterHasUnreadCount] = true;
filter[kTIMConversationListFilterHasGroupAtInfo] = true;

TIMConvGetConversationListByFilter(json::Serialize(filter).c_str(), 0, 20, [](int32_t code, const char* desc, const char* json_param, const void* user_data) {
    printf("TIMConvGetConversationListByFilter code:%d|desc:%s|json_param %s\r\n", code, desc, json_param);

    // 读取 json_param 存放的结果
    json::Value json = json::Deserialize(json_param);
    // json[TIMConversationListResultConvList] 读取到 ConvInfo 列表
    uint64_t next_seq = json[TIMConversationListResultNextSeq].ToUInt64();
    bool is_finished = json[TIMConversationListResultIsFinished].ToBool();
    if (!is_finished) {
        // 继续调用 TIMConvGetConversationListByFilter 获取下一页，filter 参数的字段填写如下所示
        // json::Object filter;
        // filter[kTIMConversationListFilterConvType] = kTIMConv_Group;
        // filter[kTIMConversationListFilterMarkType] = kTIMConversationMarkTypeStar;
        // filter[kTIMConversationListFilterConversationGroup] = "my_group_name";
        // filter[kTIMConversationListFilterHasUnreadCount] = true;
        // filter[kTIMConversationListFilterHasGroupAtInfo] = true;
    }
}, nullptr);

TIMConvDelete()

TIM_API int TIMConvDelete	(	const char *	conv_id,
		enum TIMConvType	conv_type,
		TIMCommCallback	cb,
		const void *	user_data
	)

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

参数

conv_id	会话的ID
conv_type	会话类型，请参考 TIMConvType
cb	删除会话成功与否的回调。回调函数定义请参考 TIMCommCallback
user_data	用户自定义数据，ImSDK只负责传回给回调函数cb，不做任何处理

返回

int 返回TIM_SUCC表示接口调用成功（接口只有返回TIM_SUCC，回调cb才会被调用），其他值表示接口调用失败。每个返回值的定义请参考 TIMResult

注意

此接口用于删除会话（该会话以及会话中的历史消息，会被 SDK 从本地和服务端一同删除掉，并且不可恢复），删除会话是否成功的结果会通过会话事件回调返回。

TIMConvDeleteConversationList()

TIM_API int TIMConvDeleteConversationList	(	const char *	conversation_id_array,
		bool	clear_message,
		TIMCommCallback	cb,
		const void *	user_data
	)

5.5 删除会话列表（从 7.1 版本开始支持）

参数

conversation_id_array	会话 ID 列表
clear_message	是否删除会话中的消息；设置为 false 时，保留会话消息；设置为 true 时，本地和服务器的消息会一起删除，并且不可恢复
cb	删除会话列表的回调。回调函数定义和参数解析请参考 TIMCommCallback
user_data	用户自定义数据，ImSDK 只负责传回给回调函数 cb，不做任何处理

返回

int 返回 TIM_SUCC 表示接口调用成功（接口只有返回 TIM_SUCC，回调 cb 才会被调用），其他值表示接口调用失败。每个返回值的定义请参考 TIMResult

注意

每次最多支持删除 100 个会话

示例(回调结果中 json_param 使用的 Json Key 请参考 TIMConversationOperationResult)

json::Array conversation_id_array;
conversation_id_array.push_back("c2c_conversation_id1");
conversation_id_array.push_back("group_conversation_id2");

bool clear_message = true;

TIMConvDeleteConversationList(json::Serialize(conversation_id_array).c_str(), clear_message, [](int32_t code, const char* desc, const char* json_param, const void* user_data) {
    printf("TIMConvDeleteConversationList code:%d|desc:%s|json_param %s\r\n", code, desc, json_param);

    // 遍历读取 json_param 存放的操作结果，参见 TIMConversationOperationResult 的定义
}, nullptr);

TIMConvSetDraft()

TIM_API int TIMConvSetDraft	(	const char *	conv_id,
		enum TIMConvType	conv_type,
		const char *	json_draft_param
	)

5.6 设置指定会话的草稿

参数

conv_id	会话的ID
conv_type	会话类型，请参考 TIMConvType
json_draft_param	被设置的草稿 Json 字符串, Json Key 请参考 Draft

返回

int 返回TIM_SUCC表示接口调用成功，其他值表示接口调用失败。每个返回值的定义请参考 TIMResult

注意

会话草稿一般用在保存用户当前输入的未发送的消息

示例

Json::Value json_value_text;  // 构造消息
json_value_text[kTIMElemType] = kTIMElem_Text;
json_value_text[kTIMTextElemContent] = "this draft";
Json::Value json_value_msg;
json_value_msg[kTIMMsgElemArray].append(json_value_text);

Json::Value json_value_draft; // 构造草稿
json_value_draft[kTIMDraftEditTime] = time(NULL);
json_value_draft[kTIMDraftUserDefine] = "this is userdefine";
json_value_draft[kTIMDraftMsg] = json_value_msg;

if (TIM_SUCC != TIMConvSetDraft(userid.c_str(), TIMConvType::kTIMConv_C2C, json_value_draft.toStyledString().c_str())) {
    // TIMConvSetDraft 接口调用失败
}

// json_value_draft.toStyledString().c_str() 得到 json_draft_param JSON 字符串如下
{
   "draft_edit_time" : 1551271429,
   "draft_msg" : {
      "message_elem_array" : [
         {
            "elem_type" : 0,
            "text_elem_content" : "this draft"
         }
      ]
   },
   "draft_user_define" : "this is userdefine"
}

TIMConvCancelDraft()

TIM_API int TIMConvCancelDraft	(	const char *	conv_id,
		enum TIMConvType	conv_type
	)

5.7 删除指定会话的草稿

参数

conv_id	会话的ID
conv_type	会话类型，请参考 TIMConvType

返回

int 返回TIM_SUCC表示接口调用成功，其他值表示接口调用失败。每个返回值的定义请参考 TIMResult

TIMConvSetConversationCustomData()

TIM_API int TIMConvSetConversationCustomData	(	const char *	conversation_id_array,
		const char *	custom_data,
		TIMCommCallback	cb,
		const void *	user_data
	)

5.8 设置会话自定义数据（从 6.5 版本开始支持）

参数

conversation_id_array	会话 ID 列表
custom_data	自定义数据，最大支持 256 bytes
cb	设置会话自定义字段的回调。回调函数定义和参数解析请参考 TIMCommCallback
user_data	用户自定义数据，ImSDK只负责传回给回调函数cb，不做任何处理

返回

int 返回TIM_SUCC表示接口调用成功（接口只有返回TIM_SUCC，回调cb才会被调用），其他值表示接口调用失败。每个返回值的定义请参考 TIMResult

示例(回调结果中 json_param 使用的 Json Key 请参考 TIMConversationOperationResult)

json::Array conversation_id_array;
conversation_id_array.push_back("c2c_conversation_id1");
conversation_id_array.push_back("group_conversation_id2");

std::string custom_data = "my_custom_data";

TIMConvSetConversationCustomData(json::Serialize(conversation_id_array).c_str(), custom_data.c_str(), [](int32_t code, const char* desc, const char* json_param, const void* user_data) {
    printf("TIMConvSetConversationCustomData code:%d|desc:%s|json_param %s\r\n", code, desc, json_param);

    // 遍历读取 json_param 存放的操作结果，参见 TIMConversationOperationResult 的定义
}, nullptr);

TIMConvPinConversation()

TIM_API int TIMConvPinConversation	(	const char *	conv_id,
		enum TIMConvType	conv_type,
		bool	is_pinned,
		TIMCommCallback	cb,
		const void *	user_data
	)

5.9 设置会话置顶

参数

conv_id	会话 ID
conv_type	会话类型，请参考 TIMConvType
is_pinned	是否置顶会话
cb	设置会话置顶回调。回调函数定义和参数解析请参考 TIMCommCallback
user_data	用户自定义数据，ImSDK只负责传回给回调函数cb，不做任何处理

返回

int 返回 TIM_SUCC 表示接口调用成功（接口只有返回 TIM_SUCC，回调 cb 才会被调用）。每个返回值的定义请参考 TIMResult

示例

// json_param 返回值为空字符串， 直接判断 code 即可
TIMConvPinConversation(conv_id, conv_type, true,
     [](int32_t code, const char* desc, const char* json_param, const void* user_data) {
     printf("TIMConvPinConversation|code:%d|desc:%s\n", code, desc);
}, nullptr);

TIMConvMarkConversation()

TIM_API int TIMConvMarkConversation	(	const char *	conversation_id_array,
		uint64_t	mark_type,
		bool	enable_mark,
		TIMCommCallback	cb,
		const void *	user_data
	)

5.10 标记会话（从 6.5 版本开始支持，需要您购买旗舰版套餐）

参数

conversation_id_array	会话 ID 列表
mark_type	会话标记类型，取值详见 TIMConversationMarkType
enable_mark	true：设置标记 false：取消标记
cb	标记会话的回调。回调函数定义和参数解析请参考 TIMCommCallback
user_data	用户自定义数据，ImSDK只负责传回给回调函数cb，不做任何处理

返回

int 返回 TIM_SUCC 表示接口调用成功（接口只有返回 TIM_SUCC，回调 cb 才会被调用）。每个返回值的定义请参考 TIMResult

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

注意

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

示例(回调结果中 json_param 使用的 Json Key 请参考 TIMConversationOperationResult)

json::Array conversation_id_array;
conversation_id_array.push_back("c2c_conversation_id1");
conversation_id_array.push_back("group_conversation_id2");

uint64_t mark_type = (uint64_t)kTIMConversationMarkTypeUnread | (0x1LL << 32);
bool enable_mark = true;

TIMConvMarkConversation(json::Serialize(conversation_id_array).c_str(), mark_type, enable_mark, [](int32_t code, const char* desc, const char* json_param, const void* user_data) {
    printf("TIMConvMarkConversation code:%d|desc:%s|json_param %s\r\n", code, desc, json_param);

    // 遍历读取 json_param 存放的操作结果，参见 TIMConversationOperationResult 的定义
}, nullptr);

TIMConvGetTotalUnreadMessageCount()

TIM_API int TIMConvGetTotalUnreadMessageCount	(	TIMCommCallback	cb,
		const void *	user_data
	)

5.11 获取所有会话总的未读消息数

参数

cb	获取所有会话总的未读消息数回调。回调函数定义和参数解析请参考 TIMCommCallback
user_data	用户自定义数据，ImSDK只负责传回给回调函数cb，不做任何处理

返回

int 返回 TIM_SUCC 表示接口调用成功（接口只有返回 TIM_SUCC，回调 cb 才会被调用）。每个返回值的定义请参考 TIMResult

注意

• 调用该接口以后，任意会话的未读数发生变化时，SDK 都会给您抛 TIMSetConvTotalUnreadMessageCountChangedCallback 回调。
• 未读总数会减去设置为免打扰的会话的未读数，即消息接收选项设置为 kTIMRecvMsgOpt_Not_Receive 或 kTIMRecvMsgOpt_Not_Notify 或 kTIMRecvMsgOpt_Not_Notify_Except_At 的会话。

示例 (回调结果中 json_param 使用的 Json Key 请参考 GetTotalUnreadNumberResult)

TIMConvGetTotalUnreadMessageCount(
     [](int32_t code, const char* desc, const char* json_param, const void* user_data) {
     // json key 请参考 GetTotalUnreadNumberResult
     printf("TIMConvGetTotalUnreadMessageCount|code:%d|desc:%s|json_param:%s\n", code, desc, json_param);
}, nullptr);

TIMConvGetUnreadMessageCountByFilter()

TIM_API int TIMConvGetUnreadMessageCountByFilter	(	const char *	filter,
		TIMCommCallback	cb,
		const void *	user_data
	)

5.12 根据 filter 获取未读总数（7.0 及以上版本支持）

参数

filter	会话 filter, Json Key 请参考 TIMConversationListFilter
cb	获取未读总数的回调。回调函数定义和参数解析请参考 TIMCommCallback
user_data	用户自定义数据，ImSDK只负责传回给回调函数cb，不做任何处理

返回

int 返回TIM_SUCC表示接口调用成功（接口只有返回TIM_SUCC，回调cb才会被调用），其他值表示接口调用失败。每个返回值的定义请参考 TIMResult

注意

• 未读总数会减去设置为免打扰的会话的未读数，即消息接收选项设置为 kTIMRecvMsgOpt_Not_Receive 或 kTIMRecvMsgOpt_Not_Notify 或 kTIMRecvMsgOpt_Not_Notify_Except_At 的会话。

示例 (回调结果中 json_param 使用的 Json Key 请参考 GetTotalUnreadNumberResult)

json::Object filter;
filter[kTIMConversationListFilterConvType] = kTIMConv_Group;
filter[kTIMConversationListFilterConversationGroup] = "my_group_name";
filter[kTIMConversationListFilterMarkType] = kTIMConversationMarkTypeStar;
filter[kTIMConversationListFilterHasUnreadCount] = true;
filter[kTIMConversationListFilterHasGroupAtInfo] = true;

TIMConvGetUnreadMessageCountByFilter(json::Serialize(filter).c_str(), [](int32_t code, const char* desc, const char* json_param, const void* user_data) {
    // json key 请参考 GetTotalUnreadNumberResult
    printf("TIMConvGetTotalUnreadMessageCount|code:%d|desc:%s|json_param:%s\n", code, desc, json_param);
}, nullptr);

TIMConvSubscribeUnreadMessageCountByFilter()

TIM_API int TIMConvSubscribeUnreadMessageCountByFilter

(

const char *

filter

)

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

参数

filter

会话 filter, Json Key 请参考 TIMConversationListFilter

返回

int 返回TIM_SUCC表示接口调用成功（接口只有返回TIM_SUCC，回调cb才会被调用），其他值表示接口调用失败。每个返回值的定义请参考 TIMResult

注意

• 当您调用这个接口以后，该 filter 下的未读数发生变化时，SDK 会给您抛 TIMSetConvUnreadMessageCountChangedByFilterCallback 注册的回调。

示例

json::Object filter;
filter[kTIMConversationListFilterConvType] = kTIMConv_Group;
filter[kTIMConversationListFilterConversationGroup] = "my_group_name";
filter[kTIMConversationListFilterMarkType] = kTIMConversationMarkTypeStar;
filter[kTIMConversationListFilterHasUnreadCount] = true;
filter[kTIMConversationListFilterHasGroupAtInfo] = true;

TIMConvSubscribeUnreadMessageCountByFilter(json::Serialize(filter).c_str());

TIMConvUnsubscribeUnreadMessageCountByFilter()

TIM_API int TIMConvUnsubscribeUnreadMessageCountByFilter

(

const char *

filter

)

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

参数

filter

会话 filter, Json Key 请参考 TIMConversationListFilter

返回

int 返回TIM_SUCC表示接口调用成功（接口只有返回TIM_SUCC，回调cb才会被调用），其他值表示接口调用失败。每个返回值的定义请参考 TIMResult

示例

json::Object filter;
filter[kTIMConversationListFilterConvType] = kTIMConv_Group;
filter[kTIMConversationListFilterConversationGroup] = "my_group_name";
filter[kTIMConversationListFilterMarkType] = kTIMConversationMarkTypeStar;
filter[kTIMConversationListFilterHasUnreadCount] = true;
filter[kTIMConversationListFilterHasGroupAtInfo] = true;

TIMConvUnsubscribeUnreadMessageCountByFilter(json::Serialize(filter).c_str());

TIMConvCleanConversationUnreadMessageCount()

TIM_API int TIMConvCleanConversationUnreadMessageCount	(	const char *	conversation_id,
		uint64_t	clean_timestamp,
		uint64_t	clean_sequence,
		TIMCommCallback	cb,
		const void *	user_data
	)

5.15 清理会话的未读消息计数（7.1 及以上版本支持）

参数

conversation_id	会话唯一 ID， C2C 单聊组成方式："c2c_" + userID；群聊组成方式为 "group_" + groupID
clean_timestamp	清理时间戳，单位为秒，仅对单聊会话生效，指定清理哪一个 timestamp 之前的未读消息计数；当传入为 0 时，对应会话所有的未读消息将被清理，会话的未读数会清 0；
clean_sequence	清理时 sequence，仅对群聊会话生效，指定清理哪一个 sequence 之前的未读消息计数；当传入为 0 时，对应会话所有的未读消息将被清理，会话的未读数会清 0；
cb	创建会话分组的回调。回调函数定义和参数解析请参考 TIMCommCallback
user_data	用户自定义数据，ImSDK只负责传回给回调函数cb，不做任何处理

注意

• 当您想清理所有单聊会话的未读消息计数，conversation_id 请传入 "c2c"，即不指定具体的 userID；
• 当您想清理所有群聊会话的未读消息计数，conversation_id 请传入 "group"，即不指定具体的 groupID；
• 当您想清理所有会话的未读消息计数，conversation_id 请传入 "" 或者 nullptr；
• 该接口调用成功后，SDK 会通过 TIMSetConvEventCallback 回调 ( TIMConvEvent 为 kTIMConvEvent_Update）将对应会话的最新未读数通知给您。

示例

TIMConvCleanConversationUnreadMessageCount("c2c_user1", 123456, 0, [](int32_t code, const char* desc, const char* json_param, const void* user_data) {
    printf("TIMConvCleanConversationUnreadMessageCount code:%d|desc:%s\n", code, desc);

}, nullptr);

TIMConvCreateConversationGroup()

TIM_API int TIMConvCreateConversationGroup	(	const char *	group_name,
		const char *	conversation_id_array,
		TIMCommCallback	cb,
		const void *	user_data
	)

6.1 创建会话分组（从 6.5 版本开始支持，需要您购买旗舰版套餐）

参数

group_name	分组名（必填参数，长度要 > 0，最大支持 32 bytes）
conversation_id_array	会话 ID 列表（必填参数，不能为空）
cb	创建会话分组的回调。回调函数定义和参数解析请参考 TIMCommCallback
user_data	用户自定义数据，ImSDK只负责传回给回调函数cb，不做任何处理

返回

int 返回 TIM_SUCC 表示接口调用成功（接口只有返回 TIM_SUCC，回调 cb 才会被调用）。每个返回值的定义请参考 TIMResult

注意

会话分组最大支持 20 个，不再使用的分组请及时删除。

示例

std::string group_name = "my_group_name";

json::Array conversation_id_array;
conversation_id_array.push_back("c2c_conversation_id1");
conversation_id_array.push_back("group_conversation_id2");

TIMConvCreateConversationGroup(group_name.c_str(), json::Serialize(conversation_id_array).c_str(), [](int32_t code, const char* desc, const char* json_param, const void* user_data) {
    printf("TIMConvCreateConversationGroup code:%d|desc:%s|json_param %s\r\n", code, desc, json_param);

    // 遍历读取 json_param 存放的操作结果，参见 TIMConversationOperationResult 的定义
}, nullptr);

TIMConvGetConversationGroupList()

TIM_API int TIMConvGetConversationGroupList	(	TIMCommCallback	cb,
		const void *	user_data
	)

6.2 获取会话分组列表（从 6.5 版本开始支持，需要您购买旗舰版套餐）

参数

cb	获取会话分组列表的回调。回调函数定义和参数解析请参考 TIMCommCallback
user_data	用户自定义数据，ImSDK只负责传回给回调函数cb，不做任何处理

返回

int 返回 TIM_SUCC 表示接口调用成功（接口只有返回 TIM_SUCC，回调 cb 才会被调用）。每个返回值的定义请参考 TIMResult

注意

该接口获取的是本地缓存的会话分组，建议在 kTIMConvEvent_Finish 之后调用。

示例

TIMConvGetConversationGroupList([](int32_t code, const char* desc, const char* json_param, const void* user_data) {
    printf("TIMConvGetConversationGroupList code:%d|desc:%s|json_param %s\r\n", code, desc, json_param);

    // 读取 json_param 存放的会话分组列表，例如：
    // [
    //      "my_group_name1",
    //      "my_group_name2",
    //      "my_group_name3"
    // ]
}, nullptr);

TIMConvDeleteConversationGroup()

TIM_API int TIMConvDeleteConversationGroup	(	const char *	group_name,
		TIMCommCallback	cb,
		const void *	user_data
	)

6.3 删除会话分组（从 6.5 版本开始支持，需要您购买旗舰版套餐）

参数

group_name	分组名（必填参数，长度要 > 0，最大支持 32 bytes）
cb	删除会话分组的回调。回调函数定义和参数解析请参考 TIMCommCallback
user_data	用户自定义数据，ImSDK只负责传回给回调函数cb，不做任何处理

返回

int 返回 TIM_SUCC 表示接口调用成功（接口只有返回 TIM_SUCC，回调 cb 才会被调用）。每个返回值的定义请参考 TIMResult

示例

std::string group_name = "my_group_name";

TIMConvDeleteConversationGroup(group_name.c_str(), [](int32_t code, const char* desc, const char* json_param, const void* user_data) {
    printf("TIMConvDeleteConversationGroup code:%d|desc:%s|json_param %s\r\n", code, desc, json_param);
}, nullptr);

TIMConvRenameConversationGroup()

TIM_API int TIMConvRenameConversationGroup	(	const char *	old_name,
		const char *	new_name,
		TIMCommCallback	cb,
		const void *	user_data
	)

6.4 重命名会话分组（从 6.5 版本开始支持，需要您购买旗舰版套餐）

参数

old_name	分组名（必填参数，长度要 > 0，最大支持 32 bytes）
new_name	分组名（必填参数，长度要 > 0，最大支持 32 bytes）
cb	重命名会话分组的回调。回调函数定义和参数解析请参考 TIMCommCallback
user_data	用户自定义数据，ImSDK只负责传回给回调函数cb，不做任何处理

返回

int 返回 TIM_SUCC 表示接口调用成功（接口只有返回 TIM_SUCC，回调 cb 才会被调用）。每个返回值的定义请参考 TIMResult

示例

std::string old_name = "old_name";
std::string new_name = "new_name";

TIMConvRenameConversationGroup(old_name.c_str(), new_name.c_str(), [](int32_t code, const char* desc, const char* json_param, const void* user_data) {
    printf("TIMConvRenameConversationGroup code:%d|desc:%s|json_param %s\r\n", code, desc, json_param);
}, nullptr);

TIMConvAddConversationsToGroup()

TIM_API int TIMConvAddConversationsToGroup	(	const char *	group_name,
		const char *	conversation_id_array,
		TIMCommCallback	cb,
		const void *	user_data
	)

6.5 添加会话到一个会话分组（从 6.5 版本开始支持，需要您购买旗舰版套餐）

参数

group_name	分组名（必填参数，长度要 > 0，最大支持 32 bytes）
conversation_id_array	会话 ID 列表（必填参数，不能为空）
cb	添加会话到一个会话分组的回调。回调函数定义和参数解析请参考 TIMCommCallback
user_data	用户自定义数据，ImSDK只负责传回给回调函数cb，不做任何处理

返回

int 返回 TIM_SUCC 表示接口调用成功（接口只有返回 TIM_SUCC，回调 cb 才会被调用）。每个返回值的定义请参考 TIMResult

示例 (回调结果中 json_param 使用的 Json Key 请参考 TIMConversationOperationResult)

std::string group_name = "my_group_name";

json::Array conversation_id_array;
conversation_id_array.push_back("c2c_conversation_id1");
conversation_id_array.push_back("group_conversation_id2");

TIMConvAddConversationsToGroup(group_name.c_str(), json::Serialize(conversation_id_array).c_str(), [](int32_t code, const char* desc, const char* json_param, const void* user_data) {
    printf("TIMConvAddConversationsToGroup code:%d|desc:%s|json_param %s\r\n", code, desc, json_param);

    // 遍历读取 json_param 存放的操作结果，参见 TIMConversationOperationResult 的定义
}, nullptr);

TIMConvDeleteConversationsFromGroup()

TIM_API int TIMConvDeleteConversationsFromGroup	(	const char *	group_name,
		const char *	conversation_id_array,
		TIMCommCallback	cb,
		const void *	user_data
	)

6.6 从会话分组中删除多个会话（从 6.5 版本开始支持，需要您购买旗舰版套餐）

参数

group_name	分组名（必填参数，长度要 > 0，最大支持 32 bytes）
conversation_id_array	会话 ID 列表（必填参数，不能为空）
cb	从会话分组中删除多个会话的回调。回调函数定义和参数解析请参考 TIMCommCallback
user_data	用户自定义数据，ImSDK只负责传回给回调函数cb，不做任何处理

返回

int 返回 TIM_SUCC 表示接口调用成功（接口只有返回 TIM_SUCC，回调 cb 才会被调用）。每个返回值的定义请参考 TIMResult

示例 (回调结果中 json_param 使用的 Json Key 请参考 TIMConversationOperationResult)

std::string group_name = "my_group_name";

json::Array conversation_id_array;
conversation_id_array.push_back("c2c_conversation_id1");
conversation_id_array.push_back("group_conversation_id2");

TIMConvDeleteConversationsFromGroup(group_name.c_str(), json::Serialize(conversation_id_array).c_str(), [](int32_t code, const char* desc, const char* json_param, const void* user_data) {
    printf("TIMConvDeleteConversationsFromGroup code:%d|desc:%s|json_param %s\r\n", code, desc, json_param);

    // 遍历读取 json_param 存放的操作结果，参见 TIMConversationOperationResult 的定义
}, nullptr);