TIMMessageManagerFunction.h 文件参考

类型定义
typedef void(*	TIMRecvNewMsgCallback) (const char *json_msg_array, const void *user_data)
typedef void(*	TIMMsgElemUploadProgressCallback) (const char *json_msg, uint32_t index, uint32_t cur_size, uint32_t total_size, const void *user_data)
typedef void(*	TIMMsgGroupMessageReadMemberListCallback) (const char *json_group_member_array, uint64_t next_seq, bool is_finished, const void *user_data)
typedef void(*	TIMMsgReadedReceiptCallback) (const char *json_msg_read_receipt_array, const void *user_data)
typedef void(*	TIMMsgRevokeCallback) (const char *json_msg_revoke_info_array, const void *user_data)
typedef void(*	TIMMsgUpdateCallback) (const char *json_msg_array, const void *user_data)
typedef void(*	TIMMsgExtensionsChangedCallback) (const char *message_id, const char *message_extension_array, const void *user_data)
typedef void(*	TIMMsgExtensionsDeletedCallback) (const char *message_id, const char *message_extension_key_array, const void *user_data)
typedef void(*	TIMMsgReactionsChangedCallback) (const char *message_reaction_change_info_array, const void *user_data)
typedef void(*	TIMMsgAllMessageReceiveOptionCallback) (const char *json_receive_message_option_info, const void *user_data)
typedef void(*	TIMMsgGroupPinnedMessageChangedCallback) (const char *group_id, const char *json_msg, bool is_pinned, const char *op_user, const void *user_data)

函数
TIM_API void	TIMAddRecvNewMsgCallback (TIMRecvNewMsgCallback cb, const void *user_data)
TIM_API void	TIMRemoveRecvNewMsgCallback (TIMRecvNewMsgCallback cb)
TIM_API void	TIMSetMsgElemUploadProgressCallback (TIMMsgElemUploadProgressCallback cb, const void *user_data)
TIM_API void	TIMSetMsgReadedReceiptCallback (TIMMsgReadedReceiptCallback cb, const void *user_data)
TIM_API void	TIMSetMsgRevokeCallback (TIMMsgRevokeCallback cb, const void *user_data)
TIM_API void	TIMSetMsgUpdateCallback (TIMMsgUpdateCallback cb, const void *user_data)
TIM_API void	TIMSetMsgExtensionsChangedCallback (TIMMsgExtensionsChangedCallback cb, const void *user_data)
TIM_API void	TIMSetMsgExtensionsDeletedCallback (TIMMsgExtensionsDeletedCallback cb, const void *user_data)
TIM_API void	TIMSetMsgReactionsChangedCallback (TIMMsgReactionsChangedCallback cb, const void *user_data)
TIM_API void	TIMSetMsgAllMessageReceiveOptionCallback (TIMMsgAllMessageReceiveOptionCallback cb, const void *user_data)
TIM_API void	TIMSetMsgGroupPinnedMessageChangedCallback (TIMMsgGroupPinnedMessageChangedCallback cb, const void *user_data)
TIM_API int	TIMMsgSendMessage (const char *conv_id, enum TIMConvType conv_type, const char *json_msg_param, char *message_id_buffer, TIMCommCallback cb, const void *user_data)
TIM_API int	TIMMsgCancelSend (const char *conv_id, enum TIMConvType conv_type, const char *message_id, TIMCommCallback cb, const void *user_data)
TIM_API int	TIMMsgBatchSend (const char *json_batch_send_param, TIMCommCallback cb, const void *user_data)
TIM_API int	TIMMsgDownloadElemToPath (const char *json_download_elem_param, const char *path, TIMCommCallback cb, const void *user_data)
TIM_API int	TIMMsgDownloadMergerMessage (const char *json_single_msg, TIMCommCallback cb, const void *user_data)
TIM_API int	TIMMsgSetLocalCustomData (const char *json_msg_param, TIMCommCallback cb, const void *user_data)
TIM_API int	TIMMsgSetC2CReceiveMessageOpt (const char *json_identifier_array, TIMReceiveMessageOpt opt, TIMCommCallback cb, const void *user_data)
TIM_API int	TIMMsgGetC2CReceiveMessageOpt (const char *json_identifier_array, TIMCommCallback cb, const void *user_data)
TIM_API int	TIMMsgSetGroupReceiveMessageOpt (const char *group_id, TIMReceiveMessageOpt opt, TIMCommCallback cb, const void *user_data)
TIM_API int	TIMMsgSetAllReceiveMessageOpt (TIMReceiveMessageOpt opt, int32_t start_hour, int32_t start_minute, int32_t start_second, uint32_t duration, TIMCommCallback cb, const void *user_data)
TIM_API int	TIMMsgSetAllReceiveMessageOpt2 (TIMReceiveMessageOpt opt, uint32_t start_time_stamp, uint32_t duration, TIMCommCallback cb, const void *user_data)
TIM_API int	TIMMsgGetAllReceiveMessageOpt (TIMCommCallback cb, const void *user_data)
TIM_API int	TIMMsgGetMsgList (const char *conv_id, enum TIMConvType conv_type, const char *json_get_msg_param, TIMCommCallback cb, const void *user_data)
TIM_API int	TIMMsgRevoke (const char *conv_id, enum TIMConvType conv_type, const char *json_msg_param, TIMCommCallback cb, const void *user_data)
TIM_API int	TIMMsgModifyMessage (const char *json_msg_param, TIMCommCallback cb, const void *user_data)
TIM_API int	TIMMsgDelete (const char *conv_id, enum TIMConvType conv_type, const char *json_msgdel_param, TIMCommCallback cb, const void *user_data)
TIM_API int	TIMMsgListDelete (const char *conv_id, enum TIMConvType conv_type, const char *json_msg_array, TIMCommCallback cb, const void *user_data)
TIM_API int	TIMMsgClearHistoryMessage (const char *conv_id, enum TIMConvType conv_type, TIMCommCallback cb, const void *user_data)
TIM_API int	TIMMsgSaveMsg (const char *conv_id, enum TIMConvType conv_type, const char *json_msg_param, TIMCommCallback cb, const void *user_data)
TIM_API int	TIMMsgImportMsgList (const char *conv_id, enum TIMConvType conv_type, const char *json_msg_array, TIMCommCallback cb, const void *user_data)
TIM_API int	TIMMsgFindMessages (const char *json_message_id_array, TIMCommCallback cb, const void *user_data)
TIM_API int	TIMMsgFindByMsgLocatorList (const char *conv_id, enum TIMConvType conv_type, const char *json_msg_Locator_array, TIMCommCallback cb, const void *user_data)
TIM_API int	TIMMsgSearchLocalMessages (const char *json_search_message_param, TIMCommCallback cb, const void *user_data)
TIM_API int	TIMMsgSearchCloudMessages (const char *json_search_message_param, TIMCommCallback cb, const void *user_data)
TIM_API int	TIMMsgSendMessageReadReceipts (const char *json_msg_array, TIMCommCallback cb, const void *user_data)
TIM_API int	TIMMsgGetMessageReadReceipts (const char *json_msg_array, TIMCommCallback cb, const void *user_data)
TIM_API int	TIMMsgGetGroupMessageReadMemberList (const char *json_msg, TIMGroupMessageReadMembersFilter filter, uint64_t next_seq, uint32_t count, TIMMsgGroupMessageReadMemberListCallback cb, const void *user_data)
TIM_API int	TIMMsgSetMessageExtensions (const char *json_msg, const char *json_extension_array, TIMCommCallback cb, const void *user_data)
TIM_API int	TIMMsgGetMessageExtensions (const char *json_msg, TIMCommCallback cb, const void *user_data)
TIM_API int	TIMMsgDeleteMessageExtensions (const char *json_msg, const char *json_extension_key_array, TIMCommCallback cb, const void *user_data)
TIM_API int	TIMMsgAddMessageReaction (const char *json_msg, const char *reaction_id, TIMCommCallback cb, const void *user_data)
TIM_API int	TIMMsgRemoveMessageReaction (const char *json_msg, const char *reaction_id, TIMCommCallback cb, const void *user_data)
TIM_API int	TIMMsgGetMessageReactions (const char *json_msg_array, uint32_t max_user_count_per_reaction, TIMCommCallback cb, const void *user_data)
TIM_API int	TIMMsgGetAllUserListOfMessageReaction (const char *json_msg, const char *reaction_id, uint32_t next_seq, uint32_t count, TIMCommCallback cb, const void *user_data)
TIM_API int	TIMMsgTranslateText (const char *json_source_text_array, const char *source_language, const char *target_language, TIMCommCallback cb, const void *user_data)
TIM_API int	TIMMsgConvertVoiceToText (const char *url, const char *language, TIMCommCallback cb, const void *user_data)
TIM_API int	TIMPinGroupMessage (const char *group_id, const char *json_msg, bool is_pinned, TIMCommCallback cb, const void *user_data)
TIM_API int	TIMGetPinnedGroupMessageList (const char *group_id, TIMCommCallback cb, const void *user_data)

类型定义说明

TIMRecvNewMsgCallback

typedef void(* TIMRecvNewMsgCallback) (const char *json_msg_array, const void *user_data)

1.1 新消息回调

参数

json_msg_array	新消息数组, Json Key 请参考 Message
user_data	ImSDK负责透传的用户自定义数据，未做任何处理

注意

此回调可以获取新接收的消息数组。注意：消息内的元素也是一个数组。数组中每个元素的定义由 elem_type 字段决定

消息数组解析示例

Json::Value json_value_msgs; // 解析消息
Json::Reader reader;
if (!reader.parse(json_msg_array, json_value_msgs)) {
    printf("reader parse failure!%s", reader.getFormattedErrorMessages().c_str());
    return;
}
for (Json::ArrayIndex i = 0; i < json_value_msgs.size(); i++) {  // 遍历Message
    Json::Value& json_value_msg = json_value_msgs[i];
    Json::Value& elems = json_value_msg[kTIMMsgElemArray];
    for (Json::ArrayIndex m = 0; m < elems.size(); m++) {   // 遍历Elem
        Json::Value& elem = elems[i];

        uint32_t elem_type = elem[kTIMElemType].asUInt();
        if (elem_type == TIMElemType::kTIMElem_Text) {  // 文本

        } else if (elem_type == TIMElemType::kTIMElem_Sound) {  // 声音

        } else if (elem_type == TIMElemType::kTIMElem_File) {  // 文件

        } else if (elem_type == TIMElemType::kTIMElem_Image) { // 图片

        } else if (elem_type == TIMElemType::kTIMElem_Custom) { // 自定义元素

        } else if (elem_type == TIMElemType::kTIMElem_GroupTips) { // 群组系统消息

        } else if (elem_type == TIMElemType::kTIMElem_Face) { // 表情

        } else if (elem_type == TIMElemType::kTIMElem_Location) { // 位置

        } else if (elem_type == TIMElemType::kTIMElem_GroupReport) { // 群组系统通知

        } else if (elem_type == TIMElemType::kTIMElem_Video) { // 视频

        }
    }
}

返回一个文本消息的Json示例 (Json Key 请参考 Message、 TextElem)

