Conversion APIs

Last updated: 2021-12-29 16:39:53

    Two types of Conversation are available:

    • C2C conversation: a one-to-one chat between you and another user. Messages are read and sent through the conversation.
    • Group conversation: a group chat among group members. All group members can receive messages sent in the group conversation.

    TIMConvCreate

    This API is used to create a conversation. (This API is to be disused. The IM SDK will automatically create conversations for message sending and receiving. No manual creation is required.)

    Prototype

    TIM_DECL int TIMConvCreate(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 conversation creation. 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:

    • A conversation is a one-to-one or group chat, through which messages are sent and received between you and another user or in a group.
    • This API creates a conversation or obtains conversation information. The conversation type (group or one-to-one chat) and the conversation party identifier (the conversation party's account or group ID) need to be specified. Conversation information is returned through the callback function cb.

    Example 1: obtaining a one-to-one chat with a party whose UserID is Windows-02

    const void* user_data = nullptr; // Returned by the callback function
    const char* userid = "Windows-02";
    int ret = TIMConvCreate(userid, kTIMConv_C2C, [](int32_t code, const char* desc, const char* json_param, const void* user_data) {
      if (ERR_SUCC != code) {
          return;
      }
      // The callback returns detailed information about the conversation
    }, user_data);
    if (ret != TIM_SUCC) {
      // Failed to call the `TIMConvCreate` API
    }
    

    Example 2: obtaining a group chat with the group ID set to Windows-Group-01

    const void* user_data = nullptr; // Returned by the callback function
    const char* userid = "Windows-Group-01";
    int ret = TIMConvCreate(userid, kTIMConv_Group, [](int32_t code, const char* desc, const char* json_param, const void* user_data) {
      if (ERR_SUCC != code) {
          return;
      }
      // The callback returns detailed information about the conversation
    }, user_data);
    if (ret != TIM_SUCC) {
      // Failed to call the `TIMConvCreate` API
    }
    

    TIMConvDelete

    This API is used to delete a conversation.

    Prototype

    TIM_DECL int TIMConvDelete(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 a conversation is 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 is used to delete a conversation. Whether a conversation is successfully deleted is returned through the callback.

    TIMConvGetConvList

    This API is used to obtain the conversation list of recent contacts.

    Prototype

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

    Parameters

    Parameter Type Description
    cb TIMCommCallback Callback function for obtaining the conversation list of recent contacts. 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.

    TIMConvGetConvInfo

    This API is used to query the list of conversations.

    Prototype

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

    Parameters

    Parameter Type Description
    json_get_conv_list_param const char* List of conversation IDs and types.
    cb TIMCommCallback Callback function for obtaining the conversation list. 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::Object json_obj;
    json_obj[kTIMGetConversationListParamConvId] = "98826";
    json_obj[kTIMGetConversationListParamConvType] = kTIMConv_C2C;
    Json::Array json_arry;
    json_arry.append(json_obj);
    TIMConvGetConvInfo(json_arry.toStyledString().c_str(),
     [](int32_t code, const char* desc, const char* json_param, const void* user_data) {
     printf("TIMConvGetConvInfo|code:%d|desc:%s\n", code, desc);
    }, nullptr);
    // Example of `json_params`. For details, see [ConvInfo](TIMCloudDef.h).
    [{
    "conv_active_time": 5,
    "conv_id": "98826",
    "conv_is_has_draft": false,
    "conv_is_has_lastmsg": true,
    "conv_is_pinned": false,
    "conv_last_msg": {
        "message_client_time": 1620877708,
        "message_conv_id": "98826",
        "message_conv_type": 1,
        "message_custom_int": 0,
        "message_custom_str": "",
        "message_elem_array": [{
            "elem_type": 0,
            "text_elem_content": "11111"
    }],
        "message_is_from_self": false,
        "message_is_online_msg": false,
        "message_is_peer_read": false,
        "message_is_read": false,
        "message_msg_id": "144115233874815003-1620877708-1038050731",
        "message_platform": 0,
        "message_priority": 1,
        "message_rand": 1038050731,
        "message_sender": "98826",
        "message_sender_profile": {
            "user_profile_add_permission": 1,
            "user_profile_birthday": 0,
            "user_profile_custom_string_array": [],
            "user_profile_face_url": "test1-www.google.com",
            "user_profile_gender": 0,
            "user_profile_identifier": "98826",
            "user_profile_language": 0,
            "user_profile_level": 0,
            "user_profile_location": "",
            "user_profile_nick_name": "test change8888",
            "user_profile_role": 0,
            "user_profile_self_signature": ""
        },
        "message_seq": 15840,
        "message_server_time": 1620877708,
        "message_status": 2,
        "message_unique_id": 6961616747713488299
     },
     "conv_type": 1,
     "conv_unread_num": 1
    }]
    

    TIMConvSetDraft

    This API is used to set the draft of a specified conversation.

    Prototype

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

    Parameters

    Parameter Type Description
    conv_id const char* Conversation ID.
    conv_type enum TIMConvType Conversation type. For more information, see TIMConvType.
    json_draft_param const char* JSON string of the set draft.

    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:

    Conversation drafts are usually used to save entered messages that have not been sent.

    Example

    Json::Value json_value_text;  // Construct a message
    json_value_text[kTIMElemType] = kTIMElem_Text;
    json_value_text[kTIMTextElemContent] = "this draft";
    Json::Value json_value_msg;
    json_value_msg[kTIMMsgElemArray].append(json_value_text);
    Json::Value json_value_draft; // Construct a draft
    json_value_draft[kTIMDraftEditTime] = time(NULL);
    json_value_draft[kTIMDraftUserDefine] = "this is userdefine";
    json_value_draft[kTIMDraftMsg] = json_value_msg;
    if (TIM_SUCC != TIMConvSetDraft(userid.c_str(), TIMConvType::kTIMConv_C2C, json_value_draft.toStyledString().c_str())) {
      // Failed to call the `TIMConvSetDraft` API
    } 
    // The `json_draft_param` JSON string obtained by `json_value_draft.toStyledString().c_str()` is as follows:
    {
     "draft_edit_time" : 1551271429,
     "draft_msg" : {
        "message_elem_array" : [
           {
              "elem_type" : 0,
              "text_elem_content" : "this draft"
           }
        ]
     },
     "draft_user_define" : "this is userdefine"
    }
    

    TIMConvCancelDraft

    This API is used to delete the draft of a specified conversation.

    Prototype

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

    Parameters

    Parameter Type Description
    conv_id const char* Conversation ID.
    conv_type enum TIMConvType Conversation type. For more information, see TIMConvType.

    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.

    TIMConvPinConversation

    This API is used to pin a conversation to the top.

    Prototype

    TIM_DECL int TIMConvPinConversation(const char* conv_id, TIMConvType conv_type, bool is_pinned, 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.
    is_pinned bool Whether to pin the conversation to the top.
    cb TIMCommCallback Callback function for pinning the conversation to the top. 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

    // The return value of `json_param` is an empty string, and you only need to check `code` to determine the result.
    TIMConvPinConversation(
       [](int32_t code, const char* desc, const char* json_param, const void* user_data) {
       printf("TIMConvPinConversation|code:%d|desc:%s\n", code, desc);
    }, nullptr);
    

    TIMConvGetTotalUnreadMessageCount

    This API is used to obtain the total unread message count of all conversations.

    Prototype

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

    Parameters

    Parameter Type Description
    cb TIMCommCallback Callback function for obtaining the total unread message count of all conversations. 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

    TIMConvGetTotalUnreadMessageCount(
      [](int32_t code, const char* desc, const char* json_param, const void* user_data) {
      printf("TIMConvGetTotalUnreadMessageCount|code:%d|desc:%s\n", code, desc);
    }, nullptr);
    // Example of `json_param`. For details on JSON keys, see [GetTotalUnreadNumberResult](TIMCloudDef.h).
    // {"conv_get_total_unread_message_count_result_unread_count":4}