• UIKit
  • SDK
  • 服务端 API
Chat/
SDK/
Web/
用户/
SDK
  • 集成 SDK
  • 初始化
  • 登录登出
  • 接口列表
  • 更新日志
  • 消息
    • 介绍
    • 发送消息
    • 接收消息
    • 历史消息
    • 转发消息
    • 修改消息
    • 删除消息
    • 清空消息
    • 撤回消息
    • 在线消息
    • 已读回执
    • 查询消息
    • 群定向消息
    • 消息免打扰
    • 消息扩展
    • 消息翻译
  • 会话
    • 介绍
    • 会话列表
    • 获取会话
    • 会话未读数
    • 置顶会话
    • 删除会话
    • 会话标记
    • 会话分组
  • 群组
    • 介绍
    • 管理群组
    • 群资料
    • 管理群成员
    • 群成员资料
    • 自定义属性
    • 群计数器
  • 社群话题
    • 管理社群
  • 用户
    • 用户资料
    • 用户状态
    • 管理好友
    • 好友列表
    • 黑名单
  • 开发指引
  • 控制台指南
    • 创建和升级应用
    • 基本配置
    • 功能配置
    • 账号管理
    • 群组管理
    • 回调配置
  • 产品介绍
    • 消息管理
      • 单聊消息
      • 消息存储
      • 离线推送
      • 群消息
      • 消息格式
    • 账号系统
      • 登陆验证
      • 在线状态管理
    • 群相关
      • 群组系统
      • 群组管理
    • 用户资料和关系链
      • 资料管理
      • 关系链管理
  • 购买指南
    • 计费概述
    • 价格中心
  • 错误码

用户状态

功能描述

从 2.21.0 版本开始,Web Chat SDK 提供了用户状态管理的功能,每个用户拥有两种不同类型的状态:
普通状态。SDK 内置状态,客户无法直接修改。
自定义状态。客户自定义的状态,可以自行修改。利用自定义状态,您可以对该设置诸如“听歌中”、“通话中”等一些自定义信息。
说明:
用户状态针对的是当前用户,跟设备无关。如果有多台设备同时登录同一个账号,不支持按设备查询或者按设备设置状态。
用户的普通状态类型有以下三种:
在线(TIM.TYPES.USER_STATUS_ONLINE):当前用户已登录上线,可以正常收发消息。
离线(TIM.TYPES.USER_STATUS_OFFLINE):web 登录/登出时不会触发离线状态, 在集成 Native IMSDK 的 App 中会触发离线状态。
未登录(TIM.TYPES.USER_STATUS_UNLOGINED):用户注册账号后从未登录过,或者用户主动调用 logout 退出登录。
注意:
下文所述的部分功能仅进阶版套餐支持,使用前请确认。
下文所述的部分功能需要在 Chat Console 打开对应的用户状态开关,使用前请确认。




设置自己的自定义状态

您可以调用接口 setSelfStatus 设置 customStatus 字段来设置自己的自定义状态。设置成功后,您可以通过 TIM.EVENT.USER_STATUS_UPDATED 事件收到自己状态变更的通知。详情请参见下文的 状态变更通知
自定义状态清除机制:
1. 您可以在调用 setSelfStatus 接口时,通过将 customStatus 字段设置为空来主动清除。
2. 账号登出一段时间(Web)后,IM 后台会自动清除自定义状态,此时也会触发状态变更通知。
说明:
1. 调用 setSelfStatus 不需要升级到进阶版,也无需开启控制台开关。
2. 本接口不做限频控制。
接口
chat.setSelfStatus(options);
参数
参数 options 为 Object 类型,包含的属性值如下:
Name
Type
Description
customStatus
String
用户自定义状态
返回值
Promise
示例
// 设置 customStatus 为空字符串 '',则清除自己的自定义状态
let promise = chat.setSelfStatus({customStatus: 'xxx'});
promise.then(function(imResponse) {
console.log(imResponse.data);
const { userID, statusType, customStatus } = imResponse.data;
// userID - 用户 ID
// statusType - 用户状态,枚举值及说明如下:
// TencentCloudChat.TYPES.USER_STATUS_UNKNOWN - 未知
// TencentCloudChat.TYPES.USER_STATUS_ONLINE - 在线
// TencentCloudChat.TYPES.USER_STATUS_OFFLINE - 离线
// TencentCloudChat.TYPES.USER_STATUS_UNLOGINED - 未登录
// customStatus - 用户自定义状态
}).catch(function(imError) {
console.warn('setSelfStatus error:', imError); // 设置用户自己的自定义状态失败的相关信息
});