[
   {
      "message_client_time" : 1551080111,
      "message_conv_id" : "user2",
      "message_conv_type" : 1,
      "message_elem_array" : [
         {
            "elem_type" : 0,
            "text_elem_content" : "123213213"
         }
      ],
      "message_is_from_self" : true,
      "message_is_read" : true,
      "message_rand" : 2130485001,
      "message_sender" : "user1",
      "message_seq" : 1,
      "message_server_time" : 1551080111,
      "message_status" : 2
   }
]

返回一个群通知消息的Json示例 (Json Key 请参考 Message、 GroupReportElem)

[
   {
      "message_client_time" : 1551344977,
      "message_conv_id" : "",
      "message_conv_type" : 3,
      "message_elem_array" : [
         {
            "elem_type" : 9,
            "group_report_elem_group_id" : "first group id",
            "group_report_elem_group_name" : "first group name",
            "group_report_elem_msg" : "",
            "group_report_elem_op_group_memberinfo" : {
               "group_member_info_custom_info" : {},
               "group_member_info_identifier" : "user1",
               "group_member_info_join_time" : 0,
               "group_member_info_member_role" : 0,
               "group_member_info_msg_flag" : 0,
               "group_member_info_msg_seq" : 0,
               "group_member_info_name_card" : "",
               "group_member_info_shutup_time" : 0
            },
            "group_report_elem_op_user" : "",
            "group_report_elem_platform" : "Windows",
            "group_report_elem_report_type" : 6,
            "group_report_elem_user_data" : ""
         }
      ],
      "message_is_from_self" : false,
      "message_is_read" : true,
      "message_rand" : 2207687390,
      "message_sender" : "@TIM#SYSTEM",
      "message_seq" : 1,
      "message_server_time" : 1551344977,
      "message_status" : 2
   }
]

返回一个群提示消息的Json示例 (Json Key 请参考 Message、 GroupTipsElem)

[
   {
      "message_client_time" : 1551412814,
      "message_conv_id" : "first group id",
      "message_conv_type" : 2,
      "message_elem_array" : [
         {
            "elem_type" : 6,
            "group_tips_elem_changed_group_memberinfo_array" : [],
            "group_tips_elem_group_change_info_array" : [
               {
                  "group_tips_group_change_info_flag" : 10,
                  "group_tips_group_change_info_value" : "first group name to other name"
               }
            ],
            "group_tips_elem_group_id" : "first group id",
            "group_tips_elem_group_name" : "first group name to other name",
            "group_tips_elem_member_change_info_array" : [],
            "group_tips_elem_member_num" : 0,
            "group_tips_elem_op_group_memberinfo" : {
               "group_member_info_custom_info" : {},
               "group_member_info_identifier" : "user1",
               "group_member_info_join_time" : 0,
               "group_member_info_member_role" : 0,
               "group_member_info_msg_flag" : 0,
               "group_member_info_msg_seq" : 0,
               "group_member_info_name_card" : "",
               "group_member_info_shutup_time" : 0
            },
            "group_tips_elem_op_user" : "user1",
            "group_tips_elem_platform" : "Windows",
            "group_tips_elem_time" : 0,
            "group_tips_elem_tip_type" : 6,
            "group_tips_elem_user_array" : []
         }
      ],
      "message_is_from_self" : false,
      "message_is_read" : true,
      "message_rand" : 1,
      "message_sender" : "@TIM#SYSTEM",
      "message_seq" : 1,
      "message_server_time" : 1551412814,
      "message_status" : 2
   },
]

TIMMsgElemUploadProgressCallback

typedef void(* TIMMsgElemUploadProgressCallback) (const char *json_msg, uint32_t index, uint32_t cur_size, uint32_t total_size, const void *user_data)

1.2 消息内元素相关文件上传进度回调

参数

json_msg	新消息, Json Key 请参考 Message
index	上传的富媒体消息元素在 json_msg 消息的下标
cur_size	上传当前大小
total_size	上传总大小
user_data	ImSDK负责透传的用户自定义数据，未做任何处理

示例

void MsgElemUploadProgressCallback(const char* json_msg, uint32_t index, uint32_t cur_size, uint32_t total_size, const void* user_data) {
    Json::Value json_value_msg;
    Json::Reader reader;
    if (!reader.parse(json_msg, json_value_msg)) {
        // Json 解析失败
        return;
    }
    Json::Value& elems = json_value_msg[kTIMMsgElemArray];
    if (index >= elems.size()) {
        // index 超过消息元素个数范围
        return;
    }
    uint32_t elem_type = elems[index][kTIMElemType].asUInt();
    if (kTIMElem_File ==  elem_type) {

    }
    else if (kTIMElem_Sound == elem_type) {

    }
    else if (kTIMElem_Video == elem_type) {

    }
    else if (kTIMElem_Image == elem_type) {

    }
    else {
        // 其他类型元素不符合上传要求
    }
}

TIMMsgGroupMessageReadMemberListCallback

typedef void(* TIMMsgGroupMessageReadMemberListCallback) (const char *json_group_member_array, uint64_t next_seq, bool is_finished, const void *user_data)

1.3 获取群消息已读群成员列表

参数

json_group_member_array	群消息已读群成员列表, Json Key 请参考 GroupMemberInfo
next_seq	下一次分页拉取的游标
is_finished	群消息已读群成员列表是否已经拉取完毕
user_data	ImSDK负责透传的用户自定义数据，未做任何处理

示例

void MsgGroupReadMembersCallback(const char* json_group_member_array, uint64_t next_seq, bool is_finished, const void* user_data) {
    Json::Value member_array;
    Json::Reader reader;
    if (!reader.parse(json_group_member_array, member_array)) {
        // Json 解析失败
        return;
    }

    for (Json::ArrayIndex i = 0; i < member_array.size(); i++) {
        Json::Value& member = member_array[i];
        std::string user_id = member[kTIMGroupMemberInfoIdentifier].asString();
        std::string name_card = member[kTIMGroupMemberInfoNameCard].asString();
        std::string face_url = member[kTIMGroupMemberInfoFaceUrl].asString();
    }

    if (false == is_finished) {
        TIMMsgGetGroupMessageReadMemberList(json_msg, TIM_GROUP_MESSAGE_READ_MEMBERS_FILTER_READ, next_seq, 100, MsgGroupReadMembersCallback, user_data);
    }
}

TIMMsgReadedReceiptCallback

typedef void(* TIMMsgReadedReceiptCallback) (const char *json_msg_read_receipt_array, const void *user_data)

1.4 收到消息已读回执

参数

json_msg_read_receipt_array	消息已读回执数组, Json Key 请参考 MessageReceipt
user_data	ImSDK负责透传的用户自定义数据，未做任何处理

示例

void MsgReadedReceiptCallback(const char* json_msg_read_receipt_array, const void* user_data) {
    Json::Value json_value_receipts;
    Json::Reader reader;
    if (!reader.parse(json_msg_read_receipt_array, json_value_receipts)) {
        // Json 解析失败
        return;
    }

    for (Json::ArrayIndex i = 0; i < json_value_receipts.size(); i++) {
        Json::Value& json_value_receipt = json_value_receipts[i];
        uint32_t conv_type = json_value_receipt[kTIMMsgReceiptConvType].asUInt();
        std::string convid = json_value_receipt[kTIMMsgReceiptConvId].asString();

        // C2C 消息回执
        uint64_t timestamp = json_value_receipt[kTIMMsgReceiptTimeStamp].asUInt64();

        // 群消息回执
        std::string msg_id = json_value_receipt[kTIMMsgReceiptMsgId].asString();
        uint64_t read_count = json_value_receipt[kTIMMsgReceiptReadCount].asUInt64();
        uint64_t unread_count = json_value_receipt[kTIMMsgReceiptUnreadCount].asUInt64();

        // 消息已读逻辑
    }
}

TIMMsgRevokeCallback

typedef void(* TIMMsgRevokeCallback) (const char *json_msg_revoke_info_array, const void *user_data)

1.5 接收的消息被撤回回调

参数

json_msg_revoke_info_array	撤回信息数组, Json Key 请参考 Message, MsgLocator
user_data	ImSDK负责透传的用户自定义数据，未做任何处理

注意

从 7.4 版本开始，该回调支持返回撤回者信息和撤回原因

示例

void MsgRevokeCallback(const char* json_msg_revoke_info_array, const void* user_data) {
    Json::Value json_value_revoke_info_list;
    Json::Reader reader;
    if (!reader.parse(json_msg_revoke_info_array, json_value_revoke_info_list)) {
        // Json 解析失败
        return;
    }
    for (Json::ArrayIndex i = 0; i < json_value_revoke_info_list.size(); i++) {
        Json::Value& json_value_revoke_info = json_value_revoke_info_list[i];

        // 撤回的消息标识符
        std::string convid = json_value_revoke_info[kTIMMsgLocatorConvId].asString();
        uint32_t conv_type = json_value_revoke_info[kTIMMsgLocatorConvType].asUInt();
        bool isrevoke      = json_value_revoke_info[kTIMMsgLocatorIsRevoked].asBool();
        uint64_t time      = json_value_revoke_info[kTIMMsgLocatorTime].asUInt64();
        uint64_t seq       = json_value_revoke_info[kTIMMsgLocatorSeq].asUInt64();
        uint64_t rand      = json_value_revoke_info[kTIMMsgLocatorRand].asUInt64();
        bool isself        = json_value_revoke_info[kTIMMsgLocatorIsSelf].asBool();

        // 撤回者
        std::string revoker_id = json_value_revoke_info[kTIMMsgRevokerUserID].asString();
        std::string revoker_nick_name = json_value_revoke_info[kTIMMsgRevokerNickName].asString();
        std::string revoker_face_url = json_value_revoke_info[kTIMMsgRevokerFaceUrl].asString();

        // 撤回原因
        std::string revoke_reason = json_value_revoke_info[kTIMMsgRevokeReason].asString();

        // 消息撤回逻辑
    }
}

TIMMsgUpdateCallback

typedef void(* TIMMsgUpdateCallback) (const char *json_msg_array, const void *user_data)

1.6 消息更新回调

参数

json_msg_array	更新的消息数组, Json Key 请参考 Message
user_data	ImSDK负责透传的用户自定义数据，未做任何处理

注意

请参考 TIMRecvNewMsgCallback

TIMMsgExtensionsChangedCallback

typedef void(* TIMMsgExtensionsChangedCallback) (const char *message_id, const char *message_extension_array, const void *user_data)

1.7 消息扩展信息更新回调

参数

message_id	消息 ID
message_extension_array	扩展信息列表, Json Key 请参考 MessageExtension
user_data	ImSDK负责透传的用户自定义数据，未做任何处理

返回的扩展信息列表 json 示例

[
   {
       "message_extension_key":"extension_key_1",
       "message_extension_value":"extension_value_1"
   },
   {
       "message_extension_key":"extension_key_2",
       "message_extension_value":"extension_value_2"
   }
]

TIMMsgExtensionsDeletedCallback

typedef void(* TIMMsgExtensionsDeletedCallback) (const char *message_id, const char *message_extension_key_array, const void *user_data)

1.8 消息扩展信息删除回调

参数

message_id	消息 ID
message_extension_key_array	扩展信息的关键字列表, Json Key 请参考 MessageExtension
user_data	ImSDK负责透传的用户自定义数据，未做任何处理

返回的扩展信息的关键字列表 json 示例

[
   {
       "message_extension_key":"extension_key_1",
   }
]

TIMMsgReactionsChangedCallback

typedef void(* TIMMsgReactionsChangedCallback) (const char *message_reaction_change_info_array, const void *user_data)

