IM SDK Web API 文档 — v5.1.0

IM SDK Web 是面向 Web 与跨平台 JavaScript 运行时的即时通讯 SDK。下表按功能模块汇总当前公开 API;点击 API 名称可查看完整参数、返回值、示例及错误码。

类或管理器 说明
ChatClient 聊天 SDK 的入口,提供初始化、登录和登出方法,并管理 SDK 与聊天服务器之间的连接。
ChatManager 通过 client.chatManager 使用,提供消息创建、发送与接收、会话管理、历史消息查询、回执和附件下载等方法。
Message 消息类型,定义消息发送者、会话、消息体、发送状态和扩展属性。
ConversationItem 会话类型,定义会话标识、会话类型、未读数、最后一条消息和置顶等属性。
ContactManager 通过 client.contactManager 使用,提供联系人、好友申请、好友备注和黑名单管理方法。
GroupManager 通过 client.groupManager 使用,提供群组创建、查询、加入、解散和成员权限管理等方法。
Group 绑定到指定 groupId 的群组实体。通过 client.groupManager.getGroup(groupId) 获取后,调用该实体上的方法操作对应群组。
ChatRoomManager 通过 client.chatRoomManager 使用,提供聊天室查询、加入、退出以及成员权限管理方法。
ChatRoom 绑定到指定 chatRoomId 的聊天室实体。通过 client.chatRoomManager.getChatRoom(chatRoomId) 获取后,调用该实体上的方法操作对应聊天室。
PresenceManager 通过 client.presenceManager 使用,提供用户在线状态发布、订阅和查询方法。
ChatThreadManager 通过 client.chatThreadManager 使用,提供 ChatThread 创建、解散、查询和成员管理方法。
ChatThread 绑定到指定 chatThreadId 的消息话题实体。通过 client.chatThreadManager.getChatThread(chatThreadId) 获取后,调用该实体上的方法操作对应消息话题。
PushManager 通过 client.pushManager 使用,提供离线推送 token、免打扰和推送语言配置方法。
UserInfoManager 通过 client.userInfoManager 使用,提供用户属性获取、更新、订阅和取消订阅方法。

下表方法直接通过 client 调用。ChatClient 是 SDK 主入口,负责初始化、登录、连接生命周期、事件监听和 Manager 注册。

API 名称 API 描述 起始版本
init 初始化 ChatClient 单例。首次调用时创建实例;后续若使用相同配置调用,将复用该实例,并支持追加注册管理器。 V5.0.0
login 登录并建立到消息服务的长连接。登录成功后会恢复本地缓存、同步会话列表,并按配置触发好友列表与用户属性同步。 V5.0.0
logout 登出并关闭当前连接,同时清理登录态、运行时缓存引用与日志上报状态。 V5.0.0
getConnectionState 获取当前连接状态。 V5.0.0
getCurrentUserId 获取当前登录用户 ID。 V5.0.0
getClientResource 获取当前连接的设备资源标识。 V5.0.0
renewToken 更新当前登录会话的 IM token,并重置 token 生命周期提醒。 V5.0.0
getRTCTokenInfo 获取当前用户的 RTC token 信息。 V5.0.0
getUserIdsWithRTCUids 批量查询映射到 RTC UID 的 IM 用户 ID。 V5.0.0
getSelfIdsOnOtherPlatform 获取当前用户在其他已登录设备上的登录 ID 列表。登录 ID 由 user ID + "/" + resource (设备的识别号)组成。 V5.0.0
getServerUrlsConfig 获取当前固定的服务地址配置;仅在初始化时传入了 serviceConfig.serverUrls 才会返回有效值。 V5.0.0
addEventHandler 注册 ChatClient 事件处理器,用于监听连接、消息、好友、群组等 SDK 公开事件。 V5.0.0
removeEventHandler 移除指定的 ChatClient 事件处理器。 V5.0.0
use 注册一个管理器构造器,并返回带该管理器类型增强的 ChatClient 实例。 V5.0.0

下表方法通过 client.chatManager 调用,提供消息创建、收发、查询、回执、翻译以及会话管理 API。

