This document describes the usage of some basic features of the Tencent Cloud IM SDK to give you a better understanding of the basic processes of Instant Messaging (IM).

Initialization

Before using the SDK to perform IM operations, you need to initialize the SDK.
Example:

int sdk_app_id = 12345678;
std::string json_init_cfg;
Json::Value json_value_dev;
json_value_dev[kTIMDeviceInfoDevId] = "12345678";
json_value_dev[kTIMDeviceInfoPlatform] = TIMPlatform::kTIMPlatform_Windows;
json_value_dev[kTIMDeviceInfoDevType] = "";

Json::Value json_value_init;
json_value_init[kTIMSdkConfigLogFilePath] = path;
json_value_init[kTIMSdkConfigConfigFilePath] = path;
json_value_init[kTIMSdkConfigAccountType] = "107";
json_value_init[kTIMSdkConfigDeviceInfo] = json_value_dev;

TIMInit(sdk_app_id, json_value_init.toStyledString().c_str());

You can obtain the SDKAppID after creating an app in the IM console. For more information on initialization operations, see Initialization.

Login/Logout

Login

• Users can normally send and receive messages only after they have logged in to the Tencent backend server. To log in to the Tencent backend server, a user needs to provide information including UserID and UserSig. For more information, see Login Authentication.
  Login is an asynchronous process, and the result returned by the callback function indicates whether the login was successful. Users can proceed to subsequent operations only after successful login. When login succeeds or fails, the system will trigger the corresponding callback.

Example:

const void* user_data = nullptr; // Return of the callback function
const char* id = "WIN01"; 
const char* user_sig = "WIN01UserSig";
TIMLogin(id, user_sig, [](int32_t code, const char* desc, const char* json_param, const void* user_data) {
    if (code != ERR_SUCC) {
        // Failed to log in
        return;
    }
    // Logged in successfully

}, user_data);

Here, code indicates the error code and desc indicates error description. For more information, see Error Codes.

onForceOffline

If this user has been forced logout by another client, the login fails and returns the error code (ERR_IMSDK_KICKED_BY_OTHERS: 6208). If a user is forced logout, be sure to notify the user of this with a notification window such as an Alert window. For more information on forcible logout, see User State Changes.

onUserSigExpired
Every UserSig has an expiration time. When a UserSig expires, login returns error code 70001. If you receive this error code, request a new UserSig from your business server. For more information, see User Ticket Expiration.

Logout

The logout operation needs to be called if the user wants to log out or switch to another user.

Example:

const void* user_data = nullptr; // Return of the callback function
TIMLogout([](int32_t code, const char* desc, const char* json_param, const void* user_data) { 
    if (code != ERR_SUCC) { 
        // Failed to log out
        return;
    }
    // Logged out successfully

}, user_data);

When you need to switch to another account, login can be called again only after the logout callback succeeds or fails. Otherwise, login may fail.
For more information on login and logout operations, see Login and Logout.

Sending Messages

Obtaining conversations

A conversation refers to a conversation with a user or a group. To send or receive messages in a one-to-one or group conversation, you need to first obtain the conversation by specifying the conversation type (one-to-one chat or group chat) and the peer’s identifier (the peer’s account or group ID).

Example of obtaining the one-to-one conversation with a recipient whose UserID is Windows-02

const void* user_data = nullptr; // Return of 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) {
    // The callback returns details about the conversation.
}, user_data);
if (ret != TIM_SUCC) {
    // Failed to call the TIMConvCreate API
}

Example of obtaining the conversation with the group ID of Windows-Group-01

const void* user_data = nullptr; // Return of the callback function
const char* groupid = "Windows-Group-01";
int ret = TIMConvCreate(groupid, kTIMConv_Group, [](int32_t code, const char* desc, const char* json_param, const void* user_data) {
    // The callback returns details about the conversation.
}, user_data);
if (ret != TIM_SUCC) {
    // Failed to call the TIMConvCreate API
}