查询用户状态

您可以调用 getUserStatus 接口查询自己和其他用户的状态,接口会返回被查询者的普通状态和自定义状态。
接口
chat.getUserStatus(options);
参数
参数 options 为 Object 类型,包含的属性值如下:
Name
Type
Description
userIDList
Array
待查询的用户 userID 列表,查询自己时,只需要传入自己的 userID 即可。
返回值
Promise

查询自己的状态

设置 userIDList 仅包含自己的 userID,可查询自己的状态。
说明:
1. 查询自己的状态不需要升级到旗舰版,也无需开启控制台开关。
2. 查询自己的状态不做接口限频控制。
示例
// 查询自己的用户状态
// userIDList 仅包含自己的 userID 时表示查询自己的状态
let promise = chat.getUserStatus({userIDList: [`${myUserID}`]});
promise.then(function(imResponse) {
const { successUserList } = imResponse.data;
successUserList.forEach((item) => {
const { userID, statusType, customStatus } = item;
// userID - 用户 ID
// statusType - 用户状态,枚举值及说明如下:
// TencentCloudChat.TYPES.USER_STATUS_UNKNOWN - 未知
// TencentCloudChat.TYPES.USER_STATUS_ONLINE - 在线
// TencentCloudChat.TYPES.USER_STATUS_OFFLINE - 离线
// TencentCloudChat.TYPES.USER_STATUS_UNLOGINED - 未登录
// customStatus - 用户自定义状态
});
}).catch(function(imError) {
console.warn('getUserStatus error:', imError); // 获取用户状态失败的相关信息
});

查询其他人的状态

设置 userIDList 为其他人的 userID 列表,可查询其他人的状态。
查询其他用户状态需要升级到进阶版套餐,详情请参见 基础服务详情
查询其他用户状态需要提前在 Chat Console 开启 “用户状态查询及状态变更通知”。如果开关关闭,调用 getUserStatus 会报错。



说明:
接口限频默认为 5 秒 20 次请求,单次查询最大用户数不超过 500 人。
示例
// 查询其他用户的状态
let promise = chat.getUserStatus({userIDList: ['user0', 'user1']});
promise.then(function(imResponse) {
const { successUserList, failureUserList } = imResponse.data;
// 查询成功的用户列表
successUserList.forEach((item) => {
const { userID, statusType, customStatus } = item;
// userID - 用户 ID
// statusType - 用户状态,枚举值及说明如下:
// TencentCloudChat.TYPES.USER_STATUS_UNKNOWN - 未知
// TencentCloudChat.TYPES.USER_STATUS_ONLINE - 在线
// TencentCloudChat.TYPES.USER_STATUS_OFFLINE - 离线
// TencentCloudChat.TYPES.USER_STATUS_UNLOGINED - 未登录
// customStatus - 用户自定义状态
});

// 查询失败的用户列表
failureUserList.forEach((item) => {
const { userID, code, message } = item;
// userID - 查询失败的用户 ID
// code - 查询失败的错误码
// message - 查询失败的错误信息
});
}).catch(function(imError) {
console.warn('getUserStatus error:', imError); // 获取用户状态失败的相关信息
});

订阅用户状态