API 名称 API 描述 起始版本
sendMessage 发送一条已创建的消息。文本、图片、文件、语音、视频、位置、命令、自定义和合并消息均通过该入口发送。 V5.0.0
createTextMessage 创建文本消息对象。创建后需调用 sendMessage 发送。 V5.0.0
createImageMessage 创建图片消息对象。支持传入本地文件或远程图片地址。 V5.0.0
createFileMessage 创建文件消息对象。支持传入本地文件或远程文件地址。 V5.0.0
createVoiceMessage 创建语音消息对象。支持传入本地语音文件或远程语音地址。 V5.0.0
createVideoMessage 创建视频消息对象。支持传入本地视频文件或远程视频地址。 V5.0.0
createLocationMessage 创建位置消息对象。 V5.0.0
createCmdMessage 创建命令消息对象。命令消息通常用于业务自定义控制信令。 V5.0.0
createCustomMessage 创建自定义消息对象。可通过 eventparams 承载业务自定义内容。 V5.0.0
createCombineMessage 创建合并消息对象,用于发送聊天记录合集。 V5.0.0
getConversationList 从本地会话列表缓存中获取会话,支持通过 filter 过滤。 V5.0.0
setCurrentConversation 设置当前正在浏览的会话。设置后,该会话收到在线消息时 SDK 仍会更新最后消息和列表排序,但不会累加本地未读数。该状态只保存在当前 SDK 会话内存中,切换页面或关闭会话时应调用 resetCurrentConversation() V5.0.0
resetCurrentConversation 重置当前正在浏览的会话。重置后,收到在线消息会按默认规则累加对应会话的本地未读数。 V5.0.0
getCurrentConversation 获取当前正在浏览的会话。 V5.0.0
deleteConversation 删除指定会话,可选择同时删除服务端漫游消息。 删除成功后,SDK 会同步删除本地会话列表缓存;如果本地会话列表发生变化,会触发 onConversationListUpdatereasonlocal V5.0.0
setConversationPinned 设置或取消设置会话置顶状态。 V5.0.0
addConversationMark 为单个或多个会话添加标记。 V5.0.0
removeConversationMark 从单个或多个会话移除标记。 V5.0.0
clearAllMessagesAndConversations 清空当前用户的所有会话和服务端漫游消息。 清空成功后,SDK 会同步清空本地 conversation/session-list 缓存;如果本地会话列表发生变化,会触发 onConversationListUpdatereasonlocal V5.0.0
pinMessage 在指定会话中置顶一条消息。 V5.0.0
unpinMessage 取消置顶指定会话中的一条消息。 V5.0.0
getPinnedMessageList 获取指定会话内的置顶消息列表。该接口不分页,不接收 messageId,最多返回 20 条。 V5.0.0
addEventHandler 注册消息域事件处理器。 V5.0.0
removeEventHandler 移除已注册的消息域事件处理器。 V5.0.0
clearConversationUnreadMessageCount 清空指定会话的未读消息数。 V5.0.0
sendMessageReadReceipts 批量发送消息已读回执。仅支持同一个会话内的 1 至 50 条单聊或群聊消息。 V5.0.0
clearAllConversationUnreadMessageCount 清空所有会话的未读消息数。 V5.0.0
recallMessage 撤回一条已发送消息。 V5.0.0
modifyMessage 编辑一条消息内容。当前仅支持文本消息和自定义消息。 V5.0.0
getHistoryMessages 从服务端获取历史消息。 V5.0.0
searchMessages 服务端消息搜索,根据关键词和过滤条件搜索历史消息。 V5.0.0
downloadAttachment 下载消息附件,适用于图片、语音、视频和文件等附件消息。 V5.0.0
downloadAndParseCombineMessage 下载并解析合并消息内容,返回合并消息中的子消息列表。 V5.0.0
removeHistoryMessages 删除服务端历史消息,可按消息 ID 列表或时间戳删除。 V5.0.0
getGroupMessageReadUsers 获取指定群消息的已读成员列表。 V5.0.0
getGroupMessageReadReceipts 批量获取群消息已读回执详情。 V5.0.0
addReaction 为消息添加 Reaction。 V5.0.0
removeReaction 删除当前用户在消息上添加的 Reaction。 V5.0.0
getReactionList 获取一条或多条消息的 Reaction 汇总列表。 V5.0.0
getReactionDetail 获取指定消息 Reaction 的用户详情。 V5.0.0
getSupportedTranslationLanguages 获取翻译服务支持的语言列表。 V5.0.0
translateMessage 翻译文本消息内容到一个或多个目标语言。 V5.0.0
voiceMessageToText 将已发送或已接收的语音消息体转为文字。 V5.0.0
voiceFileToText 上传本地语音文件并转换为文字。 V5.0.0

下表方法通过 client.chatThreadManager 调用,提供消息话题创建、查询、成员管理、生命周期操作和事件监听 API。