1.9 消息回应信息更新回调

参数

message_reaction_change_info_array	回应信息变更列表, Json Key 请参考 MessageReactionChangeInfo
user_data	ImSDK负责透传的用户自定义数据，未做任何处理

注意

• 该回调是消息 Reaction 的增量回调，只会携带变更的 Reaction 信息。
• 当变更的 Reaction 信息里的 message_reaction_total_user_count 字段值为 0 时，表明该 Reaction 已经没有用户在使用，您可以在 UI 上移除该 Reaction 的展示。

返回的回应信息列表 json 示例

[
    {
        "message_reaction_change_info_msg_id":"12345678910-1689942227-1328217716",
        "message_reaction_change_info_reaction_list":[
            {
                "message_reaction_id":"emoji1",
                "message_reaction_total_user_count":1,
                "message_reaction_user_info_array":[
                    {
                        "user_profile_face_url":"www.google.com",
                        "user_profile_identifier":"kkkm",
                        "user_profile_nick_name":"mizore",
                    }
                ]
            }
        ]
    }
]

TIMMsgAllMessageReceiveOptionCallback

typedef void(* TIMMsgAllMessageReceiveOptionCallback) (const char *json_receive_message_option_info, const void *user_data)

1.10 登录用户全局消息接收选项变更通知

参数

json_receive_message_option_info	当前用户全局消息接收选项，请参考 TIMReceiveMessageOptInfo
user_data	ImSDK负责透传的用户自定义数据，未做任何处理

TIMMsgGroupPinnedMessageChangedCallback

typedef void(* TIMMsgGroupPinnedMessageChangedCallback) (const char *group_id, const char *json_msg, bool is_pinned, const char *op_user, const void *user_data)

1.11 群置顶消息更新的回调

参数

group_id	群组 ID
json_msg	变更的置顶消息
is_pinned	变更类型
op_user	操作人信息

注意

• 如果变更类型为取消置顶，message 参数中只有消息的 key，不包含完整的消息体。

函数说明

TIMAddRecvNewMsgCallback()

TIM_API void TIMAddRecvNewMsgCallback	(	TIMRecvNewMsgCallback	cb,
		const void *	user_data
	)

2.1 添加接收新消息回调

参数

cb	新消息回调函数，请参考 TIMRecvNewMsgCallback
user_data	用户自定义数据，ImSDK只负责传回给回调函数cb，不做任何处理

注意

如果用户是登录状态，ImSDK收到新消息会通过此接口设置的回调抛出，另外需要注意，抛出的消息不一定是未读的消息， 只是本地曾经没有过的消息（例如在另外一个终端已读，拉取最近联系人消息时可以获取会话最后一条消息，如果本地没有，会通过此方法抛出）。 在用户登录之后，ImSDK会拉取离线消息，为了不漏掉消息通知，需要在登录之前注册新消息通知。

TIMRemoveRecvNewMsgCallback()

TIM_API void TIMRemoveRecvNewMsgCallback

(

TIMRecvNewMsgCallback

cb

)

2.2 删除接收新消息回调

参数

cb	新消息回调函数，请参考 TIMRecvNewMsgCallback

注意

参数cb需要跟 TIMAddRecvNewMsgCallback 传入的cb一致，否则删除回调失败

TIMSetMsgElemUploadProgressCallback()

TIM_API void TIMSetMsgElemUploadProgressCallback	(	TIMMsgElemUploadProgressCallback	cb,
		const void *	user_data
	)

2.3 设置消息内元素相关文件上传进度回调

参数

cb	文件上传进度回调，请参考 TIMMsgElemUploadProgressCallback
user_data	用户自定义数据，ImSDK只负责传回给回调函数cb，不做任何处理

注意

设置消息元素上传进度回调。当消息内包含图片、声音、文件、视频元素时，ImSDK会上传这些文件，并触发此接口设置的回调，用户可以根据回调感知上传的进度

TIMSetMsgReadedReceiptCallback()

TIM_API void TIMSetMsgReadedReceiptCallback	(	TIMMsgReadedReceiptCallback	cb,
		const void *	user_data
	)

2.4 设置消息已读回执回调

参数

cb	消息已读回执回调，请参考 TIMMsgReadedReceiptCallback
user_data	用户自定义数据，ImSDK只负责传回给回调函数cb，不做任何处理

注意

发送方发送消息，接收方调用接口 TIMMsgReportReaded 上报 C2C 消息已读，或者调用 TIMMsgSendMessageReadReceipts 发送群消息已读回执，发送方ImSDK会通过此接口设置的回调抛出。

TIMSetMsgRevokeCallback()

TIM_API void TIMSetMsgRevokeCallback	(	TIMMsgRevokeCallback	cb,
		const void *	user_data
	)

2.5 设置接收的消息被撤回回调

参数

cb	消息撤回通知回调,请参考 TIMMsgRevokeCallback
user_data	用户自定义数据，ImSDK只负责传回给回调函数cb，不做任何处理

注意

发送方发送消息，接收方收到消息。此时发送方调用接口 TIMMsgRevoke 撤回该消息，接收方的ImSDK会通过此接口设置的回调抛出。

TIMSetMsgUpdateCallback()

TIM_API void TIMSetMsgUpdateCallback	(	TIMMsgUpdateCallback	cb,
		const void *	user_data
	)

2.6 设置消息更新的回调

参数

cb	消息更新回调，请参考 TIMMsgUpdateCallback
user_data	用户自定义数据，ImSDK只负责传回给回调函数cb，不做任何处理

注意

• 当您发送的消息在服务端被修改后，ImSDK会通过该回调通知给您
• 您可以在您自己的服务器上拦截所有即时通信IM消息 发单聊消息之前回调
• 设置成功之后，即时通信IM服务器会将您的用户发送的每条消息都同步地通知给您的业务服务器。
• 您的业务服务器可以对该条消息进行修改（例如过滤敏感词），如果您的服务器对消息进行了修改，ImSDK就会通过此回调通知您。

TIMSetMsgExtensionsChangedCallback()

TIM_API void TIMSetMsgExtensionsChangedCallback	(	TIMMsgExtensionsChangedCallback	cb,
		const void *	user_data
	)

2.7 设置消息扩展信息更新的回调

参数

cb	消息扩展信息更新回调,请参考 TIMMsgExtensionsChangedCallback
user_data	用户自定义数据，ImSDK只负责传回给回调函数cb，不做任何处理

TIMSetMsgExtensionsDeletedCallback()

TIM_API void TIMSetMsgExtensionsDeletedCallback	(	TIMMsgExtensionsDeletedCallback	cb,
		const void *	user_data
	)

2.8 设置消息扩展信息删除的回调

参数

cb	消息扩展信息删除回调,请参考 TIMMsgExtensionsDeletedCallback
user_data	用户自定义数据，ImSDK只负责传回给回调函数cb，不做任何处理

TIMSetMsgReactionsChangedCallback()

TIM_API void TIMSetMsgReactionsChangedCallback	(	TIMMsgReactionsChangedCallback	cb,
		const void *	user_data
	)

2.9 设置消息回应信息更新的回调

参数

cb	消息回应信息更新回调,请参考 TIMMsgReactionsChangedCallback
user_data	用户自定义数据，ImSDK只负责传回给回调函数cb，不做任何处理

TIMSetMsgAllMessageReceiveOptionCallback()

TIM_API void TIMSetMsgAllMessageReceiveOptionCallback	(	TIMMsgAllMessageReceiveOptionCallback	cb,
		const void *	user_data
	)

2.10 设置全局消息接收选项的回调

参数

cb	消息更新回调，请参考 TIMMsgAllMessageReceiveOptionCallback
user_data	用户自定义数据，ImSDK只负责传回给回调函数cb，不做任何处理

TIMSetMsgGroupPinnedMessageChangedCallback()

TIM_API void TIMSetMsgGroupPinnedMessageChangedCallback	(	TIMMsgGroupPinnedMessageChangedCallback	cb,
		const void *	user_data
	)

2.11 设置置顶消息变更的回调

参数

cb	群组置顶消息变更回调，请参考 TIMMsgGroupPinnedMessageChangedCallback
user_data	用户自定义数据，ImSDK只负责传回给回调函数cb，不做任何处理

TIMMsgSendMessage()

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

3.1 发送新消息

参数

conv_id	会话的ID
conv_type	会话类型，请参考 TIMConvType
json_msg_param	消息 json 字符串, Json Key 请参考 Message
message_id_buffer	消息 ID ，分配内存大小不能低于 128 字节，如果不需要，可传入 nullptr，调用接口后，可以读取到以 '\0' 结尾的字符串
cb	发送新消息成功与否的回调。回调函数定义请参考 TIMCommCallback
user_data	用户自定义数据，ImSDK只负责传回给回调函数 cb，不做任何处理

返回

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

注意

发送新消息，单聊消息和群消息的发送均采用此接口：

• 发送单聊消息时 conv_id 为对方的UserID， conv_type 为 kTIMConv_C2C
• 发送群聊消息时 conv_id 为群ID， conv_type 为 kTIMConv_Group 发送消息时不能发送 kTIMElem_GroupTips、 kTIMElem_GroupReport，他们由后台下发，用于更新(通知)群的信息。可以发送的消息内元素：
• 文本消息元素，请参考 TextElem
• 表情消息元素，请参考 FaceElem
• 位置消息元素，请参考 LocationElem
• 图片消息元素，请参考 ImageElem
• 声音消息元素，请参考 SoundElem
• 自定义消息元素，请参考 CustomElem
• 文件消息元素，请参考 FileElem
• 视频消息元素，请参考 VideoElem

示例

Json::Value json_value_text;
json_value_text[kTIMElemType] = kTIMElem_Text;
json_value_text[kTIMTextElemContent] = "send text";
Json::Value json_value_msg;
json_value_msg[kTIMMsgElemArray].append(json_value_text);

const size_t kMessageIDLength = 128;
char message_id_buffer[kMessageIDLength] = {0};
int ret = TIMMsgSendMessage(conv_id.c_str(), kTIMConv_C2C, json_value_msg.toStyledString().c_str(), message_id_buffer,
    [](int32_t code, const char* desc, const char* json_param, const void* user_data) {
    if (ERR_SUCC != code) {
        // 消息发送失败
        return;
    }
    // 消息发送成功
}, nullptr);

// json_value_msg.toStyledString().c_str() 得到 json_msg_param JSON 字符串如下
{
   "message_elem_array" : [
      {
         "elem_type" : 0,
         "text_elem_content" : "send text"
      }
   ]
}

TIMMsgCancelSend()

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

3.2 根据消息 messageID 取消发送中的消息

参数

conv_id	会话的ID
conv_type	会话类型，请参考 TIMConvType
message_id	消息 ID
cb	取消结果的回调。回调函数定义和参数解析请参考 TIMCommCallback
user_data	用户自定义数据，ImSDK只负责传回给回调函数cb，不做任何处理

返回

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

示例

TIMMsgCancelSend("test_win_03", kTIMConv_C2C, "message_id_1", [](int32_t code, const char* desc, const char* json_param, const void* user_data) {

}, nullptr);

TIMMsgBatchSend()

TIM_API int TIMMsgBatchSend	(	const char *	json_batch_send_param,
		TIMCommCallback	cb,
		const void *	user_data
	)

