Conversations

The IM SDK supports the following two types of conversations:

• 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.

Prototype

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

Parameters

Return values

• 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 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

Return values

This API is used to delete a conversation. Whether a conversion 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

Return values

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

Return values

Conversation drafts are usually used to save entered but not sent messages.

Example

Json::Value json_value_text;  // Constructs 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; // Constructs 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

Return values