Class ChatClient

ChatClient 是 SDK 的主入口，负责连接生命周期管理、消息发送、事件分发、缓存访问和管理器注册。

Methods

init login logout getConnectionState getCurrentUserId getClientResource renewToken getRTCTokenInfo getUserIdsWithRTCUids getSelfIdsOnOtherPlatform getServerUrlsConfig addEventHandler removeEventHandler use

Methods

Staticinit

  • init<Managers extends readonly ManagerRegistration<ChatClient>[] = []>(
        config: InitConfig & { managers?: Managers },
    ): WithManagers<ChatClient, Managers>

    初始化 ChatClient 单例。首次调用时创建实例；后续若使用相同配置调用，将复用该实例，并支持追加注册管理器。

    Type Parameters

    Parameters

    • config: InitConfig & { managers?: Managers }

      初始化配置，必须且只能包含 App Key 或 App ID 之一，并可包含服务接入参数与管理器列表。

    Returns WithManagers<ChatClient, Managers>

    返回带已注册管理器类型增强的 ChatClient 实例。

    Example: 初始化并注册管理器

    const client = ChatClient.init({
      appKey: 'org#app',
      managers: [ChatManager, GroupManager],
    });

    Example: 使用 App ID 初始化；登录时 SDK 会通过 DNSConfig 解析对应的 App Key。

    const client = ChatClient.init({ appId: 'application-id' });
    await client.login({ userId: 'user-id', token: 'token' });

login

  • login(params: AuthContext): Promise<void>

    登录并建立到消息服务的长连接。登录成功后会恢复本地缓存、同步会话列表，并按配置触发好友列表与用户属性同步。

    Parameters

    • params: AuthContext

      登录参数，包含用户 ID 和 Token。

    Returns Promise<void>

    登录成功时 resolve；该 Promise 不携带任何返回值。

    Example: 登录 SDK

    await client.login({
      userId: 'alice',
      token: 'your-im-token',
    });

logout

  • logout(): Promise<void>

    登出并关闭当前连接，同时清理登录态、运行时缓存引用与日志上报状态。

    Returns Promise<void>

    登出成功时 resolve；该 Promise 不携带任何返回值。

    Example: 登出 SDK

    await client.logout();

getConnectionState

  • getConnectionState(): ConnectionStatus

    获取当前连接状态。

    Returns ConnectionStatus

    返回当前连接状态枚举值。

    Example: 读取连接状态。

    const state = client.getConnectionState();

getCurrentUserId

  • getCurrentUserId(): null | string

    获取当前登录用户 ID。

    Returns null | string

    返回当前登录用户 ID；未登录时返回 null。

    Example: 读取当前登录用户

    const userId = client.getCurrentUserId();

getClientResource

  • getClientResource(): null | string

    获取当前连接的设备资源标识。

    Returns null | string

    返回当前连接的设备资源标识；若未连接或尚未完成登录握手，则返回 null。

    Example: 读取当前设备资源标识

    const clientResource = client.getClientResource();

renewToken

  • renewToken(token: string): Promise<TokenRenewalResult>

    更新当前登录会话的 IM token，并重置 token 生命周期提醒。

    Parameters

    • token: string

      新的 IM Token。该参数必传。

    Returns Promise<TokenRenewalResult>

    返回已应用的新 Token 和过期时间。

    Example: 续期 IM 登录 Token

    const result = await client.renewToken(newToken);

getRTCTokenInfo

  • getRTCTokenInfo(params?: GetRTCTokenInfoParams): Promise<RTCTokenInfo>

    获取当前用户的 RTC token 信息。

    Parameters

    • Optionalparams: GetRTCTokenInfoParams

      RTC Token 查询参数。可选。若传入 channelName，则返回该特定频道的 Token。

    Returns Promise<RTCTokenInfo>

    返回 RTC App ID、Token、频道名、UID 和过期时间。

    Example: 查询 RTC token

    const rtc = await client.getRTCTokenInfo({ channelName: 'demo' });