3.3 群发消息，该接口不支持向群组发送消息。

参数

json_batch_send_param	群发消息 json 字符串, Json Key 请参考 Message
cb	群发消息成功与否的回调。回调函数定义和参数解析请参考 TIMCommCallback
user_data	用户自定义数据，ImSDK只负责传回给回调函数cb，不做任何处理

返回

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

注意

批量发送消息的接口，每个UserID发送成功与否，通过回调cb返回。

示例

//构造消息文本元素
Json::Value json_value_elem;
json_value_elem[kTIMElemType] = TIMElemType::kTIMElem_Text;
json_value_elem[kTIMTextElemContent] = "this is batch send msg";
//构造消息
Json::Value json_value_msg;
json_value_msg[kTIMMsgElemArray].append(json_value_elem);

// 构造批量发送ID数组列表
Json::Value json_value_ids(Json::arrayValue);
json_value_ids.append("user2");
json_value_ids.append("user3");
// 构造批量发送接口参数
Json::Value json_value_batchsend;
json_value_batchsend[kTIMMsgBatchSendParamIdentifierArray] = json_value_ids;
json_value_batchsend[kTIMMsgBatchSendParamMsg] = json_value_msg;
int ret = TIMMsgBatchSend(json_value_batchsend.toStyledString().c_str(), [](int32_t code, const char* desc, const char* json_param, const void* user_data) {
}, nullptr);

// json_value_batchsend.toStyledString().c_str() 得到 json_batch_send_param JSON 字符串如下
{
   "msg_batch_send_param_identifier_array" : [ "user2", "user3" ],
   "msg_batch_send_param_msg" : {
      "message_elem_array" : [
         {
            "elem_type" : 0,
            "text_elem_content" : "this is batch send msg"
         }
      ]
   }
}

TIMMsgDownloadElemToPath()

TIM_API int TIMMsgDownloadElemToPath	(	const char *	json_download_elem_param,
		const char *	path,
		TIMCommCallback	cb,
		const void *	user_data
	)

3.4 下载消息内元素到指定文件路径(图片、视频、音频、文件)

参数

json_download_elem_param	下载的参数 Json 字符串, Json Key 请参考 DownloadElemParam
path	下载文件保存路径
cb	下载成功与否的回调以及下载进度回调。回调函数定义和参数解析请参考 TIMCommCallback
user_data	用户自定义数据，ImSDK只负责传回给回调函数cb，不做任何处理

返回

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

注意

此接口用于下载消息内图片、文件、声音、视频等元素。下载的参数 kTIMMsgDownloadElemParamId、kTIMMsgDownloadElemParamBusinessId、kTIMMsgDownloadElemParamUrl 均可以在相应元素内找到。 其中 kTIMMsgDownloadElemParamType 为下载文件类型 TIMDownloadType, 参数 path 要求是 UTF-8 编码

示例

Json::Value download_param;
download_param[kTIMMsgDownloadElemParamType] = type;
download_param[kTIMMsgDownloadElemParamId] = id;
download_param[kTIMMsgDownloadElemParamBusinessId] = business_id;
download_param[kTIMMsgDownloadElemParamUrl] = url;

TIMMsgDownloadElemToPath(download_param.toStyledString().c_str(), (path_ + "\\" + name).c_str(), [](int32_t code, const char* desc, const char* json_param, const void* user_data) {
    // 请注意，下载进度和下载结果会共用此回调，所以该回调可能会被多次调用
    // 当回调第二个参数 desc = "downloading" 时，表示下载进度（kTIMMsgDownloadElemResultCurrentSize、kTIMMsgDownloadElemResultTotalSize），否则表示下载结果
}, this);

TIMMsgDownloadMergerMessage()

TIM_API int TIMMsgDownloadMergerMessage	(	const char *	json_single_msg,
		TIMCommCallback	cb,
		const void *	user_data
	)

3.5 下载合并消息

参数

json_single_msg	单条消息的 JSON 字符串，接收消息、查找消息或查询历史消息时获取到的消息, Json Key 请参考 Message
cb	下载成功与否的回调以及下载进度回调。回调函数定义和参数解析请参考 TIMCommCallback
user_data	用户自定义数据，ImSDK只负责传回给回调函数cb，不做任何处理

返回

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

示例

// 接收一条消息 json_single_msg
TIMMsgDownloadMergerMessage(json_single_msg, [](int32_t code, const char* desc, const char* json_param, const void* user_data) {

}, this);

TIMMsgSetLocalCustomData()

TIM_API int TIMMsgSetLocalCustomData	(	const char *	json_msg_param,
		TIMCommCallback	cb,
		const void *	user_data
	)

3.6 设置消息自定义数据（本地保存，不会发送到对端，程序卸载重装后失效）

参数

json_msg_param	消息 json 字符串, Json Key 请参考 Message
cb	保存自定义消息成功与否的回调。回调函数定义请参考 TIMCommCallback
user_data	用户自定义数据，ImSDK只负责传回给回调函数cb，不做任何处理

返回

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

示例

Json::Value json_parameters;
json_parameters[kTIMMsgGetMsgListParamIsRamble] = true;
json_parameters[kTIMMsgGetMsgListParamIsForward] = false;
json_parameters[kTIMMsgGetMsgListParamCount] = 1;

