tencent cloud

For more information about messages, see One-to-One Message, Group Message, and Message Formats.

TIMMsgSendMessage

This API is used to send a new message.

Prototype

TIM_DECL 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);

Parameters

Parameter	Type	Description
conv_id	const char*	Conversation ID.
conv_type	enum TIMConvType	Conversation type. For more information, see TIMConvType.
json_msg_param	const char*	JSON string of the message.
cb	TIMCommCallback	Callback function for indicating whether the new message is sent. For more information about the callback function definition, see TIMCommCallback.
user_data	const void*	User-defined data. The IM SDK only transfers the user data to the callback function cb without processing the data.

Return values

Type	Description
int	If TIM_SUCC is returned, the API was called successfully. If other values are returned, the API failed to be called. For more information about the definition of each return value, see TIMResult.

Note：

• This API is used to send a new one-to-one or group chat message.
• When this API is used to send a one-to-one message, conv_id is set to UserID of the peer party, and conv_type is set to kTIMConv_C2C.
• When this API is used to send a group message, conv_id is set to the group ID, and conv_type is set to kTIMConv_Group.
• When a message is sent, kTIMElem_GroupTips and kTIMElem_GroupReport cannot be sent. They are delivered by the backend to update or notify the group information. The following elements in the message can be sent:
• Text message element (TextElem)
• Emoji message element (FaceElem)
• Location message element (LocationElem)
• Image message element (ImageElem)
• Voice message element (SoundElem)
• Custom message element (CustomElem)
• File message element (FileElem)
• Video message element (VideoElem)

Example

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);
json_value_msg[kTIMMsgSender] = login_id;
json_value_msg[kTIMMsgClientTime] = time(NULL);
json_value_msg[kTIMMsgServerTime] = time(NULL);
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) {
      // The message failed to be sent
      return;
  }
  // The message was sent successfully
}, nullptr);
// The `json_msg_param` JSON string obtained by `json_value_msg.toStyledString().c_str()` is as follows:
{
 "message_id" : "14400111550110000_1551446728_45598731"
 "message_client_time" : 1551446728,
 "message_elem_array" : [
    {
       "elem_type" : 0,
       "text_elem_content" : "send text"
    }
 ],
 "message_sender" : "user1",
 "message_server_time" : 1551446728
}

TIMMsgSendNewMsg

This API is used to send a new message. (This API is to be disused. Please use the TIMMsgSendMessage API.)

Prototype

TIM_DECL int TIMMsgSendNewMsg(const char* conv_id, enum TIMConvType conv_type, const char* json_msg_param, TIMCommCallback cb, const void* user_data);

Parameters

Parameter	Type	Description
conv_id	const char*	Conversation ID.
conv_type	enum TIMConvType	Conversation type. For more information, see TIMConvType.
json_msg_param	const char*	JSON string of the message.
cb	TIMCommCallback	Callback function for indicating whether the new message is sent. For more information about the callback function definition, see TIMCommCallback.
user_data	const void*	User-defined data. The IM SDK only transfers the user data to the callback function cb without processing the data.

Return values

Type	Description
int	If TIM_SUCC is returned, the API was successfully called. (The callback cb is called only when the API returns TIM_SUCC.) If other values are returned, the API failed to be called. For more information about the definition of each return value, see TIMResult.

Note：

• This API is used to send a new one-to-one or group chat message.
• When this API is used to send a one-to-one message, conv_id is set to UserID of the peer party, and conv_type is set to kTIMConv_C2C.
• When this API is used to send a group message, conv_id is set to the group ID, and conv_type is set to kTIMConv_Group.
• When a message is sent, kTIMElem_GroupTips and kTIMElem_GroupReport cannot be sent. They are delivered by the backend to update or notify the group information. The following elements in the message can be sent:
• Text message element (TextElem)
• Emoji message element (FaceElem)
• Location message element (LocationElem)
• Image message element (ImageElem)
• Voice message element (SoundElem)
• Custom message element (CustomElem)
• File message element (FileElem)
• Video message element (VideoElem)