您可以调用接口 subscribeUserStatus 订阅指定用户的状态。 订阅成功后,当您所订阅的用户状态变更时(包括普通状态和自定义状态),您可以通过 TIM.EVENT.USER_STATUS_UPDATED 事件收到用户状态变更通知。
接口特性:
1. 该接口不支持订阅自己的状态。如果您想感知自己的状态变更,可直接监听 TIM.EVENT.USER_STATUS_UPDATED 事件。详情请参见下文的 状态变更通知
2. 该接口支持订阅好友的状态,但是订阅好友也会占用 IM 后台订阅名额。
如果您关心所有好友的状态,不需要调用本接口,直接在 Chat Console 开启好友状态自动通知开关,开启后,您可以通过 TIM.EVENT.USER_STATUS_UPDATED 事件收到好友状态变更通知。
如果您仅关心部分好友的状态,只能调用 subscribeUserStatus 主动订阅。订阅成功后,您可以通过 TIM.EVENT.USER_STATUS_UPDATED 事件收到好友状态变更通知。
订阅用户状态需要升级到进阶版套餐,详情请参见 基础服务详情
订阅用户状态需要提前在 Chat Console 开启 “用户状态查询及状态变更通知”。如果开关关闭,调用 subscribeUserStatus 会报错。
说明:
接口限频默认为 5 秒 20 次请求,单次订阅最大用户数不超过 100 人。
接口
chat.subscribeUserStatus(options);
参数
参数 options 为 Object 类型,包含的属性值如下:
Name
Type
Description
userIDList
Array
用户 userID 列表,单次请求最多 100 个。
返回值
Promise
示例
let promise = chat.subscribeUserStatus({userIDList: ['user0', 'user1']});
promise.then(function(imResponse) {
const { failureUserList } = imResponse.data;
// 订阅失败的用户列表
failureUserList.forEach((item) => {
const { userID, code, message } = item;
// userID - 查询失败的用户 ID
// code - 查询失败的错误码
// message - 查询失败的错误信息
});
}).catch(function(imError) {
console.warn('subscribeUserStatus error:', imError); // 订阅用户状态失败的相关信息
});

取消订阅用户状态

如果您不想接收用户的状态变更通知,您可以调用接口 unsubscribeUserStatus 取消订阅用户的状态或清空订阅列表。 如果您不想主动清空订阅列表,当账号退出登录后,IM 后台默认延迟一段时间后自动清空订阅列表。
取消订阅用户状态需要升级到进阶版套餐,详情请参见 基础服务详情
取消订阅用户状态需要提前在 Chat Console 开启 “用户状态查询及状态变更通知”。如果开关关闭,调用 unsubscribeUserStatus 会报错。
说明:
接口限频默认为 5 秒 20 次请求,单次取消订阅最大用户数不超过 100 人。
接口
chat.unsubscribeUserStatus(options);
参数
参数 options 为 undefined 时,表示取消当前所有订阅,options 为 Object 时,包含的属性值如下:
Name
Type
Description
userIDList
Array
用户 userID 列表,单次请求最多 100 个。当 userIDList 为空数组或者 undefined 时,取消当前所有的订阅。
返回值
Promise
示例
// 取消当前部分用户的订阅
let promise = chat.unsubscribeUserStatus({userIDList: ['user0', 'user1']});
promise.then(function(imResponse) {
const { failureUserList } = imResponse.data;
// 取消订阅失败的用户列表
failureUserList.forEach((item) => {
const { userID, code, message } = item;
// userID - 查询失败的用户 ID
// code - 查询失败的错误码
// message - 查询失败的错误信息
});
}).catch(function(imError) {
console.warn('unsubscribeUserStatus error:', imError); // 取消订阅失败的相关信息
});

// 取消当前所有的订阅
let promise = chat.unsubscribeUserStatus();
promise.then(function(imResponse) {
const { failureUserList } = imResponse.data;
// 取消订阅失败的用户列表
failureUserList.forEach((item) => {
const { userID, code, message } = item;
// userID - 查询失败的用户 ID
// code - 查询失败的错误码
// message - 查询失败的错误信息
});
}).catch(function(imError) {
console.warn('unsubscribeUserStatus error:', imError); // 取消订阅失败的相关信息
});

状态变更通知

根据您希望感知用户状态的用户类型,可以将状态变更分为 3 种类型:
1. 感知自己的状态变更。
2. 感知好友的状态变更。
3. 感知用户(非好友)的状态变更。
上述 3 种方式的状态变更通知,SDK 都会派发 TIM.EVENT.USER_STATUS_UPDATED 事件。
虽然状态通知都通过 TIM.EVENT.USER_STATUS_UPDATED 抛出,但不同类型的用户触发该通知的方式不同。