API 名称 API 描述 起始版本
addEventHandler 注册 ChatThread 事件处理器。 V5.0.0
removeEventHandler 移除指定的消息话题事件处理器。 V5.0.0
getChatThread 获取绑定指定 chatThreadId 的 ChatThread 实体对象。 V5.0.0
createChatThread 创建消息话题。 V5.0.0
getChatThreadList 查询指定群组下的消息话题列表。 V5.0.0
getJoinedChatThreadList 查询当前用户已加入的消息话题列表。 V5.0.0
getChatThreadInfo 查询消息话题详情。 V5.0.0
joinChatThread 加入消息话题。 V5.0.0
leaveChatThread 退出消息话题。 V5.0.0
destroyChatThread 解散消息话题。 V5.0.0
updateChatThreadName 更新消息话题名称。 V5.0.0
getChatThreadMemberList 查询消息话题成员列表。 V5.0.0
removeChatThreadMember 从消息话题移除成员。 V5.0.0
getChatThreadLastMessageList 批量查询消息话题最后一条消息。 V5.0.0

ChatThread 是绑定到指定 chatThreadId 的消息话题实体。通过 client.chatThreadManager.getChatThread(chatThreadId) 获取后,使用下表方法操作该消息话题。

API 名称 API 描述 起始版本
getInfo 获取当前子区详情。 V5.0.0
refresh 刷新并返回当前子区详情,等价于 getInfo() V5.0.0
join 加入当前子区。 V5.0.0
leave 退出当前子区。 V5.0.0
destroy 解散当前子区。 V5.0.0
updateName 更新当前子区名称。 V5.0.0
getMemberList 获取当前子区成员列表。 V5.0.0
removeMember 从当前子区移除成员。 V5.0.0

下表方法通过 client.chatRoomManager 调用,提供聊天室查询、加入、成员与权限管理、公告和自定义属性 API。

API 名称 API 描述 起始版本
addEventHandler 注册聊天室事件处理器,事件包括成员进出、禁言、allowlist、公告和属性变更等。 V5.0.0
removeEventHandler 移除指定 ID 的聊天室事件处理器。 V5.0.0
getChatRoomList 分页获取公开聊天室列表,并尽量补齐聊天室所有者资料。 V5.0.0
getChatRoom 获取绑定指定 chatRoomId 的单聊天室对象,便于后续在对象上调用成员、公告、属性等方法。 V5.0.0
joinChatRoom 加入指定聊天室。该方法通过长连接聊天室操作发送加入请求。 V5.0.0

ChatRoom 是绑定到指定 chatRoomId 的聊天室实体。通过 client.chatRoomManager.getChatRoom(chatRoomId) 获取后,使用下表方法操作该聊天室。

API 名称 API 描述 起始版本
getInfo 获取当前聊天室详情。 V5.0.0
refresh 刷新并返回当前聊天室详情,等价于 getInfo() V5.0.0
updateInfo 更新当前聊天室名称、描述或最大成员数。 V5.0.0
leaveChatRoom 退出当前聊天室。 V5.0.0
getMembers 获取当前聊天室成员列表。 V5.0.0
removeMembers 从当前聊天室移除成员。 V5.0.0
getAdminList 获取当前聊天室管理员列表。 V5.0.0
addAdmin 将用户设置为当前聊天室管理员。 V5.0.0
removeAdmin 移除当前聊天室管理员。 V5.0.0
getMuteList 获取当前聊天室禁言列表。 V5.0.0
muteMembers 禁言当前聊天室成员。 V5.0.0
unmuteMembers 解除当前聊天室成员禁言。 V5.0.0
muteAllMembers 开启当前聊天室全员禁言。 V5.0.0
unmuteAllMembers 关闭当前聊天室全员禁言。 V5.0.0
checkIfInMuteList 查询当前用户是否在当前聊天室禁言列表中。 V5.0.0
getBlocklist 获取当前聊天室黑名单。 V5.0.0
blockMembers 将成员加入当前聊天室黑名单。 V5.0.0
unblockMembers 从当前聊天室黑名单移除成员。 V5.0.0
getAllowlist 获取当前聊天室 allowlist。 V5.0.0
addUsersToAllowlist 将用户加入当前聊天室 allowlist。 V5.0.0
removeUsersFromAllowlist 从当前聊天室 allowlist 移除用户。 V5.0.0
checkIfInAllowList 查询当前用户是否在当前聊天室 allowlist 中。 V5.0.0
getAnnouncement 获取当前聊天室公告。 V5.0.0
updateAnnouncement 更新当前聊天室公告。 V5.0.0
getAttributes 获取当前聊天室属性。 V5.0.0
setAttributes 设置当前聊天室属性。 V5.0.0
removeAttributes 删除当前聊天室属性。 V5.0.0