Example

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);
json_value_msg[kTIMMsgSender] = login_id;
json_value_msg[kTIMMsgClientTime] = time(NULL);
json_value_msg[kTIMMsgServerTime] = time(NULL);
int ret = TIMMsgSendNewMsg(conv_id.c_str(), 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) {
      // The message failed to be sent
      return;
  }
  // The message was sent successfully
}, this);
// The `json_msg_param` JSON string obtained by `json_value_msg.toStyledString().c_str()` is as follows:
{
 "message_client_time" : 1551446728,
 "message_elem_array" : [
    {
       "elem_type" : 0,
       "text_elem_content" : "send text"
    }
 ],
 "message_sender" : "user1",
 "message_server_time" : 1551446728
}

TIMMsgCancelSend

This API is used to cancel a message being sent based on messageID.

Prototype

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

Parameters

Parameter	Type	Description
conv_id	const char*	Conversation ID.
conv_type	enum TIMConvType	Conversation type. For more information, see TIMConvType.
message_id	const char*	Message ID.
cb	TIMCommCallback	Callback function for cancelling a message being sent. For more information about the callback function definition, see TIMCommCallback.
user_data	const void*	User-defined data. The IM SDK only transfers the user data to the callback function cb without processing the data.

Return values

Type	Description
int	If TIM_SUCC is returned, the API was called successfully. If other values are returned, the API failed to be called. For more information about the definition of each return value, see TIMResult.

Example

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

TIMMsgFindMessages

This API is used to query local messages by messageID.

Prototype

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

Parameters

Parameter	Type	Description
json_message_id_array	const char*	List of message IDs.
cb	TIMCommCallback	Callback function for indicating whether the exact search of messages cached locally is successful. For more information about the callback function definition, see TIMCommCallback.
user_data	const void*	User-defined data. The IM SDK only transfers the user data to the callback function cb without processing the data.

Return values

Type	Description
int	If TIM_SUCC is returned, the API was called successfully. If other values are returned, the API failed to be called. For more information about the definition of each return value, see TIMResult.

Example

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);
// The `json_message_id_array` JSON string obtained by `json_message_id_array.toStyledString().c_str()` is as follows:
[
 "id_clienttime_rand_1",
 "id_clienttime_rand_2",
]

TIMMsgReportReaded

This API is used to report that a message has been read.

Prototype

TIM_DECL int TIMMsgReportReaded(const char* conv_id, enum TIMConvType conv_type, const char* json_msg_param, TIMCommCallback cb, const void* user_data);

Parameters

Parameter	Type	Description
conv_id	const char*	Conversation ID. Starting from v5.8, if conv_id is set to the NULL string pointer or the null string "", conv_type indicates that all one-to-one or group messages are read.
conv_type	enum TIMConvType	Conversation type. For more information, see TIMConvType.
json_msg_param	const char*	JSON string of the message.
cb	TIMCommCallback	Callback function for notifying whether the message read state is reported. For more information about the callback function definition, see TIMCommCallback.
user_data	const void*	User-defined data. The IM SDK only transfers the user data to the callback function cb without processing the data.

Return values

Type	Description
int	If TIM_SUCC is returned, the API was successfully called. (The callback cb is called only when the API returns TIM_SUCC.) If other values are returned, the API failed to be called. For more information about the definition of each return value, see TIMResult.

Note：

json_msg_param can be set to the NULL string pointer or the null string "". In that case, the timestamp of the latest message (if any) in the conversation or the current time is used as the read timestamp for reporting. If a message needs to be specified, the timestamp of this specified message is used as the read timestamp for reporting. We recommend that the message JSON content in the message array obtained from the received new message or the message JSON content located by the message locator be used to avoid repeated construction of the message JSON content.

TIMMsgMarkAllMessageAsRead

This API is used to mark all messages as read. (This API is supported from v5.8.)

Prototype

TIM_DECL int TIMMsgMarkAllMessageAsRead(TIMCommCallback cb, const void* user_data);

Parameters

Parameter	Type	Description
cb	TIMCommCallback	Callback function for indicating whether all messages are marked as read. For more information about the callback function definition, see TIMCommCallback.
user_data	const void*	User-defined data. The IM SDK only transfers the user data to the callback function cb without processing the data.

Return values

Type	Description
int	If TIM_SUCC is returned, the API was called successfully. If other values are returned, the API failed to be called. For more information about the definition of each return value, see TIMResult.

TIMMsgRevoke