TIMMsgGetMsgList("98826", kTIMConv_C2C, json_parameters.toStyledString().c_str(),
   [](int32_t code, const char* desc, const char* json_params, const void* user_data) {
    Json::Reader json_reader;
    json::Array json_message_array;
    json_reader.parse(json_params, json_message_array);
    if (json_message_array.size() > 0) {
        Json::Value json_obj_msg = json_message_array[0];
        json_obj_msg[kTIMMsgCustomStr] = "custom Str";
        json_obj_msg[kTIMMsgCustomInt] = 123;

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

TIMMsgSetC2CReceiveMessageOpt()

TIM_API int TIMMsgSetC2CReceiveMessageOpt	(	const char *	json_identifier_array,
		TIMReceiveMessageOpt	opt,
		TIMCommCallback	cb,
		const void *	user_data
	)

4.1 设置针对某个用户的 C2C 消息接收选项（支持批量设置）

参数

json_identifier_array	用户 ID 列表
opt	消息接收选项，请参考 TIMReceiveMessageOpt
cb	设置成功与否的回调。回调函数定义请参考 TIMCommCallback
user_data	用户自定义数据，ImSDK只负责传回给回调函数cb，不做任何处理

返回

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

注意

• 该接口支持批量设置，您可以通过参数 userIDList 设置一批用户，但一次最大允许设置 30 个用户。
• 该接口调用频率被限制为1秒内最多调用5次。

示例

Json::Value json_identifier_array(Json::arrayValue);
json_identifier_array.append("user1");
json_identifier_array.append("user2");

TIMMsgSetC2CReceiveMessageOpt(json_identifier_array.toStyledString().c_str(), kTIMRecvMsgOpt_Receive, [](int32_t code, const char* desc, const char* json_param, const void* user_data) {

}, this);

TIMMsgGetC2CReceiveMessageOpt()

TIM_API int TIMMsgGetC2CReceiveMessageOpt	(	const char *	json_identifier_array,
		TIMCommCallback	cb,
		const void *	user_data
	)

4.2 查询针对某个用户的 C2C 消息接收选项

参数

json_identifier_array	用户 ID 列表
cb	查询结果的回调。回调函数定义请参考 TIMCommCallback
user_data	用户自定义数据，ImSDK只负责传回给回调函数cb，不做任何处理

返回

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

示例

Json::Value json_identifier_array(Json::arrayValue);
json_identifier_array.append("user1");
json_identifier_array.append("user2");

TIMMsgGetC2CReceiveMessageOpt(json_identifier_array.toStyledString().c_str(), [](int32_t code, const char* desc, const char* json_param, const void* user_data) {

}, this);

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

[
   {
      "msg_recv_msg_opt_result_identifier" : "user1",
      "msg_recv_msg_opt_result_opt" : 0,
   },
   {
      "msg_recv_msg_opt_result_identifier" : "user2",
      "msg_recv_msg_opt_result_opt" : 1,
   }
]

TIMMsgSetGroupReceiveMessageOpt()

TIM_API int TIMMsgSetGroupReceiveMessageOpt	(	const char *	group_id,
		TIMReceiveMessageOpt	opt,
		TIMCommCallback	cb,
		const void *	user_data
	)

4.3 设置群消息的接收选项

参数

group_id	群 ID
opt	消息接收选项，请参考 TIMReceiveMessageOpt
cb	设置成功与否的回调。回调函数定义请参考 TIMCommCallback
user_data	用户自定义数据，ImSDK只负责传回给回调函数cb，不做任何处理

返回

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

注意

• 查询群消息的接收选项：您可以在群资料 GroupBaseInfo 中获得这个信息

示例

TIMMsgSetGroupReceiveMessageOpt("group_id", kTIMRecvMsgOpt_Receive, [](int32_t code, const char* desc, const char* json_param, const void* user_data) {

}, this);

TIMMsgSetAllReceiveMessageOpt()

TIM_API int TIMMsgSetAllReceiveMessageOpt	(	TIMReceiveMessageOpt	opt,
		int32_t	start_hour,
		int32_t	start_minute,
		int32_t	start_second,
		uint32_t	duration,
		TIMCommCallback	cb,
		const void *	user_data
	)

4.4 设置登录用户全局消息接收选项，从 7.4 版本开始支持

参数

opt	全局消息接收选项设置，请参考 TIMReceiveMessageOpt
start_hour	(0 - 23) 免打扰开始时间：小时，取值范围[0 - 23]
start_minute	(0 - 59) 免打扰开始时间：分钟，取值范围[0 - 59]
start_second	(0 - 59) 免打扰开始时间：秒，取值范围[0 - 59]
duration	免打扰持续时长：单位：秒，取值范围 [0 - 24*60*60].
cb	设置成功与否的回调。回调函数定义请参考 TIMCommCallback
user_data	用户自定义数据，ImSDK只负责传回给回调函数cb，不做任何处理

返回

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

注意

请注意

• 当 duration 的取值小于 24*60*60 时，可用于实现重复免打扰，即消息免打扰从每天的 start_hour:start_minute:start_second 表示的时间点开始，持续时长为 duration 秒
• 当 duration 取值不小于 24*60*60 时，可用于实现永久免打扰，即从调用该 API 当天 start_hour:start_minute:start_second 表示的时间点开始永久消息免打扰

示例

TIMMsgSetAllReceiveMessageOpt(kTIMRecvMsgOpt_Receive, 12, 0, 0, 60*60*2, [](int32_t code, const char* desc, const char* json_param, const void* user_data) {

}, this);

TIMMsgSetAllReceiveMessageOpt2()

TIM_API int TIMMsgSetAllReceiveMessageOpt2	(	TIMReceiveMessageOpt	opt,
		uint32_t	start_time_stamp,
		uint32_t	duration,
		TIMCommCallback	cb,
		const void *	user_data
	)

4.5 设置登录用户全局消息接收选项，从 7.4 版本开始支持

参数

opt	全局消息接收选项设置，请参考 TIMReceiveMessageOpt
start_time_stamp	免打扰开始时间，UTC 时间戳，单位：秒
duration	免打扰持续时长：单位：秒
cb	设置成功与否的回调。回调函数定义请参考 TIMCommCallback
user_data	用户自定义数据，ImSDK只负责传回给回调函数cb，不做任何处理

返回

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

示例

TIMMsgSetAllReceiveMessageOpt(kTIMRecvMsgOpt_Receive, 123456, 60*60*2, [](int32_t code, const char* desc, const char* json_param, const void* user_data) {

}, this);

TIMMsgGetAllReceiveMessageOpt()

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

4.6 获取登录用户全局消息接收选项，从 7.4 版本开始支持

参数

cb	查询结果的回调。回调函数定义请参考 TIMCommCallback
user_data	用户自定义数据，ImSDK只负责传回给回调函数cb，不做任何处理

返回

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

示例

TIMMsgGetAllReceiveMessageOpt([](int32_t code, const char* desc, const char* json_param, const void* user_data) {

}, this);

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

[
   {
      "kTIMMsgAllRecvMsgOptLevel" : "kTIMRecvMsgOpt_Not_Notify",
      "kTIMMsgAllRecvMsgOptStartHour" : 12,    // 免打扰开始时间：小时
      "kTIMMsgAllRecvMsgOptStartMinute" : 0,    // 免打扰开始时间：分钟
      "kTIMMsgAllRecvMsgOptStartSecond" : 0,    // 免打扰开始时间：秒
      "kTIMMsgAllRecvMsgOptStartTimeStamp" : 0,
      "kTIMMsgAllRecvMsgDuration" : 7200,
   }
]

// 或者

[
   {
      "kTIMMsgAllRecvMsgOptLevel" : "kTIMRecvMsgOpt_Not_Notify",
      "kTIMMsgAllRecvMsgOptStartHour" : 0,
      "kTIMMsgAllRecvMsgOptStartMinute" : 0,
      "kTIMMsgAllRecvMsgOptStartSecond" : 0,
      "kTIMMsgAllRecvMsgOptStartTimeStamp" : 123456,    // 免打扰开始时间，UTC 时间戳，单位：秒
      "kTIMMsgAllRecvMsgDuration" : 7200,
   }
]

TIMMsgGetMsgList()

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

5.1 获取指定会话的历史消息

参数

conv_id	会话的ID
conv_type	会话类型，请参考 TIMConvType
json_get_msg_param	消息获取参数，Json Key 定义请参考 MsgGetMsgListParam
cb	获取指定会话的消息列表成功与否的回调。回调函数定义和参数解析请参考 TIMCommCallback
user_data	用户自定义数据，ImSDK只负责传回给回调函数cb，不做任何处理

返回

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

注意

从 kTIMMsgGetMsgListParamLastMsg 指定的消息开始获取本地消息列表，kTIMMsgGetMsgListParamCount 为要获取的消息数目。kTIMMsgGetMsgListParamLastMsg 可以不指定，不指定时表示以会话最新的消息为 LastMsg 。 若指定 kTIMMsgGetMsgListParamIsRamble 为 true 则本地消息获取不够指定数目时，会去获取云端漫游消息。 kTIMMsgGetMsgListParamIsForward 为 true 时表示获取比 kTIMMsgGetMsgListParamLastMsg 新的消息，为 false 时表示获取比 kTIMMsgGetMsgListParamLastMsg 旧的消息

拉取 kTIMConv_C2C 消息时，只能使用 kTIMMsgGetMsgListParamLastMsg 作为消息的拉取起点；如果没有指定 kTIMMsgGetMsgListParamLastMsg，默认使用会话的最新消息作为拉取起点 拉取 kTIMConv_Group 消息时，除了可以使用 kTIMMsgGetMsgListParamLastMsg 作为消息的拉取起点外，也可以使用 kTIMMsgGetMsgListParamLastMsgSeq 来指定消息的拉取起点，二者的区别在于：

• 使用 kTIMMsgGetMsgListParamLastMsg 作为消息的拉取起点时，返回的消息列表里不包含 kTIMMsgGetMsgListParamLastMsg；
• 使用 kTIMMsgGetMsgListParamLastMsgSeq 作为消息拉取起点时，返回的消息列表里包含 kTIMMsgGetMsgListParamLastMsgSeq 所表示的消息；

在拉取 kTIMConv_Group 消息时

• 如果同时指定了 kTIMMsgGetMsgListParamLastMsg 和 kTIMMsgGetMsgListParamLastMsgSeq，SDK 优先使用 kTIMMsgGetMsgListParamLastMsg 作为消息的拉取起点
• 如果 kTIMMsgGetMsgListParamLastMsg 和 kTIMMsgGetMsgListParamLastMsgSeq，SDK 都未指定，消息的拉取起点分为如下两种情况：
• 如果设置了拉取的时间范围，SDK 会根据 kTIMMsgGetMsgListParamTimeBegin 所描述的时间点作为拉取起点
• 如果未设置拉取的时间范围，SDK 默认使用会话的最新消息作为拉取起点
• 如果设置了 kTIMMsgGetMsgListParamMessageSequenceArray，则 SDK 优先按照指定的 sequence 返回消息列表

请注意以下特殊逻辑：

• 如果没有触发登录，调用该接口不会返回历史消息
• 如果登录失败，调用该接口会返回本地历史消息
• 如果 SDK 检测到没有网络，调用该接口会返回本地历史消息
• 如果登录成功且网络正常，当 kTIMMsgGetMsgListParamIsRamble 设置为 true 时，调用该接口会先请求云端历史消息，然后再和本地历史消息合并后返回
• 只有会议群（Meeting）才能拉取到进群前的历史消息，直播群（AVChatRoom）消息不存漫游和本地数据库，调用这个接口无效

获取 C2C 会话 Windows-02 消息列表示例

Json::Value json_msg(Json::objectValue); // 构造Message
Json::Value json_get_msg_param;
json_get_msg_param[kTIMMsgGetMsgListParamLastMsg] = json_msg;
json_get_msg_param[kTIMMsgGetMsgListParamIsRamble] = false;
json_get_msg_param[kTIMMsgGetMsgListParamIsForward] = true;
json_get_msg_param[kTIMMsgGetMsgListParamCount] = 100;

int ret = TIMMsgGetMsgList("Windows-02", kTIMConv_C2C, json_get_msg_param.toStyledString().c_str(), [](int32_t code, const char* desc, const char* json_params, const void* user_data) {
}, this);

// json_get_msg_param.toStyledString().c_str() 得到 json_get_msg_param JSON 字符串如下
{
   "msg_getmsglist_param_count" : 100,
   "msg_getmsglist_param_is_forward" : true,
   "msg_getmsglist_param_is_ramble" : false,
   "msg_getmsglist_param_last_msg" : {}
}

TIMMsgRevoke()

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

5.2 消息撤回

参数

conv_id	会话的ID
conv_type	会话类型，请参考 TIMConvType
json_msg_param	消息 json 字符串, Json Key 请参考 Message
cb	消息撤回成功与否的回调。回调函数定义请参考 TIMCommCallback
user_data	用户自定义数据，ImSDK只负责传回给回调函数cb，不做任何处理

返回

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

注意

• 消息撤回。使用保存的消息Json或者用消息定位符查找到的消息Json，避免重复构造消息Json.
• 撤回消息的时间限制默认 2 minutes，超过 2 minutes 的消息不能撤回，您也可以在 控制台（功能配置 -> 登录与消息 -> 消息撤回设置）自定义撤回时间限制。
• 仅支持单聊和群组中发送的普通消息，无法撤销 kTIMMsgIsOnlineMsg 为 true 即仅在线用户才能收到的消息。
• 如果发送方撤回消息，已经收到消息的一方会收到 TIMMsgRevokeExCallback 回调。
• 从 IMSDK 7.4 版本开始，支持撤回包括直播群（AVChatRoom）、社群在内的所有群类型的消息。
• 在单聊场景中，仅能撤回自己的消息；在群聊场景中，除了可以撤回自己的消息外，管理员或者群主也可以撤回其他群成员的消息。

示例

Json::Value json_value_text;
json_value_text[kTIMElemType] = kTIMElem_Text;
json_value_text[kTIMTextElemContent] = "send text";
Json::Value json_value_msg;
json_value_msg[kTIMMsgElemArray].append(json_value_text);

int ret = TIMMsgSendNewMsg("test_win_03", kTIMConv_C2C, json_value_msg.toStyledString().c_str(), [](int32_t code, const char* desc, const char* json_param, const void* user_data) {
    if (ERR_SUCC != code) {
        // 消息发送失败
        return;
    }
    // 消息发送成功 json_param 返回发送后的消息json字符串
    TIMMsgRevoke("test_win_03", kTIMConv_C2C, json_param, [](int32_t code, const char* desc, const char* json_param, const void* user_data) {
        if (ERR_SUCC != code) {
            // 消息撤回失败
            return;
        }
        // 消息撤回成功

    }, user_data);
}, this);

TIMMsgModifyMessage()

TIM_API int TIMMsgModifyMessage	(	const char *	json_msg_param,
		TIMCommCallback	cb,
		const void *	user_data
	)

5.3 消息变更

参数

json_msg_param	消息 json 字符串, Json Key 请参考 Message
cb	修改消息内容成功与否的回调。回调函数定义请参考 TIMCommCallback
user_data	用户自定义数据，ImSDK只负责传回给回调函数cb，不做任何处理

返回

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

注意

• 如果消息修改成功，自己和对端用户（C2C）或群组成员（Group）都会收到 TIMSetMsgUpdateCallback 设置的回调。
• 如果在修改消息过程中，消息已经被其他人修改，cb 会返回 ERR_SDK_MSG_MODIFY_CONFLICT 错误。
• 消息无论修改成功或则失败，cb 都会返回最新的消息对象。

示例

Json::Value json_value_text;
json_value_text[kTIMElemType] = kTIMElem_Text;
json_value_text[kTIMTextElemContent] = "send text";
Json::Value json_value_msg;
json_value_msg[kTIMMsgElemArray].append(json_value_text);

int ret = TIMMsgSendNewMsg("test_win_03", kTIMConv_C2C, json_value_msg.toStyledString().c_str(), [](int32_t code, const char* desc, const char* json_param, const void* user_data) {
    if (ERR_SUCC != code) {
        // 消息发送失败
        return;
    }
    // 消息发送成功 json_param 返回发送后的消息json字符串
    TIMMsgModifyMessage(json_param, [](int32_t code, const char* desc, const char* json_param, const void* user_data) {
        if (ERR_SUCC != code) {
            // 修改消息内容失败
            return;
        }
        // 修改消息内容成功

    }, user_data);
}, this);

TIMMsgDelete()

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

5.4 删除指定会话的消息

参数

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

返回

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

示例

Json::Value json_value_msg(Json::objectValue);
Json::Value json_value_msgdelete;
json_value_msgdelete[kTIMMsgDeleteParamMsg] = json_value_msg;
TIMMsgDelete("user2", kTIMConv_C2C, json_value_msgdelete.toStyledString().c_str(), [](int32_t code, const char* desc, const char* json_param, const void* user_data) {

}, nullptr);

// json_value_msgdelete.toStyledString().c_str() 得到 json_msgdel_param JSON 字符串如下
{
  "msg_delete_param_is_ramble" : false,
  "msg_delete_param_msg" : {}
}

TIMMsgListDelete()

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

5.5 删除指定会话的本地及漫游消息列表

参数

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

返回

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

注意

本接口会在删除本地消息的同时也会删除漫游消息。需要注意以下几点：

• 建议将之前的消息数组Json保存，然后删除的时候直接调用接口，避免构造消息数组。
• 一次最多只能删除 50 条消息。
• 一秒钟最多只能调用一次该接口。
• 如果该账号在其他设备上拉取过这些消息，那么调用该接口删除后，这些消息仍然会保存在那些设备上，即删除消息不支持多端同步。

示例

Json::Value json_value_elem; //构造消息文本元素
json_value_elem[kTIMElemType] = TIMElemType::kTIMElem_Text;
json_value_elem[kTIMTextElemContent] = "this is import msg";

Json::Value json_value_msg; //构造消息
json_value_msg[kTIMMsgSender] = login_id;
json_value_msg[kTIMMsgClientTime] = time(NULL);
json_value_msg[kTIMMsgServerTime] = time(NULL);
json_value_msg[kTIMMsgElemArray].append(json_value_elem);

Json::Value json_value_msgs;  //消息数组
json_value_msgs.append(json_value_msg);

TIMMsgListDelete("user2", kTIMConv_C2C, json_value_msgs.toStyledString().c_str(), [](int32_t code, const char* desc, const char* json_param, const void* user_data) {

}, nullptr);

// json_value_msgs.toStyledString().c_str() 得到json_msg_array JSON 字符串如下
[
   {
      "message_client_time" : 1551446728,
      "message_elem_array" : [
         {
            "elem_type" : 0,
            "text_elem_content" : "I will be deleted"
         }
      ],
      "message_sender" : "user1",
      "message_server_time" : 1551446728
   }
]

TIMMsgClearHistoryMessage()

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

5.6 清空指定会话的消息

参数

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

返回

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

示例

TIMMsgClearHistoryMessage("user2", kTIMConv_C2C, [](int32_t code, const char* desc, const char* json_param, const void* user_data) {

}, nullptr);

TIMMsgSaveMsg()

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

5.7 保存自定义消息

参数

conv_id	会话的ID
conv_type	会话类型，请参考 TIMConvType
json_msg_param	消息 json 字符串, 消息的 Json Key 请参考 Message
cb	保存自定义消息成功与否的回调。回调函数定义请参考 TIMCommCallback
user_data	用户自定义数据，ImSDK只负责传回给回调函数cb，不做任何处理

返回

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

注意

消息保存接口，一般是自己构造一个消息 Json 字符串，然后保存到指定会话

TIMMsgImportMsgList()

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

5.8 导入消息列表到指定会话

参数

conv_id	会话的ID
conv_type	会话类型，请参考 TIMConvType
json_msg_array	消息数组, 消息的 Json Key 请参考 Message
cb	导入消息列表到指定会话成功与否的回调。回调函数定义请参考 TIMCommCallback
user_data	用户自定义数据，ImSDK只负责传回给回调函数cb，不做任何处理

返回

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

注意

批量导入消息，可以自己构造消息去导入。也可以将之前要导入的消息数组 Json 保存，然后导入的时候直接调用接口，避免构造消息数组

示例

Json::Value json_value_elem; //构造消息文本元素
json_value_elem[kTIMElemType] = TIMElemType::kTIMElem_Text;
json_value_elem[kTIMTextElemContent] = "this is import msg";

Json::Value json_value_msg; //构造消息
json_value_msg[kTIMMsgSender] = login_id;
json_value_msg[kTIMMsgClientTime] = time(NULL);
json_value_msg[kTIMMsgServerTime] = time(NULL);
json_value_msg[kTIMMsgElemArray].append(json_value_elem);

Json::Value json_value_msgs;  //消息数组
json_value_msgs.append(json_value_msg);

TIMMsgImportMsgList("user2", kTIMConv_C2C, json_value_msgs.toStyledString().c_str(), [](int32_t code, const char* desc, const char* json_param, const void* user_data) {

}, nullptr);

// json_value_msgs.toStyledString().c_str() 得到json_msg_array JSON 字符串如下
[
   {
      "message_client_time" : 1551446728,
      "message_elem_array" : [
         {
            "elem_type" : 0,
            "text_elem_content" : "this is import msg"
         }
      ],
      "message_sender" : "user1",
      "message_server_time" : 1551446728
   }
]

TIMMsgFindMessages()

TIM_API int TIMMsgFindMessages	(	const char *	json_message_id_array,
		TIMCommCallback	cb,
		const void *	user_data
	)

5.9 根据消息 messageID 查询本地的消息列表

参数

json_message_id_array	消息 ID 列表
cb	根据消息 messageID 查询本地的消息列表成功与否的回调。回调函数定义和参数解析请参考 TIMCommCallback
user_data	用户自定义数据，ImSDK只负责传回给回调函数cb，不做任何处理

返回

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

示例

Json::Value json_message_id_1("id_clienttime_rand_1");
Json::Value json_message_id_2("id_clienttime_rand_2");

Json::Value json_message_id_array;
json_message_id_array.append(json_message_id_1);
json_message_id_array.append(json_message_id_2);
TIMMsgFindMessages(json_message_id_array.toStyledString().c_str(), [](int32_t code, const char* desc, const char* json_param, const void* user_data) {

}, nullptr);

// json_message_id_array.toStyledString().c_str() 的到 json_message_id_array JSON 字符串如下
[
   "id_clienttime_rand_1",
   "id_clienttime_rand_2",
]

TIMMsgFindByMsgLocatorList()

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

5.10 根据消息定位精准查找指定会话的消息

参数

conv_id	会话的ID
conv_type	会话类型，请参考 TIMConvType
json_msg_Locator_array	消息定位符数组, Json Key 请参考 MsgLocator
cb	根据消息定位精准查找指定会话的消息成功与否的回调。回调函数定义和参数解析请参考 TIMCommCallback
user_data	用户自定义数据，ImSDK只负责传回给回调函数cb，不做任何处理

返回

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

注意

• 此接口根据消息定位符精准查找指定会话的消息，该功能一般用于消息撤回时查找指定消息等
• 一个消息定位符对应一条消息

示例

Json::Value json_msg_locator;                      // 一条消息对应一个消息定位符(精准定位)
json_msg_locator[kTIMMsgLocatorIsRevoked] = false; // 消息是否被撤回
json_msg_locator[kTIMMsgLocatorTime] = 123;        // 填入消息的时间
json_msg_locator[kTIMMsgLocatorSeq] = 1;
json_msg_locator[kTIMMsgLocatorIsSelf] = false;
json_msg_locator[kTIMMsgLocatorRand] = 12345678;

Json::Value json_msg_locators;
json_msg_locators.append(json_msg_locator);
TIMMsgFindByMsgLocatorList("user2", kTIMConv_C2C, json_msg_locators.toStyledString().c_str(), [](int32_t code, const char* desc, const char* json_param, const void* user_data) {

}, nullptr);

// json_msg_locators.toStyledString().c_str() 的到 json_msg_Locator_array JSON 字符串如下
[
   {
      "message_locator_is_revoked" : false,
      "message_locator_is_self" : false,
      "message_locator_rand" : 12345678,
      "message_locator_seq" : 1,
      "message_locator_time" : 123
   }
]

TIMMsgSearchLocalMessages()

TIM_API int TIMMsgSearchLocalMessages	(	const char *	json_search_message_param,
		TIMCommCallback	cb,
		const void *	user_data
	)

5.11 搜索本地消息（5.4.666 及以上版本支持，需要您购买旗舰版套餐）

参数

json_search_message_param	消息搜索参数, Json Key 请参考 MessageSearchParam
cb	搜索成功与否的回调。回调函数定义和参数解析请参考 TIMCommCallback
user_data	用户自定义数据，ImSDK只负责传回给回调函数cb，不做任何处理

返回

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

搜索本地消息示例

Json::Value json_search_message_param;
json_search_message_param[kTIMMsgSearchParamKeywordArray].append("keyword1");
json_search_message_param[kTIMMsgSearchParamKeywordArray].append("keyword2");
json_search_message_param[kTIMMsgSearchParamMessageTypeArray].append(kTIMElem_Text);
json_search_message_param[kTIMMsgSearchParamMessageTypeArray].append(kTIMElem_Image);
json_search_message_param[kTIMMsgSearchParamConvId] = "xxxxx";
json_search_message_param[kTIMMsgSearchParamConvType] = kTIMConv_Group;
json_search_message_param[kTIMMsgSearchParamPageIndex] = 0;
json_search_message_param[kTIMMsgSearchParamPageSize] = 10;

int ret = TIMMsgSearchLocalMessages(json_search_message_param.toStyledString().c_str(), [](int32_t code, const char* desc, const char* json_params, const void* user_data) {

}, this);

// json_search_message_param.toStyledString().c_str() 得到 json_search_message_param JSON 字符串如下
{
   "msg_search_param_keyword_array" : ["keyword1", "keyword2"],
   "msg_search_param_message_type_array" : [0, 1],
   "msg_search_param_page_index" : 0,
   "msg_search_param_page_size" : 10
}

TIMMsgSearchCloudMessages()

TIM_API int TIMMsgSearchCloudMessages	(	const char *	json_search_message_param,
		TIMCommCallback	cb,
		const void *	user_data
	)

5.12 搜索云端消息（7.3 及以上版本支持，需要您购买旗舰版套餐）

参数

json_search_message_param	消息搜索参数, Json Key 请参考 MessageSearchParam
cb	搜索成功与否的回调。回调函数定义和参数解析请参考 TIMCommCallback
user_data	用户自定义数据，ImSDK只负责传回给回调函数cb，不做任何处理

返回

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

注意

• 该功能为 IM 增值功能，详见价格说明
• 如果您没有开通该服务，调用接口会返回 60020 错误码

搜索云端消息示例

Json::Value json_search_message_param;
json_search_message_param[kTIMMsgSearchParamKeywordArray].append("keyword1");
json_search_message_param[kTIMMsgSearchParamKeywordArray].append("keyword2");
json_search_message_param[kTIMMsgSearchParamMessageTypeArray].append(kTIMElem_Text);
json_search_message_param[kTIMMsgSearchParamMessageTypeArray].append(kTIMElem_Image);
json_search_message_param[kTIMMsgSearchParamConvId] = "xxxxx";
json_search_message_param[kTIMMsgSearchParamConvType] = kTIMConv_Group;
json_search_message_param[kTIMMsgSearchParamSearchCount] = 10;
json_search_message_param[kTIMMsgSearchParamSearchCursor] = "xxxxx";

int ret = TIMMsgSearchCloudMessages(json_search_message_param.toStyledString().c_str(), [](int32_t code, const char* desc, const char* json_params, const void* user_data) {

}, this);

// json_search_message_param.toStyledString().c_str() 得到 json_search_message_param JSON 字符串如下
{
   "msg_search_param_keyword_array" : ["keyword1", "keyword2"],
   "msg_search_param_message_type_array" : [0, 1],
   "msg_search_param_search_count" : 10,
   "msg_search_param_search_cursor" : ""
}

TIMMsgSendMessageReadReceipts()

TIM_API int TIMMsgSendMessageReadReceipts	(	const char *	json_msg_array,
		TIMCommCallback	cb,
		const void *	user_data
	)

5.13 发送消息已读回执 （6.1 及其以上版本支持，需要您购买旗舰版套餐）

参数

json_msg_array	消息列表, 消息的 Json Key 请参考 Message
cb	成功与否的回调。回调函数定义和参数解析请参考 TIMCommCallback
user_data	用户自定义数据，ImSDK只负责传回给回调函数cb，不做任何处理

返回

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

注意

请注意：

• 向群消息发送已读回执，需要您先到控制台打开对应的开关，详情参考文档 群消息已读回执 。
• 该接口调用成功后，会话未读数不会变化，消息发送者会收到 TIMSetMsgReadedReceiptCallback 注册的回调，回调里面会携带消息的最新已读信息。

发送消息已读回执示例

int ret = TIMMsgSendMessageReadReceipts(json_msg_array, [](int32_t code, const char* desc, const char* json_params, const void* user_data) {
}, this);

TIMMsgGetMessageReadReceipts()

TIM_API int TIMMsgGetMessageReadReceipts	(	const char *	json_msg_array,
		TIMCommCallback	cb,
		const void *	user_data
	)

5.14 获取消息已读回执（6.1 及其以上版本支持，需要您购买旗舰版套餐）

参数

json_msg_array	消息列表, 消息的 Json Key 请参考 Message
cb	成功与否的回调。回调函数定义和参数解析请参考 TIMCommCallback
user_data	用户自定义数据，ImSDK只负责传回给回调函数cb，不做任何处理

返回

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

注意

请注意：

• 获取群消息已读回执，需要您先到控制台打开对应的开关，详情参考文档 群消息已读回执 。
• json_msg_array 中的多条消息必须在同一个会话中。

获取消息已读回执示例

int ret = TIMMsgGetMessageReadReceipts(json_msg_array, [](int32_t code, const char* desc, const char* json_params, const void* user_data) {
    Json::Value json_value_receipts;
    Json::Reader reader;
    if (!reader.parse(json_params, json_value_receipts)) {
        // Json 解析失败
        return;
    }

    for (Json::ArrayIndex i = 0; i < json_value_receipts.size(); i++) {
        Json::Value& json_value_receipt = json_value_receipts[i];
        uint32_t conv_type = json_value_receipt[kTIMMsgReceiptConvType].asUInt();
        std::string group_id = json_value_receipt[kTIMMsgReceiptConvId].asString();
        std::string msg_id = json_value_receipt[kTIMMsgReceiptMsgId].asString();
        uint64_t read_count = json_value_receipt[kTIMMsgReceiptReadCount].asUInt64();
        uint64_t unread_count = json_value_receipt[kTIMMsgReceiptUnreadCount].asUInt64();
    }
}, this);

TIMMsgGetGroupMessageReadMemberList()

TIM_API int TIMMsgGetGroupMessageReadMemberList	(	const char *	json_msg,
		TIMGroupMessageReadMembersFilter	filter,
		uint64_t	next_seq,
		uint32_t	count,
		TIMMsgGroupMessageReadMemberListCallback	cb,
		const void *	user_data
	)

5.15 获取群消息已读群成员列表（6.1 及其以上版本支持，需要您购买旗舰版套餐）

参数

json_msg	单条群消息, Json Key 请参考 Message
filter	指定拉取已读或未读群成员列表。
next_seq	分页拉取的游标，第一次默认取传 0，后续分页拉取时，传上一次分页拉取成功回调里的 next_seq
count	分页拉取的个数，最大支持 100 个。
cb	成功与否的回调。回调函数定义和参数解析请参考 TIMCommCallback
user_data	用户自定义数据，ImSDK只负责传回给回调函数cb，不做任何处理

返回

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

注意

请注意：

• 使用该功能之前，请您先到控制台打开对应的开关，详情参考文档 群消息已读回执 。

发送群消息已读回执示例

int ret = TIMMsgGetGroupMessageReadMemberList(json_msg, TIM_GROUP_MESSAGE_READ_MEMBERS_FILTER_READ, next_seq, 100,
        [](const char* json_group_member_array, uint64_t next_seq, bool is_finished, const void* user_data) {
    Json::Value member_array;
    Json::Reader reader;
    if (!reader.parse(json_group_member_array, member_array)) {
        // Json 解析失败
        return;
    }

    for (Json::ArrayIndex i = 0; i < member_array.size(); i++) {
        Json::Value& member = member_array[i];
        std::string user_id = member[kTIMGroupMemberInfoIdentifier].asString();
        std::string name_card = member[kTIMGroupMemberInfoNameCard].asString();
        std::string face_url = member[kTIMGroupMemberInfoFaceUrl].asString();
    }

    if (false == is_finished) {
        TIMMsgGetGroupMessageReadMemberList(json_msg, TIM_GROUP_MESSAGE_READ_MEMBERS_FILTER_READ, next_seq, 100, MsgGroupReadMembersCallback, user_data);
    }
}, this);

TIMMsgSetMessageExtensions()

TIM_API int TIMMsgSetMessageExtensions	(	const char *	json_msg,
		const char *	json_extension_array,
		TIMCommCallback	cb,
		const void *	user_data
	)

5.16 设置消息扩展 （6.7 及其以上版本支持，需要您购买旗舰版套餐）

参数

json_msg	消息 json 字符串, Json Key 请参考 Message。消息需满足三个条件：1、消息发送前需设置 kTIMMsgSupportMessageExtension 为 true，2、消息必须是发送成功的状态，3、消息不能是直播群（AVChatRoom）消息。
json_extension_array	消息扩展信息 json 字符串, Json Key 请参考 MessageExtension。如果扩展的 key 已经存在，则修改扩展的 value 信息，否则新增扩展
cb	成功与否的回调。回调函数定义请参考 TIMCommCallback
user_data	用户自定义数据，ImSDK只负责传回给回调函数cb，不做任何处理

返回

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

注意

• 扩展 key 最大支持 100 字节，扩展 value 最大支持 1KB，单次最多支持设置 20 个扩展，单条消息最多可设置 300 个扩展
• 当多个用户同时设置同一个扩展 key 时，只有第一个用户可以执行成功，其它用户会收到 23001 错误码和更新后的扩展信息
• 在收到错误码和最新扩展信息后，请按需重新发起设置操作
• 我们强烈建议不同的用户设置不同的扩展 key，这样大部分场景都不会冲突，比如投票、接龙、问卷调查，都可以把自己的 userID 作为扩展 key

设置消息扩展示例

json::Array json_element_array;
json::Object json_element;
json_element[kTIMElemType] = kTIMElem_Text;
json_element[kTIMTextElemContent] = "send text";
json_element_array.push_back(json_element);

json::Object json_message;
// 设置此消息支持消息扩展
json_message[kTIMMsgSupportMessageExtension] = true;
json_message[kTIMMsgElemArray] = json_element_array;
std::string json_parameters = json::Serialize(json_message);

const size_t kMessageIDLength = 128;
char message_id_buffer[kMessageIDLength] = {0};
TIMMsgSendMessage(GetGroupID().c_str(), kTIMConv_Group, json_parameters.c_str(), message_id_buffer,
    [](int32_t code, const char* desc, const char* json_param, const void* user_data) {
        if (ERR_SUCC != code) {
            // 消息发送失败
            return;
        }

         // 设置消息扩展字段参数
        json::Object json_extension_item;
        json_extension_item[kTIMMsgExtensionKey]   = "extension_key";
        json_extension_item[kTIMMsgExtensionValue] = "extension_value";

        json::Array json_extension_array;
        json_extension_array.push_back(json_extension_item);

        // 消息发送成功, json_param 为返回发送后的消息json字符串
        TIMMsgSetMessageExtensions(json_param, json::Serialize(json_extension_array).c_str(),
            [](int32_t code, const char* desc, const char* json_param, const void* user_data) {
                if (ERR_SUCC != code) {
                    // 设置消息扩展失败
                    return;
                }
                // 设置消息扩展成功
            }, user_data);
}, nullptr);

TIMMsgGetMessageExtensions()

TIM_API int TIMMsgGetMessageExtensions	(	const char *	json_msg,
		TIMCommCallback	cb,
		const void *	user_data
	)

5.17 获取消息扩展（6.7 及其以上版本支持，需要您购买旗舰版套餐）

参数

json_msg	消息 json 字符串, Json Key 请参考 Message
cb	成功与否的回调。回调函数定义请参考 TIMCommCallback
user_data	用户自定义数据，ImSDK只负责传回给回调函数cb，不做任何处理

返回

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

获取消息扩展示例

json::Object json_parameters;
json_parameters[kTIMMsgGetMsgListParamIsRamble] = true;
json_parameters[kTIMMsgGetMsgListParamIsForward] = false;
json_parameters[kTIMMsgGetMsgListParamCount] = 1;

TIMMsgGetMsgList(GetGroupID().c_str(), kTIMConv_Group, json::Serialize(json_parameters).c_str(),
    [](int32_t code, const char* desc, const char* json_params, const void* user_data) {
        Printf("TIMMsgGetMsgList complete|code:%d|desc:%s|json_params:%s\n", code, desc, json_params);

        json::Array json_message_array = json::Deserialize(json_params).ToArray();
        if (json_message_array.size() > 0) {
            std::string json_message = json::Serialize(json_message_array[0]);

            TIMMsgGetMessageExtensions(json_message.c_str(),
                [](int32_t code, const char* desc, const char* json_param, const void* user_data) {
                if (ERR_SUCC != code) {
                    // 获取消息扩展失败
                    return;
                }
                // 获取消息扩展成功
                Printf("TIMMsgGetMessageExtensions complete|code:%d|desc:%s|json_param:%s\n", code, desc, json_param);
                }, user_data);
        }
}, nullptr);

TIMMsgDeleteMessageExtensions()

TIM_API int TIMMsgDeleteMessageExtensions	(	const char *	json_msg,
		const char *	json_extension_key_array,
		TIMCommCallback	cb,
		const void *	user_data
	)

5.18 删除消息扩展（6.7 及其以上版本支持，需要您购买旗舰版套餐）

参数

json_msg	消息 json 字符串, Json Key 请参考 Message
json_extension_key_array	扩展信息 key 列表，单次最大支持删除 20 个消息扩展，如果设置为空，表示删除消息所有扩展
cb	成功与否的回调。回调函数定义请参考 TIMCommCallback
user_data	用户自定义数据，ImSDK只负责传回给回调函数cb，不做任何处理

返回

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

注意

• 当多个用户同时设置或删除同一个扩展 key 时，只有第一个用户可以执行成功，其它用户会收到 23001 错误码和最新的扩展信息，在收到错误码和扩展信息后，请按需重新发起删除操作。

删除消息扩展示例

json::Object json_parameters;
json_parameters[kTIMMsgGetMsgListParamIsRamble] = true;
json_parameters[kTIMMsgGetMsgListParamIsForward] = false;
json_parameters[kTIMMsgGetMsgListParamCount] = 1;

TIMMsgGetMsgList(GetGroupID().c_str(), kTIMConv_Group, json::Serialize(json_parameters).c_str(),
    [](int32_t code, const char* desc, const char* json_params, const void* user_data) {
        Printf("TIMMsgGetMsgList complete|code:%d|desc:%s|json_params:%s\n", code, desc, json_params);

        json::Array json_message_array = json::Deserialize(json_params).ToArray();
        if (json_message_array.size() > 0) {
            std::string json_message = json::Serialize(json_message_array[0]);

            // 设置要删除的消息扩展字段（只需要包含 要删除的 key 值即可，如果传入为空，则将消息扩展字段全部删除）
            json::Array json_extension_key_array;
            json_extension_key_array.push_back("extension_key");
            std::string json_extension_keys = json::Serialize(json_extension_key_array);

            // 删除消息扩展
            TIMMsgDeleteMessageExtensions(json_message.c_str(), json_extension_keys.c_str(),
                [](int32_t code, const char* desc, const char* json_param, const void* user_data) {
                    if (ERR_SUCC != code) {
                        // 删除消息扩展失败
                        return;
                    }
                    // 删除消息扩展成功
                    Printf("TIMMsgDeleteMessageExtensions complete|code:%d|desc:%s|json_param:%s\n", code, desc, json_param);
                }, user_data);
        }
}, nullptr);

TIMMsgAddMessageReaction()

TIM_API int TIMMsgAddMessageReaction	(	const char *	json_msg,
		const char *	reaction_id,
		TIMCommCallback	cb,
		const void *	user_data
	)

5.19 添加消息回应（可以用于实现表情回应，7.4 及其以上版本支持，需要您购买旗舰版套餐）

表情回应功能是指对某条消息通过表情符号进行互动回应，我们可以看到每种表情的回应人数和回应人列表。

目前常见的消息回应展示方式会有如下两种风格：

风格一：

-------------------------—

| lucy, happy birthday! |

-------------------------—

| 😄 1 💐 2 👍🏻 10 |

-------------------------—

风格二：

---------------------------------------------—

| lucy, happy birthday! |

---------------------------------------------—

| 😁 bob 💐olivia 🎂david |

| 👍🏻 denny、james、lucy、linda、thomas 等10人 |

---------------------------------------------—

当用户点击某个表情后，会跳转到表情回应详情界面：

| 😄 | 💐 | 👍🏻 |

| bob | olivia | lucy |

| ... | ... | denny |

| ... | ... | ... |

用户可以根据某个表情分页拉取使用该表情的用户信息。

您可以基于 SDK API 实现表情回应能力:

1、调用 TIMMsgAddMessageReaction 接口为一条消息添加一个 emoji，添加成功后，emoji 下就会存储当前操作用户。

2、调用 TIMMsgRemoveMessageReaction 接口删除已经添加的 emoji，删除成功后，emoji 下就不再存储当前操作用户。

3、调用 TIMMsgGetMessageReactions 接口批量拉取多条消息的 emoji 列表，其中每个 emoji 都包含了当前使用者总人数以及前 N（默认 10）个使用者用户资料。

4、调用 TIMMsgGetAllUserListOfMessageReaction 接口分页拉取消息 emoji 的全量使用者用户资料。

5、监听 TIMMsgReactionsChangedCallback 回调，感知 emoji 的使用者信息变更，该回调会携带 emoji 最新的使用者信息（包含使用者总人数以及前 N 个使用者用户资料）。

参数

json_msg	消息 json 字符串, Json Key 请参考 Message
reaction_id	消息回应 ID，在表情回应场景，reaction_id 为表情 ID，单条消息最大支持 10 个 Reaction，单个 Reaction 最大支持 100 个用户。

注意

• 该功能为旗舰版功能，需要您购买旗舰版套餐。
• 如果单条消息 Reaction 数量超过最大限制，调用接口会报 ERR_SVR_MSG_REACTION_COUNT_LIMIT 错误。
• 如果单个 Reaction 用户数量超过最大限制，调用接口会报 ERR_SVR_MSG_REACTION_USER_COUNT_LIMIT 错误。
• 如果 Reaction 已经包含当前用户，调用接口会报 ERR_SVR_MSG_REACTION_ALREADY_CONTAIN_USER 错误。

添加消息回应示例

std::string reaction_id = "emoji1";
TIMMsgAddMessageReaction(json_msg, reaction_id.c_str(),
    [](int32_t code, const char* desc, const char* json_param, const void* user_data) {
    Printf("TIMMsgAddMessageReaction complete|code:%d|desc:%s|json_param:%s\n", code, desc, json_param);
}, user_data);

TIMMsgRemoveMessageReaction()

TIM_API int TIMMsgRemoveMessageReaction	(	const char *	json_msg,
		const char *	reaction_id,
		TIMCommCallback	cb,
		const void *	user_data
	)

5.20 删除消息回应（7.4 及其以上版本支持，需要您购买旗舰版套餐）

参数

json_msg	消息 json 字符串, Json Key 请参考 Message
reaction_id	消息回应 ID，在表情回复场景，reaction_id 为表情 ID。

注意

• 如果 Reaction 不存在，调用接口会报 ERR_SVR_MSG_REACTION_NOT_EXISTS 错误。
• 如果 Reaction 不包含当前用户，调用接口会报 ERR_SVR_MSG_REACTION_NOT_CONTAIN_USER 错误。

删除消息回应示例

std::string reaction_id = "emoji1";
TIMMsgRemoveMessageReaction(json_msg, reaction_id.c_str(),
    [](int32_t code, const char* desc, const char* json_param, const void* user_data) {
       Printf("TIMMsgRemoveMessageReaction complete|code:%d|desc:%s|json_param:%s\n", code, desc, json_param);
}, user_data);

TIMMsgGetMessageReactions()

TIM_API int TIMMsgGetMessageReactions	(	const char *	json_msg_array,
		uint32_t	max_user_count_per_reaction,
		TIMCommCallback	cb,
		const void *	user_data
	)

5.21 批量拉取多条消息回应信息（7.4 及其以上版本支持，需要您购买旗舰版套餐）

参数

json_msg_array	消息列表, Json Key 请参考 Message。一次最大支持 20 条消息，消息必须属于同一个会话。
max_user_count_per_reaction	取值范围 [0,10]，每个 Reaction 最多只返回前 10 个用户信息，如需更多用户信息，可以按需调用 TIMMsgGetMessageReactionUserList 接口分页拉取。

批量拉取消息回应列表示例

json::Array json_msg_array;
json_msg_array.push_back(json_msg);
std::string json_msg_array_str = json::Serialize(json_msg_array);
TIMMsgGetMessageReactions(json_msg_array_str.c_str(), 10,
    [](int32_t code, const char* desc, const char* json_param, const void* user_data) {
       Printf("TIMMsgGetMessageReactions complete|code:%d|desc:%s|json_param:%s\n", code, desc, json_param);
}, user_data);

TIMMsgGetAllUserListOfMessageReaction()

TIM_API int TIMMsgGetAllUserListOfMessageReaction	(	const char *	json_msg,
		const char *	reaction_id,
		uint32_t	next_seq,
		uint32_t	count,
		TIMCommCallback	cb,
		const void *	user_data
	)

5.22 分页拉取使用指定消息回应用户信息（7.4 及其以上版本支持，需要您购买旗舰版套餐）

参数

json_msg	消息 json 字符串, Json Key 请参考 Message
reaction_id	消息回应 ID，在表情回复场景，reaction_id 为表情 ID。
next_seq	分页拉取的游标，第一次传 0，后续分页传 succ 返回的 nextSeq。
count	一次分页最大拉取个数，最大支持 100 个。

拉取消息回应用户列表示例

   TIMMsgGetAllUserListOfMessageReaction(json_msg, reaction_id.c_str(), 0, 20,
       [](int32_t code, const char* desc, const char* json_param, const void* user_data) {
Printf("TIMMsgGetAllUserListOfMessageReaction complete|code:%d|desc:%s|json_param:%s\n", code, desc, json_param); *  }, user_data);

TIMMsgTranslateText()

TIM_API int TIMMsgTranslateText	(	const char *	json_source_text_array,
		const char *	source_language,
		const char *	target_language,
		TIMCommCallback	cb,
		const void *	user_data
	)

5.23 翻译文本消息

参数

json_source_text_array	待翻译文本数组。
source_language	源语言。可以设置为特定语言或 ”auto“。“auto“ 表示自动识别源语言。传空默认为 ”auto“。
target_language	目标语言。支持的目标语言有多种，例如：英语-“en“，简体中文-”zh“，法语-”fr“，德语-”de“等。详情请参考文档 文本翻译语言支持。
cb	翻译结果的回调。回调函数定义和参数解析请参考 TIMCommCallback。

返回

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

示例

json::Array json_source_text_array;
json_source_text_array.push_back("send text");
json_source_text_array.push_back("translate text test");

std::string source_language = "";
std::string target_language = "de";

TIMMsgTranslateText(json::Serialize(json_source_text_array).c_str(), source_language.c_str(), target_language.c_str(),
    [](int32_t code, const char* desc, const char* json_param, const void* user_data) {
        Printf("\nTIMMsgTranslateText complete|code:%d|desc:%s|json_param:%s\n",
            code, desc, json_param);
    }, nullptr);

TIMMsgConvertVoiceToText()

TIM_API int TIMMsgConvertVoiceToText	(	const char *	url,
		const char *	language,
		TIMCommCallback	cb,
		const void *	user_data
	)

5.24 识别语音消息，将语音转换成文字（7.4 及以上版本支持）

参数

url	语音消息下载 url，可在消息对象中获取到。
language	识别的语言。
cb	识别结果的回调。回调函数定义和参数解析请参考 TIMCommCallback。

返回

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

注意

• 语音转文字是增值付费功能，处于内测阶段，您可通过 即时通信 IM 语音转文字插件交流群 联系我们为您开通体验完整功能。

示例

std::string language = "en";

TIMMsgConvertVoiceToText(language.c_str(),
    [](int32_t code, const char* desc, const char* json_param, const void* user_data) {
        Printf("\nTIMMsgConvertVoiceToText complete|code:%d|desc:%s|json_param:%s\n",
            code, desc, json_param);
    }, nullptr);

TIMPinGroupMessage()

TIM_API int TIMPinGroupMessage	(	const char *	group_id,
		const char *	json_msg,
		bool	is_pinned,
		TIMCommCallback	cb,
		const void *	user_data
	)

5.25 设置群消息置顶（7.9 及以上版本支持，需要您购买旗舰版套餐）

参数

group_id	群 ID
is_pinned	是否置顶
json_msg	消息 json 字符串, Json Key 请参考 Message
cb	根据消息 messageID 查询本地的消息列表成功与否的回调。回调函数定义和参数解析请参考 TIMCommCallback
user_data	用户自定义数据，ImSDK只负责传回给回调函数cb，不做任何处理

返回

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

注意

• 最多支持置顶10条消息。
• 如果置顶消息数量超出限制， sdk会返回错误码10070。

添加消息回应示例

TIMPinGroupMessage(GetGroupID().c_str(), json_msg, isPinned,
    [](int32_t code, const char* desc, const char* json_param, const void* user_data) {
    Printf("TIMPinGroupMessage complete|code:%d|desc:%s|json_param:%s\n", code, desc, json_param);
}, nullptr);

TIMGetPinnedGroupMessageList()

TIM_API int TIMGetPinnedGroupMessageList	(	const char *	group_id,
		TIMCommCallback	cb,
		const void *	user_data
	)

5.26 获取已置顶的群消息列表（7.9 及以上版本支持，需要您购买旗舰版套餐）

参数

group_id	群 ID
cb	根据消息 messageID 查询本地的消息列表成功与否的回调。回调函数定义和参数解析请参考 TIMCommCallback
user_data	用户自定义数据，ImSDK只负责传回给回调函数cb，不做任何处理

返回

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

注意

• 此接口用于获取置顶消息列表，如果置顶消息已过期不会返回

示例

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