getUserIdsWithRTCUids

  • getUserIdsWithRTCUids(rtcUids: readonly number[]): Promise<RTCUidUserIdMap>

    批量查询映射到 RTC UID 的 IM 用户 ID。

    Parameters

    • rtcUids: readonly number[]

      RTC UID 列表。该参数必传，列表中的元素必须为合法数字。

    Returns Promise<RTCUidUserIdMap>

    返回 RTC UID 到 IM user ID 的映射；未命中的 UID 不会出现在结果中。

    Example: 查询 RTC UID 映射

    const users = await client.getUserIdsWithRTCUids([123456]);

getSelfIdsOnOtherPlatform

  • getSelfIdsOnOtherPlatform(): Promise<SelfIdsOnOtherPlatform>

    获取当前用户在其他已登录设备上的登录 ID 列表。登录 ID 由 user ID + "/" + resource (设备的识别号)组成。

    Returns Promise<SelfIdsOnOtherPlatform>

    返回当前用户在其他设备上的 userId/resource 列表；当前设备会被自动过滤。

    Example: 查询其他平台登录 ID

    const ids = await client.getSelfIdsOnOtherPlatform();

getServerUrlsConfig

  • getServerUrlsConfig(): undefined | ServerUrlsConfig

    获取当前固定的服务地址配置；仅在初始化时传入了 serviceConfig.serverUrls 才会返回有效值。

    Returns undefined | ServerUrlsConfig

    返回固定服务地址配置；若未配置返回 undefined。

    Example: 读取固定的服务地址配置

    const serverUrls = client.getServerUrlsConfig();

addEventHandler

  • addEventHandler(id: EventHandlerId, handlers: EventHandlerMap): void

    注册 ChatClient 事件处理器，用于监听连接、消息、好友、群组等 SDK 公开事件。

    Parameters

    • id: string

      事件处理器唯一 ID，用于后续移除。id 区分大小写。

    • handlers: EventHandlerMap

      事件处理器对象，按需实现对应的回调函数。

    公开可监听事件

    连接: onConnecting, onConnected, onDisconnected, onReconnectFailed, onTokenWillExpire, onTokenExpired, onOfflineMessageSyncStart, onOfflineMessageSyncFinish

    ConnectionEventName

    消息与会话: onMessage, onStreamMessage, onConversationListUpdate, onMessageReadReceipts, onMessageDelivered, onMessageRecalled, onMessageUpdated, onReactionChanged, onPinnedMessageChanged, onMultiDeviceContact, onMultiDeviceGroup, onMultiDeviceThread, onMultiDeviceConversation, onMultiDeviceMessageRemoved, onSyncDataStart, onSyncDataFinished

    ChatEventName

    在线状态: onPresenceStatusChange

    PresenceEventName

    联系人: onContactInvited, onContactDeleted, onContactAdded, onContactRefuse, onContactAgreed, onContactInfoUpdated

    ContactEventName

    用户资料: onOwnInfoUpdated, onUserInfoUpdated

    UserInfoEventName

    群组: onInvitationReceived, onRequestToJoinReceived, onRequestToJoinAccepted, onRequestToJoinDeclined, onInvitationAccepted, onInvitationDeclined, onUserRemoved, onGroupDestroyed, onAutoAcceptInvitationFromGroup, onMuteListAdded, onMuteListRemoved, onAllowListAdded, onAllowListRemoved, onAllMemberMuteStateChanged, onAdminAdded, onAdminRemoved, onOwnerChanged, onMembersJoined, onMembersExited, onAnnouncementChanged, onSharedFileAdded, onSharedFileDeleted, onGroupInfoChanged, onGroupDisabledChanged, onGroupMemberAttributeChanged, onUserGroupNamecardUpdated

    GroupEventName

    Returns void

    注册成功后无返回值。

    Example: 监听连接状态变化

    client.addEventHandler('client-events', {
      onConnected: () => console.log('connected'),
    });

removeEventHandler

  • removeEventHandler(id: string): void

    移除指定的 ChatClient 事件处理器。

    Parameters

    • id: string

      待移除的事件处理器 ID。

    Returns void

    移除完成后无返回值。

    Example: 移除事件处理器

    client.removeEventHandler('client-events');

use

Settings

Member Visibility

On This Page

Methods