This API is used to recall a message.

Prototype

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

Parameters

Parameter	Type	Description
conv_id	const char*	Conversation ID.
conv_type	enum TIMConvType	Conversation type. For more information, see TIMConvType.
json_msg_param	const char*	JSON string of the message.
cb	TIMCommCallback	Callback function for indicating whether the message is recalled. For more information about the callback function definition, see TIMCommCallback.
user_data	const void*	User-defined data. The IM SDK only transfers the user data to the callback function cb without processing the data.

Return values

Type	Description
int	If TIM_SUCC is returned, the API was successfully called. (The callback cb is called only when the API returns TIM_SUCC.) If other values are returned, the API failed to be called. For more information about the definition of each return value, see TIMResult.

Note：

This API is used to recall a message. The stored message JSON content or the message JSON content located by the message locator is used to avoid repeated construction of the message JSON content.

Example

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) {
      // The message failed to be sent
      return;
  }
  // The message was successfully sent. `json_param` returns the message JSON string after the message is sent.
  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) {
          // The message failed to be recalled
          return;
      }
      // The message was successfully recalled
   }, user_data);
}, this);

TIMMsgFindByMsgLocatorList

This API is used to accurately locate a message of the specified conversation by using the message locator.

Prototype

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

Parameters

Parameter	Type	Description
conv_id	const char*	Conversation ID.
conv_type	enum TIMConvType	Conversation type. For more information, see TIMConvType.
json_msg_Locator_array	const char*	Message locator array.
cb	TIMCommCallback	Callback function for indicating whether a message of the specified conversation is successfully and accurately located by the message locator. For more information about the callback definition and parameter parsing, see TIMCommCallback.
user_data	const void*	User-defined data. The IM SDK only transfers the user data to the callback function cb without processing the data.

Return values

Type	Description
int	If TIM_SUCC is returned, the API was successfully called. (The callback cb is called only when the API returns TIM_SUCC.) If other values are returned, the API failed to be called. For more information about the definition of each return value, see TIMResult.

Note：

• This API is used to accurately locate a message of the specified conversation by using the message locator. It is often used to search for a specified message upon message recall.
• One message locator corresponds to one message.

Example

Json::Value json_msg_locator;                      // One message locator corresponds to one message (accurate location)
json_msg_locator[kTIMMsgLocatorIsRevoked] = false; // Whether the message is recalled
json_msg_locator[kTIMMsgLocatorTime] = 123;        // Specifies the message time
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);
// The `json_msg_Locator_array` JSON string obtained by `json_msg_locators.toStyledString().c_str()` is as follows:
[
 {
    "message_locator_is_revoked" : false,
    "message_locator_is_self" : false,
    "message_locator_rand" : 12345678,
    "message_locator_seq" : 1,
    "message_locator_time" : 123
 }
]

TIMMsgImportMsgList

This API is used to import a message list to a specified conversation.

Prototype

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

Parameters

Parameter	Type	Description
conv_id	const char*	Conversation ID.
conv_type	enum TIMConvType	Conversation type. For more information, see TIMConvType.
json_msg_array	const char*	Message array.
cb	TIMCommCallback	Callback function for indicating whether the message list is imported to the specified conversation. For more information about the callback function definition, see TIMCommCallback.
user_data	const void*	User-defined data. The IM SDK only transfers the user data to the callback function cb without processing the data.

Return values

Type	Description
int	If TIM_SUCC is returned, the API was successfully called. (The callback cb is called only when the API returns TIM_SUCC.) If other values are returned, the API failed to be called. For more information about the definition of each return value, see TIMResult.

Note：

This API is used to import messages in batches. You can construct messages for importing. Alternatively, you can store the JSON string of the message array to be imported and call this API to import the JSON string, avoiding repeated construction of the message array.

Example

Json::Value json_value_elem; // Construct the message text element
json_value_elem[kTIMElemType] = TIMElemType::kTIMElem_Text;
json_value_elem[kTIMTextElemContent] = "this is import msg";
Json::Value json_value_msg; // Construct a message
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;  // Message array
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);
// The `json_msg_array` JSON string obtained by `json_value_msgs.toStyledString().c_str()` is as follows:
[
 {
    "message_client_time" : 1551446728,
    "message_elem_array" : [
       {
          "elem_type" : 0,
          "text_elem_content" : "this is import msg"
       }
    ],
    "message_sender" : "user1",
    "message_server_time" : 1551446728
 }
]