下表方法通过 client.contactManager 调用,提供联系人、好友申请、好友备注、黑名单和联系人事件 API。

API 名称 API 描述 起始版本
getContacts 获取当前内存中的联系人列表视图。 V5.0.0
addContact 发送联系人申请。 V5.0.0
deleteContact 删除联系人,并立即修补当前会话中的联系人快照。 V5.0.0
acceptContactInvite 接受联系人申请,并触发受控联系人刷新。 V5.0.0
declineContactInvite 拒绝联系人申请。 V5.0.0
setContactRemark 设置联系人备注,允许传入空字符串以清空备注;设置成功后会同步刷新已有单聊会话的显示名称。 V5.0.0
getBlocklist 获取当前用户的黑名单列表。 V5.0.0
addUsersToBlocklist 批量添加黑名单用户,重复值会在请求前去重并保持原始顺序。 V5.0.0
removeUserFromBlocklist 批量移除黑名单用户,重复值会在请求前去重并保持原始顺序。 V5.0.0
addEventHandler 注册联系人事件处理器,用于接收联系人关系事件;自动同步进度请在 ChatClient 级监听统一同步事件。 V5.0.0
removeEventHandler 移除已注册的联系人同步事件处理器。 V5.0.0

下表方法通过 client.groupManager 调用,提供群组查询、创建、加入、成员与权限管理、公告和共享文件 API。

API 名称 API 描述 起始版本
addEventHandler 注册群组事件处理器。 V5.0.0
removeEventHandler 移除群组事件处理器。 V5.0.0
createGroup 创建群组,可指定初始成员、公开属性、入群审批、邀请策略与最大人数。 V5.0.0
getJoinedGroupList 读取当前用户已加入群组的本地同步列表;该方法只读本地缓存和当前会话运行时数据,不发起网络请求。 V5.0.0
getGroup 获取绑定指定群 ID 的单群操作对象;该方法不发起网络请求。 V5.0.0
getGroupInfo 从服务端获取单个群组详情。 V5.0.0
getGroupInfoList 批量获取多个群组详情。 V5.0.0
joinGroup 申请加入或直接加入指定群组,取决于群组入群审批配置。 V5.0.0
inviteUsersToGroup 邀请用户加入指定群组。 V5.0.0
acceptGroupJoinRequest 同意用户的入群申请。 V5.0.0
rejectGroupJoinRequest 拒绝用户的入群申请。 V5.0.0
acceptInvitation 接受当前用户收到的群组邀请。 V5.0.0
rejectInvitation 拒绝当前用户收到的群组邀请。 V5.0.0

Group 是绑定到指定 groupId 的群组实体。通过 client.groupManager.getGroup(groupId) 获取后,使用下表方法操作该群组。

API 名称 API 描述 起始版本
getSummary 读取当前会话或本地预览中已知的已加入群轻量摘要。该方法不会发起网络请求,返回结果也不等同于完整群组详情。 V5.0.0
getDetail 获取当前群组详情。该方法会优先复用当前会话中的可用快照,必要时再从服务端拉取最新数据。 V5.0.0
refresh 强制从服务端拉取并刷新当前群组详情。 V5.0.0
updateInfo 更新当前群组的基础资料,例如群组名称、群组描述、头像或扩展信息。 V5.0.0
updateConfigs 更新当前群组的配置,例如是否公开、入群审批方式、普通成员邀请权限以及群成员人数上限。 V5.0.0
changeOwner 转让当前群组的所有权。 V5.0.0
destroy 解散当前群组。 V5.0.0
leave 当前登录用户主动退出群组。 V5.0.0
getMembers 分页获取当前群组的成员列表。 V5.0.0
removeMembers 从当前群组中移除指定成员。 V5.0.0
getAdmins 获取当前群组的管理员列表。 V5.0.0
addAdmin 添加群组管理员。 V5.0.0
removeAdmin 移除群管理员。 V5.0.0
getMuteList 获取当前群组的禁言列表。 V5.0.0
muteMembers 将当前群组中的指定成员加入禁言列表。 V5.0.0
unmuteMembers 解除当前群组中指定成员的禁言状态。 V5.0.0
muteAllMembers 开启当前群组的全员禁言。 V5.0.0
unmuteAllMembers 关闭当前群组的全员禁言。 V5.0.0
getBlocklist 获取当前群组的黑名单列表。 V5.0.0
blockMembers 将指定成员加入当前群组的黑名单。 V5.0.0
unblockMembers 将指定成员移出当前群组的黑名单。 V5.0.0
getAllowlist 获取当前群组的白名单列表。 V5.0.0
addUsersToAllowlist 将指定成员加入当前群组的白名单。 V5.0.0
removeUsersFromAllowlist 将指定成员移出当前群组的白名单。 V5.0.0
checkIfInAllowList 查询当前用户是否在当前群组的白名单中。 V5.0.0
checkIfInMuteList 查询当前用户是否在当前群组的禁言列表中。 V5.0.0
getAnnouncement 获取当前群组公告。 V5.0.0
updateAnnouncement 更新当前群组公告。 V5.0.0
getSharedFileList 分页获取当前群组的共享文件列表。 V5.0.0
uploadSharedFile 上传文件到当前群组的共享文件列表中。 V5.0.0
deleteSharedFile 删除当前群组中的共享文件。 V5.0.0
downloadSharedFile 下载当前群组中的共享文件。下载完成后,会通过回调返回 Blob 数据。 V5.0.0
setMemberAttributes 设置当前群组中指定成员的自定义属性,常用于设置群成员名片。 V5.0.0
getMembersAttributes 批量获取当前群组中多个成员的自定义属性。 V5.0.0

