• UIKit
  • SDK
  • サーバー API
Chat/
SDK/
Web/
ユーザープロファイルとリレーションシップチェーン/
SDK
  • Chat SDK のインストール
  • Chat SDK の初期化
  • ログインとログアウト
  • 顧客インターフェース
  • Changelog
  • メッセージ
    • Overview
    • メッセージ送信
    • メッセージの受信
    • 過去のメッセージ
    • メッセージ転送
    • メッセージの変更
    • メッセージ削除
    • 過去のメッセージをクリアします
    • メッセージの取り消し
    • オンラインメッセージの送信
    • メッセージの既読レシート
    • クエリーメッセージ
    • ターゲットグループメッセージ
    • 通知しません
    • Key-Value の拡張
    • 翻訳
  • セッション
    • Overview
    • セッションリスト
    • セッションの取得
    • 未読数
    • セッションの先頭固定表示
    • セッションの削除
    • マーク
    • セッショングループ
  • グループ
    • Overview
    • グループ管理
    • グループプロファイル
    • グループメンバーの管理
    • グループメンバープロファイル
    • グループプロパティのカスタマイズ
    • グループカウンター
  • コミュニティトピック
    • コミュニティ管理
  • ユーザープロファイルとリレーションシップチェーン
    • ユーザープロファイル
    • ユーザー状態
    • 友達管理
    • 友達リスト
    • ブラックリスト
  • Guideline for Beginners
  • コンソールガイド
    • アプリケーションの作成とアップグレード
    • 基本設定
    • 機能設定
    • アカウント管理
    • グループ管理
    • コールバック設定
  • 製品紹介
    • メッセージ管理
      • シングルチャットメッセージ
      • メッセージの保存
      • オフラインプッシュ
      • グループメッセージ
      • メッセージフォーマット
    • アカウントシステム
      • ログイン認証
      • オンライン状態管理
    • グループ関連
      • グループシステム
      • グループ管理
    • ユーザープロファイルとリレーションシップチェーン
      • 資料管理
      • リレーションシップチェーン管理
  • 購入ガイド
    • 課金の概要
    • 価格
  • エラーコード
このページは現在英語版のみで提供されており、日本語版も近日中に提供される予定です。ご利用いただきありがとうございます。

ユーザー状態

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.