Sending messages

In the IM SDK, messages are represented by TIMMessage. Each TIMMessage consists of multiple TIMElem objects. A TIMElem object can be text or an image, which means a message can contain multiple objects including the text, image, and other objects.

Example:

const void* user_data = nullptr; // Return of the callback function
Json::Value json_value_text;
json_value_text[kTIMElemType] = kTIMElem_Text;
json_value_text[kTIMTextElemContent] = "Message Send to Windows-02";
Json::Value json_value_msg;
json_value_msg[kTIMMsgElemArray].append(json_value_text);

const char* userid = "Windows-02";
int ret = TIMMsgSendNewMsg(userid, kTIMConv_C2C, json_value_msg.toStyledString().c_str(), [](int32_t code, const char* desc, const char* json_param, const void* user_data) {
    if (code != ERR_SUCC) { 
        // Failed to send the message
        return;
    }
    // Sent the message successfully

}, user_data);
if (ret != TIM_SUCC) {
    // Failed to call the TIMMsgSendNewMsg API
}

Receiving Messages

In most cases, users need to be notified of new messages. For this purpose, you simply need to register the new message notification callback TIMMessageListener. When the user logs in, offline messages will be pulled. To avoid missing message notifications, register the listener callback for new messages before login.

Example of setting a message listener

// Sets a new message listener. When a new message arrives, a callback is triggered through this listener.
const void *user_data = nullptr;
TIMSetRecvNewMsgCallback([](const char* json_msg_array, const void* user_data) {
    Json::Value json_value_msgs; // Parse the message
    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++) {  // Traverse messages
        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++) {   // Traverse Elems
            Json::Value& elem = elems[i];

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

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

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

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

            }
        }
    }

}, user_data);

For more information on receiving and sending messages, see Sending Messages and Receiving Messages.

Group Management

There are multiple group types in IM. For information on their characteristics and limits, see the Group System. A group is identified by a unique ID, which allows for different operations. Group-related operations are implemented by TIMGroupManager, which can be used after login.

Creating a group

The following example shows how to create a public group named Windows-Group-Name and invite user Windows_002 to the group.
Example:

Json::Value json_group_member_array(Json::arrayValue);
// Initial group members
Json::Value json_group_member;
json_group_member[kTIMGroupMemberInfoIdentifier] = "Windows_002";
json_group_member[kTIMGroupMemberInfoMemberRole] = kTIMGroupMemberRoleFlag_Member;
json_group_member_array.append(json_group_member);

Json::Value json_value_createparam;
json_value_createparam[kTIMCreateGroupParamGroupId] = "Windows-Group-01";
json_value_createparam[kTIMCreateGroupParamGroupType] = kTIMGroup_Public;
json_value_createparam[kTIMCreateGroupParamGroupName] = "Windows-Group-Name";
json_value_createparam[kTIMCreateGroupParamGroupMemberArray] = json_group_member_array;

json_value_createparam[kTIMCreateGroupParamNotification] = "group notification";
json_value_createparam[kTIMCreateGroupParamIntroduction] = "group introduction";
json_value_createparam[kTIMCreateGroupParamFaceUrl] = "group face url";
json_value_createparam[kTIMCreateGroupParamMaxMemberCount] = 2000;
json_value_createparam[kTIMCreateGroupParamAddOption] = kTIMGroupAddOpt_Any;

const void* user_data = nullptr;
int ret = TIMGroupCreate(json_param.c_str(), [](int32_t code, const char* desc, const char* json_params, const void* user_data) {
    if (code != ERR_SUCC) { 
        // Failed to create the group
        return;
    }

    // Created the group successfully and parsed the JSON string to obtain the GroupID

}, user_data))

For more information on group operations, see Group APIs.

Group messages

Group messages are similar to C2C (one-to-one chat) messages and require you to enter the group ID and group type kTIMConv_Group when the message is sent. For more information, see Sending Messages in SDK documentation.