下表方法通过 client.presenceManager 调用,提供在线状态发布、订阅、查询和事件监听 API。

API 名称 API 描述 起始版本
addEventHandler 注册 Presence 事件处理器,用于接收在线状态变更推送。 V5.0.0
removeEventHandler 移除 Presence 事件处理器。 V5.0.0
publishPresence 发布当前用户的自定义在线状态,该状态会作为在线状态扩展描述信息保存并下发给订阅者。 V5.0.0
subscribePresence 订阅指定用户的在线状态。订阅成功后,这些用户在线状态变更时会触发 Presence 事件回调。 V5.0.0
unsubscribePresence 取消订阅指定用户的在线状态,成功后不再接收这些用户的在线状态变更事件。 V5.0.0
getSubscribedPresenceList 分页查询当前用户订阅了哪些用户的在线状态。 V5.0.0
getPresenceStatus 查询指定用户的当前在线状态,不会建立订阅关系。 V5.0.0

下表方法通过 client.pushManager 调用,提供推送 token、免打扰、提醒方式和推送语言管理 API。

API 名称 API 描述 起始版本
uploadPushToken 上传或覆盖设备 Push Token。成功时仅表示请求完成,不返回业务数据。 V5.0.0
setGlobalSilentMode 设置 App 级(全局)免打扰规则,支持提醒类型、持续时长、时间区间三种模式。 V5.0.0
getGlobalSilentMode 查询 App 级(全局)免打扰规则。 V5.0.0
setConversationSilentMode 设置单会话免打扰规则,仅支持单聊与群聊。 V5.0.0
getConversationSilentMode 查询单会话免打扰规则。 V5.0.0
clearConversationRemindType 清除会话提醒类型配置,恢复服务端默认提醒策略。 V5.0.0
getConversationSilentModes 批量查询多个会话的免打扰规则,单次最多 20 条。 V5.0.0
setPushLanguage 设置推送翻译语言。 V5.0.0
getPushLanguage 查询当前推送翻译语言。 V5.0.0
getConversationListByRemindType 分页查询已设置提醒类型的会话列表。 V5.0.0

下表方法通过 client.userInfoManager 调用,提供用户资料查询、订阅、更新和事件监听 API。

API 名称 API 描述 起始版本
addEventHandler 注册用户资料事件处理器,用于接收当前用户资料更新和订阅用户资料变更通知。 V5.0.0
removeEventHandler 移除指定 ID 的用户资料事件处理器,停止接收对应事件回调。 V5.0.0
getUserInfoByUserId 按用户 ID 查询用户资料属性;未指定属性时查询 SDK 默认资料字段。 V5.0.0
getUserInfoByAttribute 按用户 ID 和指定属性集查询用户资料,适合只读取昵称、头像等部分字段。 V5.0.0
subscribeUsersInfo 订阅指定陌生人用户的资料变化;订阅成功后可通过用户资料事件处理器接收变更通知。 V5.0.0
unsubscribeUsersInfo 取消订阅指定陌生人用户的资料变化;取消后不再接收这些用户的资料变更通知。 V5.0.0
getSubscribedUsers 查询当前用户已订阅资料变化的陌生人列表,并返回这些用户的标准化资料。 V5.0.0
updateOwnInfo 更新当前登录用户的一个或多个资料属性,例如昵称、头像、邮箱、手机号、签名或扩展字段。 V5.0.0
updateOwnInfoByAttribute 更新当前登录用户的单个资料属性,适合只修改昵称、头像等一个字段的场景。 V5.0.0