IM 即时通讯（SDK）
Android
Android SDK API
更新时间： 2023/07/14 10:35:14
本文介绍 Android SDK API 的概述性信息，并列出核心 API 与核心类或接口类，方便您查阅 API 信息。
SDK API 概述
点击查看 API 概述
接口类型
NIM Android SDK （以下简称 SDK）提供两种接口类，供开发者使用：
类型 |
说明 |
|---|---|
| 主动发起请求 | 接口名均以 Service 结尾，例如 AuthService |
| 作为观察者监听事件和变化 | 接口名均以 ServiceObserver 结尾，例如 AuthServiceObserver。个别太长的类名则直接以 Observer 结尾，例如 SystemMessageObserver。 |
- SDK 接口调用必须在主进程中进行，请在主进程中调用 SDK 的
XXXService提供的方法，在主进程中注册XXXServiceObserver的观察者（有事件变更，会回调给主进程的主线程）。 - 如果您的模块运行在非主进程，请自行实现主进程与非主进程的通信（
AIDL/Messenger/ContentProvider/BroadcastReceiver等 IPC 渠道）将主进程回调或监听返回的数据传递给非主进程。
返回值类型
SDK 提供三种接口返回值：
- 基本数据类型（同步接口）
InvocationFuture（异步接口）AbortableFuture（异步接口）：异步接口基本都从主进程发起调用，然后在后台进程执行，最后再将结果返回给主进程
如果调用 AbortableFuture 异步接口，传输大量数据或者出现耗时很长的情况，可通过 abort 方法中断请求。例如上传下载、登录等。
异步接口可通过 RequestCallback 和 RequestCallbackWrapper 两种方式设置回调函数。
| 异步接口回调函数 | 说明 |
|---|---|
RequestCallback |
需要实现三个接口： 成功 onSuccess, 失败 onFailed, 异常 onException |
RequestCallbackWrapper |
需要实现 onResult。封装了成功、失败和异常三个接口，在参数上进行区分 |
SDK API 调用框架
自 v4.4.0 起，API 调用框架增强：
- 支持带 Looper 的非 UI 线程发起的异步 API 调用，直接回调到调用者线程。v4.4.0 之前版本会默认回调到 UI 线程。
- 提供异步强制转成同步的接口：
NIMClient#syncRequest，允许设置最大同步等待时间，支持非 UI 线程里需要同步调用云信 API的场景。 - 添加自动生成的 NIM SDK 类，您可直接采用
NIMSDK#getXXXService方法获取服务接口，不再需要传递 XXXService.class，简化 API 调用方式。其他插件自动生成的调用入口类为：NIMChatRoomSDK、NIMLuceneSDK。例如采用NIMSDK.getAuthService().login()替换NIMClient.getService(AuthService.class).login()。
SDK API 参考
点此进入：Android SDK API 参考
SDK 核心 API
以下仅列出 SDK 的部分核心 API，如需查阅其他 SDK API 信息，请参考下文的SDK 核心类/接口类或者直接进入Android SDK API 参考查询 API 名称。
初始化与登录
| API | 说明 |
|---|---|
| init | 在 Application#onCreate 中初始化 SDK |
| config | 在 Application#onCreate 中进行初始化配置 |
| initSDK | 在 UI 进程主线程上按需进行初始化SDK，支持通过 SDKOptions#asyncInitSDK 配置为同步或异步初始化，并支持通过 SDKOptions#reducedIM 配置为弱 IM 模式，延迟加载push进程服务
|
| getService | 获取各服务接口，例如获取 MsgService |
| getStatus | 获取当前用户的登录状态（在线状态） |
| getCurrentAccount | 获取当前用户的 IM 账号（accid） |
| updateStrings | 当系统语言发生变化时，更新文案配置。配置不能立即生效，所有文案均需要在下次使用时才会生效 |
| getSdkStorageDirPath | 获取SDK数据目录路径，需要在初始化 SDK 之后调用 |
| getSDKVersion | 运行时获取当前 SDK 版本号 |
| login | 登录 IM |
| logout | 登出 IM |
| kickOtherClient | 将同时在线的其他设备端踢下线 |
消息（单聊与群聊）
| API | 说明 |
|---|---|
| createTextMessage | 构建一条文本消息, 构建后需调用 sendMessage 方法发送 |
| createImageMessage | 构建一条图片消息,构建后需调用 sendMessage 方法发送 |
| createAudioMessage | 构建一条语音消息, 构建后需调用 sendMessage 方法发送 |
| createVideoMessage | 构建一条视频消息, 构建后需调用 sendMessage 方法发送 |
| createFileMessage | 构建一条文件消息, 构建后需调用 sendMessage 方法发送 |
| createLocationMessage | 构建一条地理位置消息, 构建后需调用 sendMessage 方法发送 |
| createTipMessage | 构建一条提示消息, 构建后需调用 sendMessage 方法发送 |
| createCustomMessage | 构建一条自定义消息, 构建后需调用 sendMessage 方法发送 |
| createEmptyMessage | 构建一条空消息, 仅可设置聊天对象、会话类型和时间点，用于记录查询。构建后需调用 sendMessage 方法发送 |
| createForwardMessage | 构建一条转发消息，构建后需调用 sendMessage 方法发送 |
| createForwardMessageListFileDetail | 创建多条待合并转发的消息，构建后需调用 sendMessage 方法发送 |
| sendMessage | 发送消息，如果需要更新发送进度，请调用MsgServiceObserve#observeMsgStatus |
| saveMessageToLocalEx | 保存消息到本地数据库，但不发送到服务器端。用于应用保存本地提醒一类的消息。与其他 SDK API 的组合调用示例，可参见收发提示消息 |
| sendMessageReceipt | 发送单聊（P2P）消息的已读回执 |
| deleteMsgSelf | 单向删除多条消息 |
| updateIMMessage | 更新消息。目前只能更新本地扩展字段 LocalExtension |
| updateIMMessageStatus | 更新消息记录的状态。可更新：
|
| revokeMessage | 撤回消息，并设置相应的第三方推送配置（包括IOS平台的推送）与未读数变化 |
历史消息
| API | 说明 |
|---|---|
| clearServerHistory | 清空服务端的单聊历史消息 |
| deleteRangeHistory | 根据时间范围删除本地历史消息 |
| searchMessageHistory | 从本地消息数据库搜索消息历史 |
| queryMessageListByUuid | 通过 uuid 批量获取历史消息 |
| pullMessageHistoryEx | 从服务器拉取消息历史记录 |
| searchRoamingMsg | 云端聊天记录关键词查询 |
| queryLastMessage | 查询同指定用户的最近一条消息 |
消息扩展
| API | 说明 |
|---|---|
| replyMessage | 引用一条消息进行回复，形成消息回复树状结构（Thread） |
| queryThreadTalkHistory | 查询 Thread 聊天云端历史（支持单聊、群聊、超大群） |
| addQuickComment | 添加快捷评论，如表情等 reaction |
| removeQuickComment | 移除快捷评论 |
| queryQuickComment | 获取快捷评论列表 |
| addCollect | 将某条消息添加为收藏 |
| removeCollect | 批量移除收藏 |
| addMsgPin | PIN 一条消息 |
| updateMsgPin | 更新一条消息的 PIN |
| removeMsgPin | 移除一条消息的 PIN |
会话列表
| API | 说明 |
|---|---|
| queryRecentContacts | 查询最近联系人会话列表数据，可按时间逆序或者正序查询指定数量的最新会话列表数据 |
| queryMySession | 获取某一个会话 |
| updateRecentAndNotify | 更新一条最近联系人会话的属性，并会触发MsgServiceObserve#observeRecentContact(Observer, boolean)的通知 。 如果仅仅是想更新最近联系人会话但不想收到通知， 可调用MsgService#updateRecent(RecentContact) |
| deleteRecentContact | 删除最近联系人记录 |
| createEmptyRecentContact | 创建一条空的联系人会话 |
| getTotalUnreadCount | 获取未读数总数 |
| queryUnreadMessageList | 根据会话ID和会话类型查找未读消息列表 |
| clearUnreadCount | 将指定会话类型的未读数清零(标记已读) |
| queryCollect | 从服务的分页查询收藏列表 |
| addStickTopSession | 添加一个置顶会话 |
| removeStickTopSession | 删除置顶会话 |
| updateStickTopSession | 更新一个置顶会话的扩展字段 |
| queryStickTopSessionBlock | 获取置顶会话信息的列表 |
离线推送与消息提醒
| API | 说明 |
|---|---|
| enable | 开启/关闭第三方离线推送服务 |
| setPushNoDisturbConfig | 设置推送免打扰时间 |
| setPushShowNoDetail | 设置离线推送是否不展示推送文案详情 |
| toggleNotification | 通知栏提醒开关控制。该方法只有在 SDKOptions#StatusBarNotificationConfig 配置不为空时调用才有效 |
群组
| API | 说明 |
|---|---|
| createTeam | 创建一个群组 |
| addMembersEx | 添加成员 |
| removeMember | 移除单个成员，只有群组创建者有此权限 |
| updateTeam | 更新群组资料 |
| dismissTeam | 解散群，只有群主有权限 |
| quitTeam | 退出群 |
| queryTeam | 查询群资料，如果本地没有群组资料，则去服务器查询。 |
| queryTeamList | 获取自己加入的群列表 |
| queryTeamListById | 根据群 ID 列表批量查询群信息 |
| searchTeam | 从服务器上查询群资料信息 |
| applyJoinTeam | 申请加入群 |
| passApply | 同意入群申请 |
| rejectApply | 拒绝入群申请 |
| addManagers | 添加管理员，仅群主有此权限 |
| removeManagers | 移除管理员，仅群主有此权限 |
| transferTeam | 转让群 |
| acceptInvite | 接受别人的入群邀请 |
| declineInvite | 拒绝别人的入群邀请 |
| queryMemberList | 获取指定群的成员信息列表 |
| muteTeamMember | 禁言或解除禁言 |
| muteAllTeamMember | 对整个群禁言或解除禁言，对普通成员生效，只有群主和管理员有权限 |
| queryMutedTeamMembers | 查询被禁言群成员列表 |
| sendTeamMessageReceipt | (群消息接收方)标记群组消息已读 |
超大群
| API | 说明 |
|---|---|
| addMembers | 添加超大群成员 |
| removeMembers | 移出超大群的群成员，只有群主有权限 |
| quitTeam | 退出超大群 |
| transferTeam | 转让超大群 |
| applyJoinTeam | 申请加入超大群 |
| passApply | 同意入群申请 |
| rejectApply | 拒绝入群申请 |
| acceptInvite | 接受别人的入群邀请 |
| declineInvite | 拒绝别人的入群邀请 |
| addManagers | 添加管理员，仅群主有此权限 |
| removeManagers | 移除管理员，仅群主有此权限 |
| muteTeamMembers | 禁言或解除禁言 |
| muteAllTeamMember | 对整个群禁言或解除禁言，对普通成员生效，只有群主和管理员有权限 |
| queryMutedTeamMembers | 查询被禁言群成员列表 |
| updateTeam | 更新超大群的资料 |
| queryTeamList | 获取自己已加入的超大群列表 |
| sendMessage | 在超大群里发送消息 |
| revokeMessage | 撤回超大群消息 |
| replyMessage | 引用一条超大群消息进行回复，形成回复树状结构（Thread） |
| clearUnreadCount | 将指定超大群的未读数清零(标记已读) |
聊天室
| API | 说明 |
|---|---|
| enterChatRoomEx | 进入聊天室 |
| getEnterErrorCode | 获取进入聊天室失败的错误码 |
| exitChatRoom | 退出聊天室 |
| sendMessage | 在聊天室内发送消息 |
| pullMessageHistoryEx | 获取聊天室历史消息 |
| getMessagesByTags | 按标签从云端拉取聊天室消息，每一个标签代表的是某个标签化分组下的聊天室成员 |
| kickMember | 将特定成员踢出聊天室 |
| fetchRoomMembers | 获取聊天室成员信息 |
| fetchRoomMembersByIds | 根据用户的 IM 账号（accid）获取聊天室成员信息 |
| markChatRoomBlackList | 将用户添加或移出聊天室黑名单 |
| markChatRoomMutedList | 将用户添加到禁言名单或取消禁言 |
| markChatRoomTempMute | 设置聊天室成员临时禁言 |
| markNormalMember | 将用户设为聊天室普通成员，或取消其普通成员角色 |
| markChatRoomManager | 将用户设为聊天室管理员，或取消其聊天室管理员角色 |
| markChatRoomTempMuteByTag | 禁言某个标签的用户的发言，只有管理员或创建者能操作。 |
| updateMyRoomRole | 更新本人在聊天室内的信息 |
| updateRoomInfo | 更新聊天室信息 |
| updateQueue | 加入或者更新聊天室队列的元素。聊天室队列指聊天室（房间）中由多个元素（key-value 键值对）构成的队列，应用于直播间中的连麦队列场景和礼物队列展示等涉及队列化展示的场景，其中的元素可以是麦位、礼物展示位等 |
| batchUpdateQueue | 批量更新聊天室队列的元素 |
| pollQueue | 取出聊天室队列的头部元素或者其他指定元素 |
| fetchQueue | 排序列出聊天室队列的所有元素 |
| dropQueue | 删除聊天室队列 |
圈组
圈组的 SDK API 数量较多，请前往下文的圈组核心类/接口类查阅圈组的 SDK API。
用户资料
| API | 说明 |
|---|---|
| fetchUserInfo | 从服务器获取用户资料 |
| getAllUserInfo | 获取本地数据库中所有用户资料 |
| updateUserInfo | 更新本人的用户资料 |
| searchUserInfosByKeyword | 搜索与关键字匹配的所有用户 |
好友关系
| API | 说明 |
|---|---|
| addFriend | 添加好友 |
| ackAddFriendRequest | 同意/拒绝好友请求 |
| ackAddFriendRequest | 同意/拒绝好友请求 |
| deleteFriend | 删除好友 |
| getFriendAccounts | 获取我的所有好友账号 |
| addToBlackList | 将用户添加至黑名单 |
| searchFriendsByKeyword | 搜索与关键字匹配的所有好友 |
SDK 核心类/接口类
以下仅列出 SDK 的核心类和接口类，如需查阅其他类或接口类的信息，请进入Android SDK API 参考搜索与查阅。
初始化与登录相关
| 类/接口 | 说明 |
|---|---|
| NIMClient | SDK 核心类，提供初始化 SDK，获取各个服务能力接口，获取当前状态等接口 |
| SdkLifecycleObserver | SDK 生命周期观察者接口类，提供监听主进程初始化状态的接口 |
| MiscService | 杂项接口类，提供日志文件上传、SDK 本地缓存、获取云信服务端时间等接口 |
| AuthService | 用户认证服务接口类，提供用户登录登出业务相关接口 |
| AuthServiceObserver | 用户认证服务观察者接口类，提供用户登录登出相关监听接口 |
消息（单聊 & 群聊）与会话相关
| 类/接口 | 说明 |
|---|---|
| MessageBuilder | 云信 IM 消息构造器，提供构建各类型消息的接口 |
| MsgService | 云信消息服务接口类，提供消息发送、消息查询、历史消息、消息扩展功能、获取未读数、已读回执、会话列表等相关接口 |
| MsgServiceObserve | 云信 IM 消息服务观察者接口类，提供消息、会话等的监听接口 |
| AudioRecorder | 高清语音录制工具类，提供语音录制相关接口 |
| AudioPlayer | 和AudioRecorder对应音频播放器，提供语音播放相关接口 |
| NosService | 网易云存储服务（NOS）接口类，提供云存储相关接口 |
| SystemMessageService | 云信 IM 系统通知接口类，提供系统通知查询和管理接口 |
| SystemMessageObserver | 云信 IM 系统通知观察者接口类，提供系统通知相关监听接口 |
| LuceneService | 全文检索接口类，提供会话检索相关接口 |
第三方离线推送相关
| 类/接口 | 说明 |
|---|---|
| MixPushService | IM 的第三方离线推送服务接口类，提供 IM 的第三方离线推送服务相关配置接口 |
群组相关
| 类/接口 | 说明 |
|---|---|
| TeamService | 群组接口类，提供创建群组、添加群成员等群组操作相关接口 |
| TeamServiceObserver | 群组观察者接口类，提供监听群组成员变动、资料变动等的监听接口 |
超大群相关
| 类/接口 | 说明 |
|---|---|
| SuperTeamService | 超大群服务接口类，提供超大群成员管理、超大群消息发送、超大群资料管理等相关接口 |
| SuperTeamServiceObserver | 超大群观察者接口类，提供超大群监听接口 |
聊天室相关
| 类/接口 | 说明 |
|---|---|
| ChatRoomService | 聊天室服务接口类，提供进出聊天室、发送聊天室消息、聊天室成员管理、聊天室队列服务、聊天室标签等接口 |
| ChatRoomMessageBuilder | 聊天室消息构造器，提供构造各类型聊天室消息的接口 |
| ChatRoomServiceObserver | 聊天室观察者接口类， 提供聊天室监听接口 |
圈组相关
| 类/接口 | 说明 |
|---|---|
| QChatService | 圈组接口类，提供圈组登录登出相关接口 |
| QChatServerService | 圈组服务器接口类，提供圈组服务器相关接口，如果创建服务器、邀请服务器成员、查询服务器成员等 |
| QChatChannelService | 圈组频道接口类，提供圈组频道相关接口，如果创建频道、查询频道、查询频道未读信息等接口 |
| QChatMessageService | 圈组消息接口类，提供发送消息、撤回消息、发送消息正在输入事件等接口 |
| QChatServiceObserver | 圈组观察者接口类，提供圈组监听接口 |
| QChatPushService | 圈组的第三方离线推送服务接口类，提供圈组的第三方离线推送服务相关配置接口 |
| QChatMediaKit | 圈组多媒体频道接口类，提供圈组多媒体频道的初始化、连接、修改多媒体频道参数等接口 |
| QChatRTCChannelController | 圈组多媒体频道控制器，提供多媒体频道成员管理、摄像头切换、扬声器管理、视频画布设置等接口 |
| QChatRTCChannelListener | 圈组多媒体频道事件监听器，提供多媒体频道的监听接口 |
用户资料相关
| 类/接口 | 说明 |
|---|---|
| UserService | 用户资料操作相关接口，如更新本人的用户资料、搜索与关键字匹配的用户等 |
| UserInfoProvider | 用户信息提供者，由开发者提供用户信息给 SDK |
好友关系相关
| 类/接口 | 说明 |
|---|---|
| FriendService | 好友关系服务接口类，提供好友管理、好友关系、黑名单、消息提醒等相关接口 |
| FriendServiceObserve | 好友关系、黑名单变更等的监听接口 |
此文档是否对你有帮助？
有帮助
我要吐槽
