Message APIs

Last updated: 2021-03-05 11:54:24

    For more information about messages, see One-to-One Chat Messages, Group Chat Messages, and Message Format Description.

    TIMMsgSendNewMsg

    This API is used to send a new message.

    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 a message.
    cb TIMCommCallback Callback function for notifying 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 chat 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 chat 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. For more information, see TextElem.
      • Emoji message element. For more information, see FaceElem.
      • Location message element. For more information, see LocationElem.
      • Image message element. For more information, see ImageElem.
      • Sound message element. For more information, see SoundElem.
      • Custom message element. For more information, see CustomElem.
      • File message element. For more information, see FileElem.
      • Video message element. For more information, see 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) {
            // Failed to send a message.
            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
    }

    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.
    conv_type enum TIMConvType Conversation type. For more information, see TIMConvType.
    json_msg_param const char* JSON string of a 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.