TIMMsgSaveMsg

This API is used to save a custom message.

Prototype

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

Parameters

Parameter	Type	Description
conv_id	const char*	Conversation ID.
conv_type	enum TIMConvType	Conversation type. For more information, see TIMConvType.
json_msg_param	const char*	JSON string of the message.
cb	TIMCommCallback	Callback function for indicating whether the custom message is saved. For more information about the callback function definition, see TIMCommCallback.
user_data	const void*	User-defined data. The IM SDK only transfers the user data to the callback function cb without processing the data.

Return values

Type	Description
int	If TIM_SUCC is returned, the API was successfully called. (The callback cb is called only when the API returns TIM_SUCC.) If other values are returned, the API failed to be called. For more information about the definition of each return value, see TIMResult.

Note：

This API is used to save a message. Generally, you can construct a message JSON string and save it to a specified conversation.

TIMMsgGetMsgList

This API is used to obtain the message list of a specified conversation.

Prototype

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

Parameters

Parameter	Type	Description
conv_id	const char*	Conversation ID.
conv_type	enum TIMConvType	Conversation type. For more information, see TIMConvType.
json_get_msg_param	const char*	Parameter for obtaining messages.
cb	TIMCommCallback	Callback function for indicating whether the message list of the specified conversation is obtained. For more information about the callback function definition and parameter parsing, see TIMCommCallback.
user_data	const void*	User-defined data. The IM SDK only transfers the user data to the callback function cb without processing the data.

Return values

Type	Description
int	If TIM_SUCC is returned, the API was successfully called. (The callback cb is called only when the API returns TIM_SUCC.) If other values are returned, the API failed to be called. For more information about the definition of each return value, see TIMResult.

Note：

• The kTIMMsgGetMsgListParamLastMsg parameter specifies the message as the start point for local message pulling. The kTIMMsgGetMsgListParamCount parameter specifies the number of messages to be pulled. kTIMMsgGetMsgListParamLastMsg is optional. If you do not specify kTIMMsgGetMsgListParamLastMsg, the newest message of the conversation will be used as the start point for local message pulling.

  • If you set kTIMMsgGetMsgListParamIsRamble to true, the roaming messages in the cloud will be pulled if the local messages are not enough.
  • If you set kTIMMsgGetMsgListParamIsForward to true, messages later than the message specified by kTIMMsgGetMsgListParamLastMsg will be pulled. If you set it to false, messages earlier than the message specified by kTIMMsgGetMsgListParamLastMsg will be pulled.

• When kTIMConv_C2C messages are pulled, only kTIMMsgGetMsgListParamLastMsg can be used to specify the start point for message pulling. If kTIMMsgGetMsgListParamLastMsg is not specified, the IM SDK uses the newest message of the conversation as the start point for message pulling.

• When kTIMConv_Group messages are pulled, kTIMMsgGetMsgListParamLastMsg or kTIMMsgGetMsgListParamLastMsgSeq can be used to specify the start point for message pulling:

• If kTIMMsgGetMsgListParamLastMsg is used to specify the start point for message pulling, the returned message list does not include the message specified by kTIMMsgGetMsgListParamLastMsg.

• If kTIMMsgGetMsgListParamLastMsgSeq is used to specify the start point for message pulling, the returned message list includes the message specified by kTIMMsgGetMsgListParamLastMsgSeq.

• When kTIMConv_Group messages are pulled:

• If both kTIMMsgGetMsgListParamLastMsg and kTIMMsgGetMsgListParamLastMsgSeq are specified, the IM SDK uses kTIMMsgGetMsgListParamLastMsg to determine the start point for message pulling.

• If both kTIMMsgGetMsgListParamLastMsg and kTIMMsgGetMsgListParamLastMsgSeq are not specified, there are two cases for the start point for message pulling:

• If the time range for message pulling is specified, the IM SDK uses the point in time specified by kTIMMsgGetMsgListParamTimeBegin as the start point for message pulling.

• If the time range for message pulling is not specified, the IM SDK uses the newest message of the conversation as the start point for message pulling.

