Class ChatClient

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

Methods

init login logout getConnectionState getCurrentUserId getClientResource getRestContext renewToken getRTCTokenInfo getUserIdsWithRTCUids getSelfIdsOnOtherPlatform getCacheManager getUploadAdapter getServerUrlsConfig getContactSnapshot addEventHandler removeEventHandler use sendMessage

Methods

Staticinit

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();

getRestContext

  • getRestContext(): RestContext

    获取当前登录会话的 REST 访问上下文，供 SDK 公开模块或扩展能力复用统一鉴权与地址信息。

    Returns RestContext

    返回当前登录会话对应的 REST 上下文。

    Example: 读取 REST 上下文。

    const context = client.getRestContext();

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();

getCacheManager

  • getCacheManager(): null | CacheManager

    获取当前登录会话绑定的缓存管理器实例。

    Returns null | CacheManager

    返回缓存管理器；未登录或缓存未初始化时返回 null。

    Example: 读取缓存管理器

    const cacheManager = client.getCacheManager();

getUploadAdapter

  • getUploadAdapter(): null | UploadAdapter

    获取当前平台适配层暴露的上传适配器。

    Returns null | UploadAdapter

    返回上传适配器；当前平台未提供时返回 null。

    Example: 读取上传适配器

    const uploadAdapter = client.getUploadAdapter();

getServerUrlsConfig

  • getServerUrlsConfig(): undefined | ServerUrlsConfig

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

    Returns undefined | ServerUrlsConfig

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

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

    const serverUrls = client.getServerUrlsConfig();

getContactSnapshot

  • getContactSnapshot(): null | ContactSnapshot

    获取当前好友快照缓存。

    Returns null | ContactSnapshot

    返回好友快照；若缓存未初始化则返回 null。

    Example: 读取好友快照

    const snapshot = client.getContactSnapshot();

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

sendMessage

  • sendMessage(message: Message, options?: SendMessageOptions): Promise<Message>

    发送消息。消息通常应通过 ChatManager 或 create*Message 系列方法先构造，再交给此方法发送。

    Parameters

    • message: Message

      必传。待发送的消息对象。message.sender.userId 必须与当前登录用户 ID 一致。

    • Optionaloptions: SendMessageOptions

      可选。发送配置项，例如进度回调函数。

    Returns Promise<Message>

    返回经过发送流程处理后的消息对象。

    Example: 发送消息

    const sent = await client.sendMessage(message);

    可能出现的错误码

    Code 含义 HTTP 处理建议 可重试
    1 消息发送已取消 - 确认 SDK 实例仍有效；如为用户主动取消，无需重试 否
    100 App Key 不合法 - 检查 SDK 初始化使用的 appKey 否
    110 参数无效 - 通过 ChatManager 的 create*Message 方法创建消息，确保发送者与当前用户一致，并检查附件数据和上传配置 否
    300 服务器不可达 - 等待连接成功后重试 是
    301 消息发送超时 - 检查网络连接后重试；重试前可根据 msgLocalId 查询业务侧发送状态 是
    303 消息发送失败 - 检查 details.serverCode 和 details.reason；若持续出现，请联系技术支持 否
    402 附件上传失败 - 检查文件、网络和上传权限后重试 是
    405 附件文件过大 - 压缩文件或更换更小的文件后重试 否
    406 附件内容不合规 - 更换合规文件后重试 否
    500 消息异常：编码失败 - 检查消息体、扩展字段和附件信息是否合法 否
    4 消息发送超过服务限制 - 降低发送频率、减少定向用户数量，或联系服务端提升配额 否
    108 Token 已过期 - 刷新 Token 并重新登录后发送 否
    202 消息发送鉴权失败 - 重新获取有效 Token 并登录 否
    210 无权限执行消息操作 - 检查账号权限、会话关系和服务开通状态 否
    213 当前登录态绑定到其他设备 - 检查多设备登录策略和设备绑定关系后重新登录 否
    214 登录设备数超过限制 - 退出其他设备或联系服务端提升设备数限制 否
    215 用户在群组或聊天室中被禁言 - 等待禁言解除或联系群组/聊天室管理员 否
    219 用户被全局禁言 - 联系管理员解除全局禁言 否
    220 当前登录设备发生变化 - 检查设备标识并重新登录 否
    221 非好友禁止发送消息 - 先添加对方为联系人，或调整应用的陌生人消息策略 否
    222 消息发送失败：被接收方拉黑 - 停止重试，并提示用户检查与接收方的关系状态 否
    305 消息服务不可用 - 检查控制台服务开通状态或联系技术支持 否
    501 消息包含违规内容 - 修改消息内容后重试 否
    505 相关消息服务未开通 - 在控制台开通对应服务后重试 否
    506 消息已过期 - 重新创建消息后发送 否
    507 当前用户不在消息白名单中 - 联系管理员将当前用户加入白名单 否
    508 消息被外部逻辑拦截 - 根据业务审核规则调整消息，或联系服务端排查 否
    509 消息发送过于频繁 - 降低发送频率后重试 是
    510 消息体超过大小限制 - 缩短消息内容、减少扩展字段或拆分消息后重试 否
    602 当前用户不在群组或聊天室中 - 加入目标群组或聊天室后重试 否
    603 无群组消息操作权限 - 检查群组角色和消息权限配置 否
    606 群组不存在 - 确认 groupId 正确且群组仍存在 否
    607 群组已禁用 - 恢复群组可用状态后重试 否
    1200 第三方内容审核拒绝 - 修改消息内容后重试 否
    1299 第三方服务拒绝消息 - 检查 details.reason，并联系对应第三方服务排查 否

Settings

Member Visibility

On This Page

Methods