tencent cloud

Feedback

Last updated: 2024-07-10 16:33:53

    Description

    Starting from version 2.21.0, the Web Chat SDK provides a feature for User Status Management, where each user has two different types of status:
    Normal Status. An SDK built-in status that cannot be directly modified by clients.
    Custom Status. A client-defined status that can be modified. Using Custom Status, you can set information such as "Listening to music," "During the call," etc.
    Note:
    User status is specific to the current user and is not related to the device. If multiple devices are logged in to the same account simultaneously, querying or setting the status by device is not supported.
    There are three types of normal user status:
    Online (TIM.TYPES.USER_STATUS_ONLINE): The current user has logged in and is online, can send and receive messages normally.
    Offline (TIM.TYPES.USER_STATUS_OFFLINE): Web login/logout will not trigger offline status. In apps integrating Native IMSDK, offline status will be triggered.
    Unlogged in (TIM.TYPES.USER_STATUS_UNLOGINED): The user has never logged in after registering an account, or the user proactively called logout to log out.
    Note:
    Some of the features described below are supported by the Advanced package only. Please confirm before use.
    Some of the features described below need to be enabled in the Chat Console. Please confirm before use.
    
    
    

    Set your custom status

    You can call the interface setSelfStatus to set the customStatus field for your custom status. Once set successfully, you will receive a notification of your status change through the TIM.EVENT.USER_STATUS_UPDATED event. For more details, please refer to the status change notification below.
    Custom status clearance mechanism:
    1. You can actively clear your status by setting the customStatus field to an empty string when calling the setSelfStatus interface.
    2. After logging out for a period of time (Web), the IM backend will automatically clear the custom status. This will also trigger a status change notification.
    Note:
    1. Calling setSelfStatus does not require upgrading to the Advanced Edition, nor does it need the Console Switch to be turned on.
    2. This interface does not perform frequency limiting control.
    API
    chat.setSelfStatus(options);
    Parameters
    The options parameter is of the Object type, and contains the following attribute values:
    Name
    Type
    Description
    customStatus
    String
    User Custom Status
    Return values
    Promise
    Example
    // Set customStatus to an empty string '', this will clear your 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 and descriptions are 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 - User Custom Status
    }).catch(function(imError) {
    console.warn('setSelfStatus error:', imError); // Failed to set user's custom status
    });

    Check User Status

    You can call the getUserStatus API to query your own and other users' statuses. The API will return both the normal status and the custom status of the queried users.
    API
    chat.getUserStatus(options);
    Parameters
    The options parameter is of the Object type, and contains the following attribute values:
    Name
    Type
    Description
    userIDList
    Array
    List of userIDs to be queried. When querying yourself, you only need to pass your own userID.
    Return values
    Promise

    Query Your Own Status

    Set userIDList to include only your own userID to query your own status.
    Note:
    1. Querying your own status does not require upgrading to the flagship version or enabling the console switch.
    2. Querying your own status is not subject to API rate limiting control.
    Example
    // Check your own user status
    // userIDList includes only your own userID to query your 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 and descriptions are 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 - User Definition Status
    });
    }).catch(function(imError) {
    console.warn('getUserStatus error:', imError); // Failed to obtain user status
    });

    Check the status of others

    Set userIDList to the userID list of others to check their status.
    Querying the status of other users requires an upgrade to the advanced bundle. For details, see Basic Service Details.
    Querying the status of other users requires enabling "User Status Inquiry and Status Change Notification" in the Chat Console in advance. If this switch is turned off, calling getUserStatus will result in an error.
    
    
    
    INote:
    API rate limiting is set to 20 requests every 5 seconds by default, and a single query can include no more than 500 users.
    Example
    // Query the status of other users
    let promise = chat.getUserStatus({userIDList: ['user0', 'user1']});
    promise.then(function(imResponse) {
    const { successUserList, failureUserList } = imResponse.data;
    // List of users with successful queries
    successUserList.forEach((item) => {
    const { userID, statusType, customStatus } = item;
    // userID - User ID
    // statusType - User status, the enumerated values and descriptions are 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 - User Definition Status
    });
    
    // List of users with failed queries
    failureUserList.forEach((item) => {
    const { userID, code, message } = item;
    // userID - User ID of the failed query
    // code - Error code of the failed query
    // message - Error message of the failed query
    });
    }).catch(function(imError) {
    console.warn('getUserStatus error:', imError); // Failed to obtain user status
    });

    Subscription user status

    You can call the interface subscribeUserStatus to subscribe to the status of specified users. After successful subscription, when the status of the subscribed user changes (including normal status and custom status), you will receive a user status change notification through the TIM.EVENT.USER_STATUS_UPDATED event.
    API Features:
    1. This interface does not support subscribing to your own status. If you want to perceive your own status changes, you can directly listen to the TIM.EVENT.USER_STATUS_UPDATED event. For details, please refer to the Status Change Notification section below.
    2. This interface supports subscribing to the status of friends, but subscribing to friends will also occupy subscription slots in the IM backend.
    If you are concerned about the status of all friends, you do not need to call this interface. Directly enable the friend status auto-notification switch in the Chat Console. Once enabled, you will receive friend status change notifications through the TIM.EVENT.USER_STATUS_UPDATED event.
    If you only care about the status of some friends, you can only call subscribeUserStatus to actively subscribe. Once the subscription is successful, you can receive friend status change notifications through the TIM.EVENT.USER_STATUS_UPDATED event.
    Subscribing to user status requires upgrading to the advanced bundle. For details, see Basic Service Details.
    Subscribing to user status requires enabling "User Status Inquiry and Status Change Notification" in the Chat Console in advance. If this switch is turned off, calling subscribeUserStatus will result in an error.
    Indication
    API rate limiting defaults to 20 requests every 5 seconds, and the maximum number of users per subscription cannot exceed 100.
    API
    chat.subscribeUserStatus(options);
    Parameters
    The options parameter is of the Object type, and contains the following attribute values:
    Name
    Type
    Description
    userIDList
    Array
    List of user userID, up to 100 per request.
    Return values
    Promise
    Example
    let promise = chat.subscribeUserStatus({userIDList: ['user0', 'user1']});
    promise.then(function(imResponse) {
    const { failureUserList } = imResponse.data;
    // List of users with failed subscriptions
    failureUserList.forEach((item) => {
    const { userID, code, message } = item;
    // userID - User ID of the failed query
    // code - Error code of the failed query
    // message - Error message of the failed query
    });
    }).catch(function(imError) {
    console.warn('subscribeUserStatus error:', imError); // Error information regarding the failure to subscribe to user status
    });

    Unsubscribe user status

    If you do not want to receive user status change notifications, you can call the unsubscribeUserStatus API to unsubscribe from user status or clear the subscription list. If you do not want to actively clear the subscription list, the IM backend will automatically clear the subscription list after a default delay period when the account logs out.
    Unsubscribing from user status requires upgrading to the advanced bundle. For details, see Basic Service Details.
    Unsubscribing from user status requires enabling "User Status Inquiry and Status Change Notification" in the Chat Console in advance. If this switch is turned off, calling unsubscribeUserStatus will result in an error.
    Indication
    API rate limiting defaults to 20 requests every 5 seconds, and the maximum number of users per unsubscription cannot exceed 100.
    API
    chat.unsubscribeUserStatus(options);
    Parameters
    When the parameter options is undefined, it means to cancel all current subscriptions. When options is an Object, it contains the following attribute values:
    Name
    Type
    Description
    userIDList
    Array
    List of user IDs, with a maximum of 100 per single request. When userIDList is an empty array or undefined, it cancels all current subscriptions.
    Return values
    Promise
    Example
    // Unsubscribe current partial users
    let promise = chat.unsubscribeUserStatus({userIDList: ['user0', 'user1']});
    promise.then(function(imResponse) {
    const { failureUserList } = imResponse.data;
    // List of users with failed unsubscriptions
    failureUserList.forEach((item) => {
    const { userID, code, message } = item;
    // userID - User ID of the failed query
    // code - Error code of the failed query
    // message - Error message of the failed query
    });
    }).catch(function(imError) {
    console.warn('unsubscribeUserStatus error:', imError); // Information related to the unsubscription failure
    });
    
    // Unsubscribe from all current subscriptions
    let promise = chat.unsubscribeUserStatus();
    promise.then(function(imResponse) {
    const { failureUserList } = imResponse.data;
    // List of users with failed unsubscriptions
    failureUserList.forEach((item) => {
    const { userID, code, message } = item;
    // userID - User ID of the failed query
    // code - Error code of the failed query
    // message - Error message of the failed query
    });
    }).catch(function(imError) {
    console.warn('unsubscribeUserStatus error:', imError); // Information related to the unsubscription failure
    });

    Status Change Notification

    Based on the user type whose status you wish to perceive, status changes can be categorized into 3 types:
    1. Perceive changes in own status.
    2. Perceive changes in friends' status.
    3. Perceive the status change of users (who are not friends).
    For the above 3 methods of status change notifications, the SDK will dispatch the TIM.EVENT.USER_STATUS_UPDATED event.
    Although all status notifications are thrown through TIM.EVENT.USER_STATUS_UPDATED, different types of users trigger this notification differently.

    Notification of Own Status Change

    If you have pre-registered for the TIM.EVENT.USER_STATUS_UPDATED event listener, when your own status changes, the SDK will dispatch the TIM.EVENT.USER_STATUS_UPDATED event, and you can get your latest status there.

    Notification of Friend's Status Change

    1. If you have enabled the automatic friend status notification in the Chat Console, when a friend's status changes, the SDK will dispatch the TIM.EVENT.USER_STATUS_UPDATED event, and you can get your friend's latest status there.
    2. If you have not enabled automatic friend status notifications and still want to be aware of friend status changes, you need to call subscribeUserStatus to actively subscribe to the friend's status. When the friend's status changes, the SDK will dispatch the TIM.EVENT.USER_STATUS_UPDATED callback.
    Note:
    subscribeUserStatus is supported only for advanced customers and requires the console switch to be enabled. For details, please refer to the Subscribe user status mentioned above.
    3. If you have neither enabled automatic notification of friend status nor called subscribeUserStatus to actively subscribe to friend status, then when a friend's status changes, you will not be able to perceive it.

    Status Change of Regular Users (Non-friends)

    If you want to be aware of regular user (non-friend) status changes, you can only call subscribeUserStatus to actively subscribe. When that user's status changes, the TIM.EVENT.USER_STATUS_UPDATED callback will be triggered, and you can get their latest status there.
    Note:
    subscribeUserStatus is supported only for advanced customers and requires the console switch to be enabled. For details, please refer to the Subscribe user status mentioned above.
    Example
    /**
    * Scenarios for receiving notifications:
    * 1. When a subscribed user's status changes (including online status and user-defined status), this event will be triggered
    * 2. If the Friend Status Notification Switch is enabled in the console, even if you haven't actively subscribed, this event will be triggered when a friend's status changes
    * 3. When the same account logs in to multiple devices, if one device modifies the user-defined status, all devices will receive this event
    */
    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 and descriptions are 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 - User Definition Status
    })
    };
    chat.on(TencentCloudChat.EVENT.USER_STATUS_UPDATED, onUserStatusUpdated);
    Note:
    Besides knowing the user's status through TIM.EVENT.USER_STATUS_UPDATED mentioned above, you can also proactively check the user's status. For more details, please refer to the previous section Check User Status.

    Status Change Notification across multiple platforms, Multi-Instance Synchronization

    If you have enabled multi-client or same platform multi-instance login (for details, please see Multi-client or same platform multi-instance login), the same account can log in on different devices. When the self-defined status of a user logged in on one device changes, the IM background will send a status change notification to other logged-in devices as well.

    Interface Limitations

    Package Limits

    setSelfStatus interface is not limited to the Advanced Edition.
    getUserStatus to check your status is not limited to the Advanced Edition.
    getUserStatus requires an upgrade to the Advanced Edition for queries other than checking your own status.
    All capabilities of the subscribeUserStatus / unsubscribeUserStatus interface require upgrading to the Advanced Edition.

    API Rate Limiting

    setSelfStatus interface is not subject to rate limiting.
    getUserStatus querying your status is not rate-limited.
    getUserStatus, apart from querying your own status, is by default limited to 20 requests every 5 seconds, with a maximum of 500 users per query.
    subscribeUserStatus interface, by default limited to 20 requests every 5 seconds, with a maximum of 100 users per subscription.
    unsubscribeUserStatus interface, by default limited to 20 requests every 5 seconds, with a maximum of 100 users per single subscription cancellation.

    FAQs

    When invoking the Subscription/Cancel Subscription API, the interface prompts the error code "72001"

    Error code 72001 indicates that the corresponding capability has not been enabled in the console. Please log in to the Chat Console to turn on the corresponding feature toggle.
    
    
    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