Example: obtaining the Windows-02 message list of the C2C conversation

Json::Value json_msg(Json::objectValue); // Construct a 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);
// The `json_get_msg_param` JSON string obtained by `json_get_msg_param.toStyledString().c_str()` is as follows:
{
 "msg_getmsglist_param_count" : 100,
 "msg_getmsglist_param_is_forward" : true,
 "msg_getmsglist_param_is_remble" : false,
 "msg_getmsglist_param_last_msg" : {}
}

TIMMsgDelete

This API is used to delete messages of a specified conversation.

Prototype

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

Parameters

Parameter	Type	Description
conv_id	const char*	Conversation ID.
conv_type	enum TIMConvType	Conversation type. For more information, see TIMConvType.
json_msgdel_param	const char*	Parameter for obtaining messages.
cb	TIMCommCallback	Callback function for indicating whether messages of the specified conversation are deleted. For more information about the callback function definition, see TIMCommCallback.
user_data	const void*	User-defined data. The IM SDK only transfers the user data to the callback function cb without processing the data.

Return values

Type	Description
int	If TIM_SUCC is returned, the API was successfully called. (The callback cb is called only when the API returns TIM_SUCC.) If other values are returned, the API failed to be called. For more information about the definition of each return value, see TIMResult.

Example

Json::Value json_value_msg(Json::objectValue);
Json::Value json_value_msgdelete;
json_value_msgdelete[kTIMMsgDeleteParamIsRamble] = false;
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);
// The `json_msgdel_param` JSON string obtained by `json_value_msgdelete.toStyledString().c_str()` is as follows:
{
"msg_delete_param_is_remble" : false,
"msg_delete_param_msg" : {}
}

TIMMsgListDelete

This API is used to delete the local and roaming messages of a specified conversation.

Prototype

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

Parameters

Parameter	Type	Description
conv_id	const char*	Conversation ID.
conv_type	enum TIMConvType	Conversation type. For more information, see TIMConvType.
json_msg_array	const char*	Message array.
cb	TIMCommCallback	Callback function for indicating whether messages of the specified conversation are deleted. For more information about the callback function definition, see TIMCommCallback.
user_data	const void*	User-defined data. The IM SDK only transfers the user data to the callback function cb without processing the data.

Return values

Type	Description
int	If TIM_SUCC is returned, the API was successfully called. (The callback cb is called only when the API returns TIM_SUCC.) If other values are returned, the API failed to be called. For more information about the definition of each return value, see TIMResult.

Note：

• This API deletes both local and roaming messages. Pay attention to the following:

• We recommend that you store the JSON string of the message array and then call this API to delete the messages, avoiding repeated construction of the message array.

• Up to 30 messages can be deleted at a time.

• This API can be called only once per second.

• If the account has pulled these messages from other devices, the messages will still be stored on those devices after this API is called to delete them. That is, the operation of message deletion cannot be synchronized across multiple devices.

Example