自己的状态变更通知

如果您提前注册了 TIM.EVENT.USER_STATUS_UPDATED 事件监听,当自己的状态发生变更时,SDK 会派发 TIM.EVENT.USER_STATUS_UPDATED 事件,您可以在其中获取到自己的最新状态。

好友的状态变更通知

1. 如果您在 Chat Console 开启了好友状态自动通知,那么当好友的状态发生变更时,SDK 会派发 TIM.EVENT.USER_STATUS_UPDATED 事件,您可以在其中获取到好友的最新状态。
2. 如果您没有开启好友状态自动通知,并且仍然想感知好友的状态变更,您需要调用 subscribeUserStatus 主动订阅好友的状态。当好友的状态发生变更时,SDK 会派发 TIM.EVENT.USER_STATUS_UPDATED 回调。
注意:
subscribeUserStatus 仅进阶版客户支持,并且需要开启控制台开关。详情请参见上文的 订阅用户状态
3. 如果您既没有开启好友状态自动通知,也没有调用 subscribeUserStatus 主动订阅好友状态,那么当好友状态发生变更时,您将无法感知到。

普通用户(非好友)的状态变更

如果您希望感知普通用户(非好友)的状态变更,只能调用 subscribeUserStatus 主动订阅。当该用户状态发生变更时,会触发 TIM.EVENT.USER_STATUS_UPDATED 回调,您可以在其中获取到其最新状态。
注意:
subscribeUserStatus 仅进阶版客户支持,并且需要开启控制台开关。详情请参见上文的 订阅用户状态
示例
/**
* 收到通知的情况:
* 1. 订阅过的用户发生了状态变更(包括在线状态和自定义状态),会触发该事件
* 2. 在控制台打开了好友状态通知开关,即使未主动订阅,当好友状态发生变更时,也会触发该事件
* 3. 同一个账号多设备登录,当其中一台设备修改了自定义状态,所有设备都会收到该事件
*/
let onUserStatusUpdated = function(event) {
console.log(event.data);
const userStatusList = event.data;
userStatusList.forEach((item) => {
const { userID, statusType, customStatus } = item;
// userID - 用户 ID
// statusType - 用户状态,枚举值及说明如下:
// TencentCloudChat.TYPES.USER_STATUS_UNKNOWN - 未知
// TencentCloudChat.TYPES.USER_STATUS_ONLINE - 在线
// TencentCloudChat.TYPES.USER_STATUS_OFFLINE - 离线
// TencentCloudChat.TYPES.USER_STATUS_UNLOGINED - 未登录
// customStatus - 用户自定义状态
})
};
chat.on(TencentCloudChat.EVENT.USER_STATUS_UPDATED, onUserStatusUpdated);
说明:
除了上述通过 TIM.EVENT.USER_STATUS_UPDATED 得知用户状态以外,您还可以主动查询用户状态,详情请参见上文 查询用户状态

状态变更通知多端、多实例同步

如果您开启了多端或同平台多实例登录(详情请参见 多端或同平台多实例登录) ,同一个账号可以在不同设备上登录。当其中一个设备上所登录的用户的自定义状态发生变更时,IM 后台会给其他登录的设备也下发状态变更通知。

接口限制

套餐限制

setSelfStatus 接口不限制进阶版。
getUserStatus 查询自己的状态,不限制进阶版。
getUserStatus 除了查询自己的状态外,均需要升级到进阶版。
subscribeUserStatus / unsubscribeUserStatus 接口的所有能力,均需要升级到进阶版。

接口限频

setSelfStatus 接口不限频。
getUserStatus 查询自己的状态,不限频。
getUserStatus 除了查询自己的状态外,默认限制 5 秒 20 次请求,单次查询最大用户数不超过 500。
subscribeUserStatus 接口,默认限制 5 秒 20 次请求,单次订阅最大用户数不超过 100。
unsubscribeUserStatus 接口,默认限制 5 秒 20 次请求,单次取消订阅最大用户数不超过 100。

常见问题

调用订阅/取消订阅接口时,接口提示 “72001” 的错误码

72001 错误码表示在控制台上并没有开启对应的能力,请登录 Chat Console 打开对应的功能开关。