tencent cloud

Feedback

Last updated: 2023-07-17 16:31:23

    Feature Description

    Each user has two statuses:
    General status. It is preset in the SDK and cannot be modified.
    Custom status. It can be customized and modified by users. For example, it can be set to "Listening to music" or "On the call".
    The general user status is available in the following three types:
    Online (TencentCloudChat.TYPES.USER_STATUS_ONLINE): The current user has logged in and can receive and send messages.
    Offline (TencentCloudChat.TYPES.USER_STATUS_OFFLINE): The offline status will not be triggered when the SDK for web is logged in/out. It will be triggered in the application with the IM SDK for React Native.
    Not logged in (TencentCloudChat.TYPES.USER_STATUS_UNLOGINED): The user hasn't logged in since registration or has called logout to log out.
    Note
    1. Some of the following features are supported only by the Premium edition. Make sure that you have purchased it before use.
    2. You need to enable user status in the Chat console for some of the following features. Make sure that you have enabled it before use.
    3. User status is relevant to the current user but not the device. If an account is logged in on multiple devices at the same time, the status cannot be queried or set by device.

    Setting the Custom Status

    Call the setSelfStatus API to set a user's own custom status through the customStatus field. Then, notifications of a change in the user's own custom status will be received through the TencentCloudChat.EVENT.USER_STATUS_UPDATED event.
    The following describes how to clear the custom status:
    1. When calling the setSelfStatus API, you can leave the customStatus field empty to clear the status.
    2. A period of time after the account logs out of the SDK for web, the Chat backend will automatically clear the custom status and trigger the status change notification.
    Note
    1. To call setSelfStatus, you don't need to upgrade to the Premium edition or enable the feature in the console.
    2. This API can be called an unlimited number of times.
    API
    chat.setSelfStatus(options);
    Parameter
    The options parameter is of the Object type. It contains the following attribute values:
    Name
    Type
    Description
    customStatus
    String
    Custom user status
    Returned value
    Promise
    Sample
    // Set `customStatus` to the empty string `''` to clear the user's own custom status
    let promise = chat.setSelfStatus({customStatus: 'xxx'});
    promise.then(function(imResponse) {
    console.log(imResponse.data);
    const { userID, statusType, customStatus } = imResponse.data;
    // userID - User ID
    // statusType - User status. The enumerated values are described as follows:
    // TencentCloudChat.TYPES.USER_STATUS_UNKNOWN - Unknown
    // TencentCloudChat.TYPES.USER_STATUS_ONLINE - Online
    // TencentCloudChat.TYPES.USER_STATUS_OFFLINE - Offline
    // TencentCloudChat.TYPES.USER_STATUS_UNLOGINED - Not logged in
    // customStatus - Custom user status
    }).catch(function(imError) {
    console.warn('setSelfStatus error:', imError); // Failed to set the user's own custom status
    });

    Querying the User Status

    Call the getUserStatus API to query the status of the user or another user. The API will return the general status and custom status of the queried user.
    Note
    1. To allow users to query their own status, you don't need to upgrade to the Premium edition or enable the feature in the console. And in this case, this API can be called an unlimited number of times.
    2. To query the status of other user, you need to upgrade to the Premium edition and enable Set user status query and status change notification in the Chat console in advance; otherwise, an error will be reported when getUserStatus is called. In this case, this API can be called 20 times every five seconds, and the statuses of up to 500 users can be queried at a time.
    API
    chat.getUserStatus(options);
    Parameter
    The options parameter is of the Object type. It contains the following attribute values:
    Name
    Type
    Description
    userIDList
    Array
    List of the userID values to be queried. Users only need to pass in their own userID to query their own status.
    Returned value
    Promise
    Sample
    // Query the user's own status
    // When `userIDList` contains only the user's own `userID`
    // it indicates to query only the user's own status.
    let promise = chat.getUserStatus({userIDList: [`${myUserID}`]});
    promise.then(function(imResponse) {
    const { successUserList } = imResponse.data;
    successUserList.forEach((item) => {
    const { userID, statusType, customStatus } = item;
    // userID - User ID
    // statusType - User status. The enumerated values are described as follows:
    // TencentCloudChat.TYPES.USER_STATUS_UNKNOWN - Unknown
    // TencentCloudChat.TYPES.USER_STATUS_ONLINE - Online
    // TencentCloudChat.TYPES.USER_STATUS_OFFLINE - Offline
    // TencentCloudChat.TYPES.USER_STATUS_UNLOGINED - Not logged in
    // customStatus - Custom user status
    });
    }).catch(function(imError) {
    console.warn('getUserStatus error:', imError); // Failed to obtain the user status
    });
    // Query the status of another user
    let promise = chat.getUserStatus({userIDList: ['user0', 'user1']});
    promise.then(function(imResponse) {
    const { successUserList, failureUserList } = imResponse.data;
    // List of `userID` values of the users whose statuses were queried successfully
    successUserList.forEach((item) => {
    const { userID, statusType, customStatus } = item;
    // userID - User ID
    // statusType - User status. The enumerated values are described as follows:
    // TencentCloudChat.TYPES.USER_STATUS_UNKNOWN - Unknown
    // TencentCloudChat.TYPES.USER_STATUS_ONLINE - Online
    // TencentCloudChat.TYPES.USER_STATUS_OFFLINE - Offline
    // TencentCloudChat.TYPES.USER_STATUS_UNLOGINED - Not logged in
    // customStatus - Custom user status
    });
    
    // List of `userID` values of the users whose statuses failed to be queried
    failureUserList.forEach((item) => {
    const { userID, code, message } = item;
    // userID - `userID` of the user whose status failed to be queried
    // code - Error code for the failed query
    // message - Error message for the failed query
    });
    }).catch(function(imError) {
    console.warn('getUserStatus error:', imError); // Failed to obtain the user status
    });

    Subscribing to the User Status

    Call the subscribeUserStatus API to subscribe to the status of the specified user. When the user status (including general status and custom status) subscribed to changes, the status change notification can be received through the TencentCloudChat.EVENT.USER_STATUS_UPDATED event.
    Note
    1. To use this feature, you need to upgrade to the Premium edition. For more information, see Pricing.
    2. To use this feature, you need to enable Set user status query and status change notification in the Chat console in advance; otherwise, an error will be reported when subscribeUserStatus is called.
    3. By default, this API can be called 20 times every five seconds, and the statuses of up to 100 users can be subscribed to at a time.
    4. To get the changes in the statuses of all of a user's friends, you don't need to call this API, and you can enable automatic notifications of friends' statuses in the Chat console, after which a friend status change notification can be received through the TencentCloudChat.EVENT.USER_STATUS_UPDATED callback.
    API
    chat.subscribeUserStatus(options);
    Parameter
    The options parameter is of the Object type. It contains the following attribute values:
    Name
    Type
    Description
    userIDList
    Array
    List of userID values. The number of userID values cannot exceed 100 per request.
    Returned value
    Promise
    Sample
    let promise = chat.subscribeUserStatus({userIDList: ['user0', 'user1']});
    promise.then(function(imResponse) {
    const { failureUserList } = imResponse.data;
    // List of `userID` values of the users whose statuses failed to be subscribed to
    failureUserList.forEach((item) => {
    const { userID, code, message } = item;
    // userID - `userID` of the user whose status failed to be queried
    // code - Error code for the failed query
    // message - Error message for the failed query
    });
    }).catch(function(imError) {
    console.warn('subscribeUserStatus error:', imError); // Failed to subscribe to the user status
    });

    Unsubscribing from the User Status

    To stop receiving notifications of changes in user statuses, call the unsubscribeUserStatus API to unsubscribe from the user status or clear the subscription list. If you don't want the subscription list to be cleared manually, after the account is logged out, the Chat backend will clear it after a certain period of time by default.
    Note
    1. To use this feature, you need to upgrade to the Premium edition. For more information, see Pricing.
    2. To use this feature, you need to enable Set user status query and status change notification in the Chat console in advance; otherwise, an error will be reported when unsubscribeUserStatus is called.
    3. By default, this API can be called 20 times every five seconds, and the statuses of up to 100 users can be unsubscribed from at a time.
    API
    chat.unsubscribeUserStatus(options);
    Parameter
    When the options parameter is undefined, it indicates to cancel all the current subscriptions. When it is of the Object type, it contains the following attribute values:
    Name
    Type
    Description
    userIDList
    Array
    List of userID values. The number of userID values cannot exceed 100 per request. When userIDList is an empty array or undefined, it indicates to cancel all the current subscriptions.
    Returned value
    Promise
    Sample
    // Unsubscribe from some of the current user statuses
    let promise = chat.unsubscribeUserStatus({userIDList: ['user0', 'user1']});
    promise.then(function(imResponse) {
    const { failureUserList } = imResponse.data;
    // List of `userID` values of the users whose statuses failed to be unsubscribed from
    failureUserList.forEach((item) => {
    const { userID, code, message } = item;
    // userID - `userID` of the user whose status failed to be queried
    // code - Error code for the failed query
    // message - Error message for the failed query
    });
    }).catch(function(imError) {
    console.warn('unsubscribeUserStatus error:', imError); // Failed to unsubscribe from the user status
    });
    // Unsubscribe from all the current subscribed user statuses
    let promise = chat.unsubscribeUserStatus();
    promise.then(function(imResponse) {
    const { failureUserList } = imResponse.data;
    // List of `userID` values of the users whose statuses failed to be unsubscribed from
    failureUserList.forEach((item) => {
    const { userID, code, message } = item;
    // userID - `userID` of the user whose status failed to be queried
    // code - Error code for the failed query
    // message - Error message for the failed query
    });
    }).catch(function(imError) {
    console.warn('unsubscribeUserStatus error:', imError); // Failed to unsubscribe from the user status
    });

    Status Change Notification

    Depending on the user type, status changes can be divided into three types:
    1. Change in a user's own status.
    2. Change in a friend's status.
    3. Change in a non-friend user's status.
    The SDK will deliver the TencentCloudChat.EVENT.USER_STATUS_UPDATED event to notify a status change of any of the three types.
    Although all the status notifications are returned in the TencentCloudChat.EVENT.USER_STATUS_UPDATED callback, they are triggered in different ways for different user types.

    Notification of a change in a user's own status

    If you have registered the TencentCloudChat.EVENT.USER_STATUS_UPDATED event listener, when a user's own status changes, the SDK will deliver the TencentCloudChat.EVENT.USER_STATUS_UPDATED event, where the user can get the latest own status.

    Notification of a change in a friend's status

    1. If you have enabled automatic notifications of friends' statuses in the Chat console, when the status of a user's friend changes, the SDK will deliver the TencentCloudChat.EVENT.USER_STATUS_UPDATED event, where the latest status of the friend can be obtained.
    2. If you don't enable automatic notifications of friends' statuses and want to get friends' status changes, you need to call subscribeUserStatus to subscribe to friends' statuses. When a friend's status changes, the SDK will deliver the TencentCloudChat.EVENT.USER_STATUS_UPDATED callback.
    3. If you neither enable automatic notifications of friends' statuses nor call subscribeUserStatus to subscribe to friends' statuses, changes in friends' statuses cannot be obtained.

    Change in a non-friend user's status

    To get the change in a non-friend user's status, you can only call subscribeUserStatus to subscribe to the status. When the user's status changes, the TencentCloudChat.EVENT.USER_STATUS_UPDATED callback will be triggered, where the user can get the latest status of the non-friend user.
    Sample
    let onUserStatusUpdated = function(event) {
    console.log(event.data);
    const userStatusList = event.data;
    userStatusList.forEach((item) => {
    const { userID, statusType, customStatus } = item;
    // userID - User ID
    // statusType - User status. The enumerated values are described as follows:
    // TencentCloudChat.TYPES.USER_STATUS_UNKNOWN - Unknown
    // TencentCloudChat.TYPES.USER_STATUS_ONLINE - Online
    // TencentCloudChat.TYPES.USER_STATUS_OFFLINE - Offline
    // TencentCloudChat.TYPES.USER_STATUS_UNLOGINED - Not logged in
    // customStatus - Custom user status
    })
    };
    chat.on(TencentCloudChat.EVENT.USER_STATUS_UPDATED, onUserStatusUpdated);

    Multi-client and multi-instance sync of status change notifications

    If you have enabled multi-client login or multi-instance login on the same platform (for more information, see Feature Configuration), an account can be logged in on different clients. When the status of the user logged in on one of the clients changes, the Chat backend will send the status change notification to other logged-in devices.

    FAQs

    What should I do if error code 72001 is reported when I call the subscribe/unsubscribe API?

    Error code 72001 indicates that the feature is not enabled in the console. You need to log in to the Chat console and enable the feature.
    Contact Us

    Contact our sales team or business advisors to help your business.

    Technical Support

    Open a ticket if you're looking for further assistance. Our Ticket is 7x24 avaliable.

    7x24 Phone Support