Json::Value json_value_elem; // Construct the message text element
json_value_elem[kTIMElemType] = TIMElemType::kTIMElem_Text;
json_value_elem[kTIMTextElemContent] = "this is import msg";
Json::Value json_value_msg; // Construct a message
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;  // Message array
json_value_msgs.append(json_value_msg);
TIMMsgListDelete("user2", kTIMConv_C2C, json_value_msgs.toStyledString().c_str(), [](int32_t code, const chardesc, const charjson_param, const voiduser_data) {
}, nullptr);
// The `json_msg_array` JSON string obtained by `json_value_msgs.toStyledString().c_str()` is as follows:
[
 {
    "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

This API is used to clear messages of a specified conversation.

Prototype

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

Parameters

Parameter	Type	Description
conv_id	const char*	Conversation ID.
conv_type	enum TIMConvType	Conversation type. For more information, see TIMConvType.
cb	TIMCommCallback	Callback function for indicating whether messages are cleared. For more information about the callback function definition, see TIMCommCallback.
user_data	const void*	User-defined data. The IM SDK only transfers the user data to the callback function cb without processing the data.

Return values

Type	Description
int	If TIM_SUCC is returned, the API was successfully called. (The callback cb is called only when the API returns TIM_SUCC.) If other values are returned, the API failed to be called. For more information about the definition of each return value, see TIMResult.

Example

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

TIMMsgSetC2CReceiveMessageOpt

This API is used to set the one-to-one message receiving option for specified users (batch setting supported).

Prototype

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

Parameters

Parameter	Type	Description
json_identifier_array	const char*	List of UserIDs.
opt	TIMReceiveMessageOpt	Message receiving option. For more information, see TIMReceiveMessageOpt.
conv_type	enum TIMConvType	Conversation type. For more information, see TIMConvType.
cb	TIMCommCallback	Callback function for indicating whether the one-to-one message receiving option is set. For more information about the callback function definition, see TIMCommCallback.
user_data	const void*	User-defined data. The IM SDK only transfers the user data to the callback function cb without processing the data.

Return values

Type	Description
int	If TIM_SUCC is returned, the API was successfully called. (The callback cb is called only when the API returns TIM_SUCC.) If other values are returned, the API failed to be called. For more information about the definition of each return value, see TIMResult.

Note：

• This API supports batch setting. You can use the userIDList field to specify up to 30 users for batch setting.
• This API can be called for up to 5 times per second.

Example

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

This API is used to query the one-to-one message receiving option for specified users.

Prototype

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

Parameters

Parameter	Type	Description
json_identifier_array	const char*	List of UserIDs.
conv_type	enum TIMConvType	Conversation type. For more information, see TIMConvType.
cb	TIMCommCallback	Query result callback function. For more information about the callback function definition, see TIMCommCallback.
user_data	const void*	User-defined data. The IM SDK only transfers the user data to the callback function cb without processing the data.

Return values

Type	Description
int	If TIM_SUCC is returned, the API was successfully called. (The callback cb is called only when the API returns TIM_SUCC.) If other values are returned, the API failed to be called. For more information about the definition of each return value, see TIMResult.

Example

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);
// Example of the callback `json_param`. For details on JSON keys, see [GetC2CRecvMsgOptResult](TIMCloudDef.h).
[
 {
    "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

This API is used to set the group message receiving option.

Prototype

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

Parameters

Parameter	Type	Description
group_id	const char*	Group ID.
opt	enum TIMReceiveMessageOpt	Message receiving option. For more information, see TIMReceiveMessageOpt.
conv_type	enum TIMConvType	Conversation type. For more information, see TIMConvType.
cb	TIMCommCallback	Callback function for indicating whether the one-to-one message receiving option is set. For more information about the callback function definition, see TIMCommCallback.
user_data	const void*	User-defined data. The IM SDK only transfers the user data to the callback function cb without processing the data.

Return values

Type	Description
int	If TIM_SUCC is returned, the API was successfully called. (The callback cb is called only when the API returns TIM_SUCC.) If other values are returned, the API failed to be called. For more information about the definition of each return value, see TIMResult.

Note：

• You can obtain the group message receiving option from the group profile GroupBaseInfo.

Example

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

TIMMsgDownloadElemToPath

This API is used to download message elements (including image, video, audio, and file) to a specified path.

Prototype

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

Parameters

Parameter	Type	Description
json_download_elem_param	const char*	JSON string of the download parameters.
path	const char*	Storage path of the downloaded file.
cb	TIMCommCallback	Callback function for indicating whether the download is successful and the download process. For more information about the callback function definition and parameter parsing, see TIMCommCallback.
user_data	const void*	User-defined data. The IM SDK only transfers the user data to the callback function cb without processing the data.

Return values

Type	Description
int	If TIM_SUCC is returned, the API was successfully called. (The callback cb is called only when the API returns TIM_SUCC.) If other values are returned, the API failed to be called. For more information about the definition of each return value, see TIMResult.

Note：

This API is used to download the image, file, audio, and video elements in messages. The download parameters, including kTIMMsgDownloadElemParamFlag, kTIMMsgDownloadElemParamId, kTIMMsgDownloadElemParamBusinessId, andkTIMMsgDownloadElemParamUrlcan be found in the corresponding elements.kTIMMsgDownloadElemParamType` indicates the download file type. For more information, see TIMDownloadType.

Example

Json::Value download_param;
download_param[kTIMMsgDownloadElemParamFlag] = flag;
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) {
}, this);

TIMMsgDownloadMergerMessage

This API is used to download a combined message.

Prototype

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

Parameters

Parameter	Type	Description
json_single_msg	const char*	JSON string of a combined message.
cb	TIMCommCallback	Callback function for indicating whether the download is successful and the download process. For more information about the callback function definition , see TIMCommCallback.
user_data	const void*	User-defined data. The IM SDK only transfers the user data to the callback function cb without processing the data.

Return values

Type	Description
int	If TIM_SUCC is returned, the API was successfully called. (The callback cb is called only when the API returns TIM_SUCC.) If other values are returned, the API failed to be called. For more information about the definition of each return value, see TIMResult.

Example

// Received a message (`json_single_msg`) 
TIMMsgDownloadMergerMessage(json_single_msg, [](int32_t code, const char* desc, const char* json_param, const void* user_data) {
}, this);

TIMMsgSearchLocalMessages

This API is used to search for local messages.

Prototype

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

Parameters

Parameter	Type	Description
json_search_message_param	const char*	Message search parameter.
cb	TIMCommCallback	Callback function for indicating whether the search is successful. For more information about the callback function definition, see TIMCommCallback.
user_data	const void*	User-defined data. The IM SDK only transfers the user data to the callback function cb without processing the data.

Return values

Type	Description
int	If TIM_SUCC is returned, the API was successfully called. (The callback cb is called only when the API returns TIM_SUCC.) If other values are returned, the API failed to be called. For more information about the definition of each return value, see TIMResult.

Example

// Received a message (`json_single_msg`) 
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);
// The `json_search_message_param` JSON string obtained by `json_search_message_param.toStyledString().c_str()` is as follows:
{
 "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
}

TIMMsgSetLocalCustomData

This API is used to set custom message data (saved locally, will not be sent to the peer end, and will become invalid after the app is uninstalled and reinstalled).

Prototype

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

Parameters

Parameter	Type	Description
json_msg_param	const char*	JSON string of the message.
cb	TIMCommCallback	Callback function for indicating whether the custom message is stored. For more information about the callback function definition, see TIMCommCallback.
user_data	const void*	User-defined data. The IM SDK only transfers the user data to the callback function cb without processing the data.

Return values

Type	Description
int	If TIM_SUCC is returned, the API was successfully called. (The callback cb is called only when the API returns TIM_SUCC.) If other values are returned, the API failed to be called. For more information about the definition of each return value, see TIMResult.

Example

// Received a message (`json_single_msg`) 
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] = "custom int";
          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);

TIMMsgBatchSend

This API is used to send messages in batches, but not to groups.

Prototype

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

Parameters

Parameter	Type	Description
json_batch_send_param	const char*	JSON string of batch sent messages.
cb	TIMCommCallback	Callback function for indicating whether the messages are batch sent successfully. For more information about the callback function definition and parameter parsing, see TIMCommCallback.
user_data	const void*	User-defined data. The IM SDK only transfers the user data to the callback function cb without processing the data.

Return values

Type	Description
int	If TIM_SUCC is returned, the API was successfully called. (The callback cb is called only when the API returns TIM_SUCC.) If other values are returned, the API failed to be called. For more information about the definition of each return value, see TIMResult.

Note：

This API is used to send messages in batches. The callback function cb returns whether the messages are sent to each UserID successfully.

Example

// Construct a text message element
Json::Value json_value_elem;
json_value_elem[kTIMElemType] = TIMElemType::kTIMElem_Text;
json_value_elem[kTIMTextElemContent] = "this is batch send msg";
// Construct a message
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);
// Construct an ID array list for batch sending
Json::Value json_value_ids(Json::arrayValue);
json_value_ids.append("user2");
json_value_ids.append("user3");
// Construct API parameters for batch sending
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);
// The `json_batch_send_param` JSON string obtained by `json_value_batchsend.toStyledString().c_str()` is as follows:
{
 "msg_batch_send_param_identifier_array" : [ "user2", "user3" ],
 "msg_batch_send_param_msg" : {
    "message_client_time" : 1551340614,
    "message_elem_array" : [
       {
          "elem_type" : 0,
          "text_elem_content" : "this is batch send msg"
       }
    ],
    "message_sender" : "user1",
    "message_server_time" : 1551340614
 }
}