跳到主要内容

单群聊选型实践

本文基于融云 IMKit 能力，系统梳理应用接入单群聊社交场景时的常见需求，并提供对应的解决方案与实现指引。同时，本文也对可能遇到的问题及关键细节加以提示，帮助您快速理解业务逻辑，高效完成功能落地。如果您基于 IMLib 实现，可参考 IMLib 单群聊场景实践。

提示
  • 本文档主要针对单聊及普通群聊（限制人数 3000 人）场景。
  • 其他会话类型的详细介绍与区别，请参考会话类型说明（Android）。

SDK 选型（当前文档基于融云 IMKit 能力）​

若您需要在应用内集成融云即时通讯能力，需在 IMLib 与 IMKit 两款 SDK 间做出选择。融云 IM 客户端 SDK 提供丰富的组件与接口，大部分能力开箱即用，您可根据业务需求灵活选型。

融云 IM 支持单聊、群聊、超级群、聊天室等多种业务形态，配合 IM 服务端 API，可满足丰富的业务需求。

业务选型​

业务需求建议做法
需要将 IM 核心能力深度集成，基于业务有特定的 UI 展示需求，需要完全自定义 UI选择 IMLib：封装了通信核心能力和会话、消息等对象，不含任何 UI 组件，可给予您最大的灵活性。
希望快速上线，直接使用成熟的会话界面选择 IMKit：集成会话界面（UI），提供开箱即用的单聊、群聊能力，可大幅缩短开发周期。
需要快速上线，但需要对界面做一定定制选择 IMKit：通过丰富的 API 自定义界面功能，或使用官方插件扩展能力，在成熟 UI 基础上按需调整。

两款 SDK 对比​

特性IMLibIMKit
定位即时通讯能力库即时通讯界面库
UI 组件不含任何 UI集成会话界面、消息列表、用户托管页面等
支持业务单聊、群聊、聊天室、超级群单聊、群聊（超级群、聊天室无现成 UI）
灵活性极高，可完全自定义高，可定制或扩展
开发周期IMLib SDK 接入较快，UI 开发周期取决于业务需求较短
依赖关系独立使用依赖 IMLib

实现要点​

  1. 业务形态：单聊、群聊功能无需额外开通，创建应用后即可使用。
  2. 平台支持：IMLib 支持 Android、iOS、Web、HarmonyOS、Flutter、React Native、Unity、uni-app、小程序；IMKit 支持 Android、iOS、Web、HarmonyOS、Flutter、uni-app（Web 端需搭配 IMLib 5.x 使用）。
  3. 版本建议：各平台 IMLib 建议使用 5.x 系列；IMKit 对应 5.x 系列。HarmonyOS 建议使用当前最新版本 SDK。
  4. 包体积：集成前可查阅集成 SDK 后包体积增量文档，评估对安装包的影响。

选型 IMLib​

适用场景：深度集成 IM 能力、完全自研 UI、需要支持超级群或聊天室的自定义界面、跨平台（React Native / Unity / Flutter / uni-app）且无现成 IMKit 支持的场景。

实现方式：集成 IMLib SDK，自行实现会话列表、聊天界面、消息气泡等全部 UI，调用 IMLib 的会话、消息等 API 完成业务逻辑。可参考官方 Demo和部分 IMkit 开源代码 与客户端 API 文档。

文档：IMLib 开发指导（Android）（iOS / Web / 其他端请查看对应平台 IMLib 文档）

选型 IMKit​

适用场景：快速上线单聊、群聊功能；希望直接使用成熟会话 UI；在现有 UI 基础上做定制或扩展。

实现方式：集成 IMKit SDK（会自动引入 IMLib），直接使用会话列表、聊天界面等组件，通过配置和 API 自定义主题、消息展示、扩展功能等，无需从零实现聊天 UI。

文档：IMKit 开发指导（Android）（iOS / Web / 其他端请查看对应平台 IMKit 文档）

源码：源码获取地址

目前融云针对 Android、iOS、Flutter 及 uni-app 平台的 IMKit SDK 均已开源。您可以通过官方渠道获取源码进行集成和二次开发。

注意

若在源码基础上进行修改，后续升级 SDK 版本时将面临较高的合并成本，排查问题也会更加复杂。同时，由于代码经过定制，官方技术支持团队将无法为修改后的源码提供直接的技术保障和问题排查支持。请在集成前综合评估长期维护的投入。

准备工作​

创建应用与数据中心选型指南​

注册开发者账号​

  1. 访问融云控制台注册您的开发者账号。注册成功后，控制台会自动在开发环境中为您创建一个应用。
  2. 在控制台的密钥管理页面，获取您的应用在开发环境的 App Key。您可在密钥管理页面查看应用的信息，如 App Key、App Secret、所属数据中心（默认为北京）。

(height=500)

创建新应用（含数据中心选择）​

如果您的应用在海外上线且用户主要在海外，在创建应用前，您可以根据消息传输需求及合规要求，选择适合您业务的海外数据中心。 文档：海外数据中心使用指南

业务场景推荐数据中心说明
国内业务中国（北京）默认选项，用户主要在中国大陆
出海业务（东南亚）新加坡用户主要分布在东南亚地区
出海业务（北美）北美（俄勒冈）用户主要分布在北美地区
出海业务（中东）沙特用户主要分布在中东地区
全球化业务根据主用户群选择选择用户最集中的区域对应的数据中心

创建方式​

  1. 打开融云控制台应用管理页面。
  2. 单击创建应用。您将在创建应用的弹窗中选择数据中心。
  3. 在创建应用对话框中输入您的应用名称、应用简介、应用类型、运营阶段、数据中心。

(height=500)

提示
  • 每个应用均拥有两个不同的 App Key，分别对应开发环境与生产环境，且两个环境之间数据相互隔离。在您的应用正式上线前，建议切换到生产环境的 App Key，以便完成上线前全流程测试和最终发布。
  • 应用创建后，数据中心不可修改（不支持跨数据中心迁移和上线），请谨慎选择。

用户介绍​

App 用户需要接入融云服务才能使用即时通讯功能。对于融云来说，用户是指持有由融云分发的有效 Token、接入并使用即时通讯服务的 App 用户。同一个用户可能拥有多个有效的访问令牌（Token），这些令牌均可用于登录系统。在进行限制时，系统以用户为单位进行控制，而不是以单个令牌为单位。令牌的失效机制基于时间，即可以将指定时间之前的 Token 作废。

注册用户​

应用服务端（App Server）应向融云服务端提供 App 用户的用户 ID（userId），以换取唯一用户 Token。对融云来说，这个以 userId 获取 Token 的步骤即注册用户，且必须通过调用 Server API 来完成。

为方便您快速体验测试，您也可以在创建应用后，前往控制台的密钥管理页面，在 管理测试用户 区域输入用户 ID，点击 获取 Token 生成用户 Token。

应用客户端必须持有有效 Token，才能成功连接到融云服务端，使用融云即时通讯服务。

注册用户数限制

  • 开发环境?中的注册用户数上限为 100 个。
  • 在 生产环境?中，升级为 IM 旗舰版或 IM 尊享版后不限制注册用户数。

多端同时在线​

多端同时在线是指同一用户账号从多个平台同时连接到融云即时通讯服务的功能。默认情况下，融云支持多端设备同时在线（同一用户账号可在移动端、Web 端、桌面端、小程序端最多一个设备上同时在线），该功能无需开通即可使用。

默认多端设备之间不会进行消息同步。例如 Web 端与移动端同时登录，Web 端接收到消息后，移动端不会再接收到该消息。如需多端同步，请开通多设备消息同步服务。

多端登录限制说明​

默认的情况下，同一用户账号可在移动端、Web 端、桌面端、小程序端最多一个设备上同时在线。

平台类别限制IM SDK 支持平台列表
移动端默认仅支持一个移动端设备连接。如需支持移动端多设备登录 ，请[提交工单]咨询详情。Android、iOS、HarmonyOS
桌面端默认仅支持一个桌面端设备连接。Electron 框架（通过 Web 端 SDK 的 Electron 模块支持）
Web 端默认仅支持一个 Web 页面连接（每个浏览器标签页认为是一个连接）。在控制台自助开通多设备消息同步服务后，自动支持多 Web 页面连接。Web
小程序端默认仅支持一个小程序连接。如需支持小程序多设备登录 ，您可以在需先按控制台内嵌指南嵌入到管理后台的 IM 服务功能配置页面（page_code: im_service_config）中，进入 多端，开通小程序多端服务。小程序

导入 SDK​

在开始之前，请确保已创建应用并完成客户端 SDK 集成（Android）中（iOS / Web / 其他端请查看对应平台文档中的「SDK 集成」章节）。

IMKit 用户信息展示方式选型​

若您需要在 IMKit 的会话列表、会话页面等 UI 中展示用户资料（昵称、头像）和群组信息，可按下表选择实现方式。

IMKit 支持两种用户信息展示方式：用户信息提供者代理方式（默认）和信息托管方式（5.12.0 起）。二者在数据来源、更新机制及接入复杂度上不同，请根据业务需求选型后按对应方式接入。

业务选型​

业务需求建议做法
已有用户中心，用户信息完全在 App 服务端维护，希望 IMKit 按需从自有接口拉取并展示用户信息提供者代理方式：通过代理方式向 IMKit 提供用户信息；数据由应用层主动提供并可选缓存到本地。
希望用户改完资料后，好友、订阅用户等自动看到最新昵称、头像，不想自建同步逻辑信息托管方式：将用户资料托管到融云，由融云向好友或订阅关系用户推送更新；会话页优先展示消息体中的用户信息，其次为托管信息。

方式一：用户信息提供者代理方式​

实现方式：应用层主动从 App 服务端获取用户信息、群组信息、群成员用户信息，并通过 SDK 提供的设置方式提供给 IMKit。融云服务端注册获取 Token 时传入的用户昵称及头像仅用于推送，不用于 IMKit 会话展示。

适用场景：已有成熟用户体系、希望数据完全在自有业务侧维护的业务。

参考文档：用户信息（Android IMKit） ｜ 用户信息（iOS IMKit） ｜ 用户信息（Web IMKit） ｜ 用户信息（HarmonyOS IMKit）（其他端请查看对应平台文档中的「用户信息」章节）。

方式二：信息托管方式​

实现方式：将用户、群组、群成员等信息托管到融云，会话列表和会话页面从融云托管接口获取数据并缓存在内存中。会话页优先展示消息体中携带的用户信息，其次为托管信息。仅好友或订阅关系的用户会实时更新。

适用场景：希望资料变更后，好友、订阅用户等自动看到最新信息，无需自建同步逻辑的业务。

接入要点：

  1. 开通与切换：信息托管服务默认已开通，无需额外配置。通过以下代码切换到托管模式：
Java
RongUserInfoManager.getInstance().setDataSourceType(RongUserInfoManager.DataSourceType.INFO_MANAGEMENT);
  1. 数据来源：切换后，会话列表和会话页从融云 lib 信息托管接口取数据，取到后缓存到内存；内存中的信息在应用生命周期内有效。

参考文档：信息托管概述（Android IMKit） ｜ 信息托管概述（iOS IMKit）

黑名单管理​

本节帮助您根据业务需求选择使用用户白名单、用户黑名单或好友关系管理（融云托管）来实现单聊消息限制能力。相关 UI 需要业务侧实现。

默认情况下，App Key 下所有用户均已开启用户黑名单服务。在即时通讯服务端建立黑名单关系的同时，在自有应用服务器维护一份黑名单数据，便于业务查询与统计。

如使用融云提供的好友关系管理服务，默认非好友间也可以正常发送消息。如需要限制为仅好友可以发送消息，可以在需先按控制台内嵌指南嵌入到管理后台的 IM 服务功能配置页面（page_code: im_service_config）中，进入 好友 > 仅好友可以相互发送单聊消息，开启该功能。

业务选型​

要点说明
默认所有人可聊，少数人可以「拉黑」不想聊的人黑名单
默认所有人不可聊，只有加好友或加入白名单的人才能互相发单聊白名单 / 仅好友可以相互发送单聊消息
您的单聊默认规则是什么？
         │
         ├── 默认「所有人可以互相发单聊」
         │         │
         │         └── 选【黑名单】
         │               （用户通过拉黑排除不想聊的人）
         │
         └── 默认「只有好友/指定人才可以发单聊」
                   │
                   └── 选【白名单/加好友】
                         （用户通过加好友/加白名单开放聊天权限）中

能力与限制​

要点说明
人数上限均为 3000 个用户
黑名单与白名单互斥黑名单与白名单服务不能同时开启。开启白名单后黑名单功能失效，原黑名单数据保留，关闭白名单后仍可恢复。
单向拉黑拉黑为单向操作：您拉黑用户 A 后，A 无法向您发单聊（会收到 405 错误），您仍可向 A 发消息，A 可正常接收。
提示
  • 服务端 API 发送单聊消息默认不校验黑名单。若需受黑名单限制，请在调用时设置参数 verifyBlacklist = 1。
  • 用户白名单服务：也可限制单聊消息，按「发件人是否在白名单内」过滤；仅白名单内用户的消息可送达当前用户。详见用户白名单服务概述。

文档：从服务端管理黑名单 | 从客户端管理黑名单（Android）（iOS / Web / 其他端请查看对应平台文档中的「黑名单管理」章节） | 单聊用户白名单概述

在线状态​

若您需要在应用内展示用户在线、离线（如会话列表绿点、联系人状态），或基于在线状态做业务逻辑（如优先推荐在线用户、约课选在线讲师），可按以下方式接入。

融云会自动上报用户的连接状态（在线、离线），您只需选择如何接收这些状态：通过服务端回调推送到您的业务服务器，或通过客户端订阅在端上直接收到状态变更。两种方式可单独使用，也可同时使用。

业务选型​

业务需求建议做法
只在 IMKit 会话页面展示在线状态（会话列表、好友列表绿点等）使用客户端订阅：在控制台开通「客户端用户在线状态订阅」或「客户端好友在线状态变更通知」，参考 IMKit 在线状态文档实现。
需要在自有服务器记录、统计或分析谁在线、离线使用服务端订阅：在控制台配置「用户在线状态订阅」回调地址，用户上线、离线、登出时融云会 POST 到您的服务器，您落库或做后续逻辑即可。
既要界面展示，又要在后台用状态数据两种都接：服务端做全量同步与报表，客户端做列表绿点等展示。

服务端订阅在线状态​

适用场景：需要在业务服务器侧感知用户上线、离线、登出，用于落库、风控、统计或多端同步。

具体实现：

  1. 在融云控制台为该 App Key 配置用户在线状态订阅回调地址（若服务器有 IP 限制，需配置回调 IP 白名单）。
  2. 在您的服务端实现该地址的 HTTP 接口，接收融云 POST 的状态变更 body（含 userid、status（0 上线 / 1 离线 / 2 登出）、os、time 等），按业务需要落库或触发逻辑。
  3. 若需主动查询某用户当前是否在线，可调用服务端 API 查询用户在线状态。

文档：订阅用户在线状态（服务端）

客户端订阅在线状态（状态在端上展示）​

适用场景：在 IMKit 会话列表、联系人或好友列表等界面实时展示「在线、离线」绿点等。

具体实现：

  1. 在融云控制台开通客户端用户在线状态订阅服务（IM 服务 > 服务购买）。
  2. 在初始化之前调用 RongConfigCenter.featureConfig().enableUserOnlineStatus(true)，且以下两个服务中至少开启一个：
服务作用
客户端好友在线状态变更通知好友的在线状态展示
客户端用户在线状态订阅非好友的在线状态展示

文档：用户在线状态（IMKit）

提示
  • 仅开启「客户端好友在线状态变更通知」时，非好友会一直显示为离线。
  • 仅开启「客户端用户在线状态订阅」时，好友会一直显示为离线。
  • 好友与非好友均需展示时，两个服务均需开通。
  • 单聊非好友会话仅展示最近 1000 个的在线状态，超出部分显示为离线。
  • 只做界面展示：接客户端订阅即可。
  • 只在服务端用状态：接服务端订阅（配置回调 + 处理 POST）。
  • 既要展示又要后台用：两种都接，互不冲突。

好友管理（托管）​

若您需要在应用内提供「好友」能力（添加好友、删除好友、好友列表、好友申请及同意、拒绝等），可使用融云的好友管理服务。融云支持在客户端和服务端分别管理好友关系，您可按现有架构选择在端上完成全部操作，或由服务端发起添加、删除等，按需实现即可。

好友管理依赖用户信息托管，该服务已默认开通；好友增删、申请状态变更等会通过事件回调同步到端上，需在连接前设置好友事件监听器才能收到通知。

业务选型​

业务需求建议做法
添加、删除好友、同意、拒绝申请、好友列表等均在 App 内由用户操作完成以客户端为主：在客户端调用添加好友、解除好友、获取好友列表、同意或拒绝好友申请等接口；在 SDK 初始化后、连接前设置好友事件监听，在回调中刷新 UI。
需要由业务服务端代发添加好友、批量同步好友关系或做后台运营操作使用服务端 API：调用服务端「添加好友」等接口（如 friend/add.json），可指定 optType 为按对方验证等级或直接加为好友；其他能力见服务端好友相关 API。
既要用户在端上操作，又要在服务端同步或代发客户端 + 服务端：端上完成日常添加、删除、同意或拒绝，服务端在需要时调用 API 发起添加或查询，二者可同时使用。
提示

若选择以客户端为主，可直接使用 IMKit 已实现好的 UI 页面（添加好友、好友列表、好友申请列表、用户资料、搜索好友等），快速接入无需自研界面，详见下文「使用 IMKit 提供的 UI 页面」。

实现要点​

  1. 开通：好友管理属于信息托管能力，已默认开通。
  2. 好友事件监听：IMKit 已默认实现好友事件监听。
  3. 加好友权限：可设置为「任何人直接添加」「需要同意后添加」「不允许任何人添加」。未设置时以 App Key 默认为准；若为「需要同意」，对方会收到申请，需调用「同意或拒绝」接口完成流程。
  4. 限制：单用户最多 3000 个好友；单次解除好友最多 100 个；检查好友关系单次最多 20 个；好友申请有效期为 7 天，超期需重新发起。

若需在好友列表中展示好友在线状态或好友资料变更，需在开发者后台开启「客户端好友在线状态变更通知」和「客户端好友资料变更通知」，并在订阅监听中处理 FRIEND_ONLINE_STATUS / FRIEND_USER_PROFILE 类型事件。

使用 IMKit 提供的 UI 页面（从客户端管理好友）​

IMKit 在「信息托管」能力下提供了完整的好友相关页面，包括：

页面说明
添加好友页面支持按用户应用号搜索并添加好友
用户资料页面查看用户信息、发起聊天、添加好友等
好友申请列表页面查看待处理的好友申请，同意/拒绝操作
好友列表页面展示当前用户的好友列表
搜索好友页面按昵称等条件搜索好友

快速启动添加好友页面示例

Java
startActivity(AddFriendListActivity.newIntent(getContext()))

文档：好友管理（Android IMKit） ｜ 好友管理（iOS IMKit）（其他端请查看对应平台文档中的「好友管理」或「用户管理」章节）。

从服务端管理好友​

实现方式：通过服务端 API 发起添加好友等操作。例如添加好友：POST friend/add.json，传入 userId（发起人）、targetId（被添加人）、optType（1：按对方验证等级，2：直接加为好友）、可选 extra。频率限制 100 次/秒。删除好友、获取好友列表、同意或拒绝申请等请参见服务端「好友管理（信息托管）」相关接口。

文档：添加好友（服务端） | 服务端 IM 用户管理（好友相关 API）

群组管理​

若您需要在应用内提供群聊能力，并希望由融云参与群组与群成员的管理（群主、管理员、群公告、邀请入群、权限等），需要先明确是否使用信息托管。未开启托管时，群组管理仅能通过服务端 API 完成，客户端不提供建群、加退群等接口；开启托管后，融云支持在客户端和服务端分别进行群组管理，您可按需在端上或由业务服务器调用 API 实现。

信息托管服务已默认开通。开启托管后，创建群、修改群资料、踢出、退出、解散、转让等操作会通过群事件回调同步给群成员，需在客户端连接前设置群事件监听器才能收到通知。

业务选型​

业务需求建议做法
只需基础群聊：建群、加群、退群由业务服务器控制，不需要群主、管理员、群公告等托管能力不启用群组托管：群组创建、解散、加入、退出、查询群成员、同步用户所在群组等全部通过旧版服务端 API 完成；群资料与群成员关系由您自有服务器维护。客户端仅收发消息，不提供群管理接口。
需要群主、管理员、群公告、邀请入群、踢人、转让群主等，且希望用户在 App 内直接操作启用信息托管 + 以客户端为主：在客户端调用创建群组、修改群资料、踢出、退出、解散、转让等接口；在连接前设置群组状态监听，在回调中处理群操作、群资料变更、加群申请等并更新 UI。
需要上述托管能力，但建群、踢人、解散等由业务服务端发起或与端上混合使用启用信息托管 + 服务端 API：通过服务端「创建群组-托管」「踢出群组-托管」「解散群组-托管」等 API 操作；与客户端 SDK 可同时使用，按需在端上或服务端发起即可。
提示

若选择启用信息托管且以客户端为主，可直接使用 IMKit 已实现好的 UI 页面（选择联系人、创建群组、群组详情、群成员列表、添加/移除群成员、我的群组、群管理、群主转让等），快速接入无需自研界面，详见下文「使用 IMKit 提供的 UI 页面」。

说明：若您此前已通过原接口（如 /group/create.json）创建过群组，要使用托管能力（群主、管理员、群资料等），需先调用导入群托管数据接口，设置群主及群默认权限后再使用托管相关接口。

实现要点​

  1. 开通：群组业务默认支持；若使用群组托管（群主、群资料、群成员资料等），依赖信息托管服务，已默认开通。
  2. 群事件监听（仅托管且使用客户端时）：在 IMLib 初始化之后、建立连接之前设置 GroupEventListener，否则无法收到群操作、群资料变更、加群申请、群备注名与特别关注多端同步等回调。
  3. 限制：单群成员上限 3000 人，单用户加入群数量无限制；客户端创建群时若同时邀请成员，单次最多 30 人；踢出群组单次最多 100 人。群组资料中的扩展信息需在控制台配置群组自定义属性后使用。
  4. 托管下的通知：群组操作（创建、加入、踢出、退出、解散、转让、管理员变更等）会以状态通知方式下发给群成员，会计入消息分发与下行统计。

使用 IMKit 提供的 UI 页面（从客户端管理群组）​

IMKit 在「信息托管」能力下提供了完整的群组相关页面，包括：

页面说明
选择/添加联系人页面从好友列表选择联系人，用于创建群组、发送邀请等；可配置单次可选最大人数（≤30）
创建群组页面输入群名、选择成员创建群组；支持自定义头像点击等
群组详情页面展示群信息、群成员，支持添加/删除成员、解散/退出、群设置等
群成员列表页面查看、搜索群成员，点击查看成员详情
添加群成员页面从联系人中选择并邀请加入群组；可配置单次可选最大人数
移除群成员页面选择群成员并执行移除操作

另含：我的群组、群通知、群成员特别关注、群管理、群管理员、群主转让等页面，可按需调用。

快速启动示例：

Java
// 选择联系人创建群组
int maxCount = 30;
startActivity(FriendSelectActivity.newIntent(this, maxCount));

// 创建群组（传入已选联系人）
List<String> inviteeUserIds = new ArrayList<>();
startActivity(GroupCreateActivity.newIntent(getContext(), groupId, inviteeUserIds));

文档：群组管理（Android IMKit） ｜ 群组管理（iOS IMKit）

从服务端管理群组​

未启用托管时：创建群组、解散群组、加入群组、退出群组、查询群组成员、查询或同步用户所在群组、刷新群组信息、群组禁言等，均通过即时通讯服务端 API 完成。融云不存储群资料，群名称、群成员关系等需在您自有服务器维护。未启用托管创建群组方式：创建群组

启用托管时：除上述基础接口外，可使用托管类接口：创建群组、解散群组、设置群组资料、批量获取群组资料、踢出、退出、转让、加入群组、将用户踢出所有群组、设置或移除群管理员、分页获取群成员、设置群成员资料、设置群名称备注名、特别关注、分页查询应用下群组及用户加入的群组等。非托管创建的群需先调用「导入群托管数据」后再使用托管接口。启用托管创建群组方式：创建群组

文档：群组业务概述（服务端） | 群组业务（创建群组、解散群组、加入退出、群组业务（信息托管开启）等）

消息管理​

若您需要在应用内实现单聊、群聊等消息的发送与接收，或由业务服务端代发消息、将消息同步到自有服务器、使用历史消息云存储等，需要先明确消息由谁发、谁收、是否落库到业务侧、是否需要云端历史。融云支持在客户端与服务端分别参与消息链路：客户端通过 SDK 收发消息并在本地存储；服务端可通过 API 发送单聊、群聊消息。若需消息同步到业务服务器或历史消息云存储，需在控制台进行功能配置或服务购买。

消息类型（文本、图片、语音等）有统一的类型标识（ObjectName）与内容体结构，不同类型在是否存储、是否计入未读、是否支持离线与推送等方面策略不同，发送前建议先了解消息类型概述。

业务选型​

提示：若您希望快速集成聊天界面，IMKit 已提供开箱即用的 UI 页面，内置会话列表、聊天页、各类型消息的发送与接收 UI（文本、图片、语音、文件等），可直接使用，无需从零实现。详见 IMKit 发送消息 等定制化文档。

业务需求建议做法
需要快速集成聊天界面，不希望自研 UI使用 IMKit：IMKit 提供开箱即用的会话列表页、聊天页，以及各类型消息（文本、图片、语音、文件等）的发送与接收 UI，可直接集成使用，详见 IMKit 定制化 文档。
自研 UI 在 App 内由用户收发消息，无需服务端代发、也无需消息同步到业务库以客户端为主：使用 IMLib SDK
需要由业务服务端代发单聊、群聊、系统消息等使用服务端消息 API：调用「发送单聊消息」「发送群聊消息」等接口，按消息类型的 ObjectName 与内容体结构传参。注意：服务端发送的消息默认仅存入收件人在服务端的历史记录；若需同时存入发件人端，请参考「客户端如何同步已发消息」。
需要将单聊、群聊等消息全量同步到自有服务器（落库、风控、审计等）配置全量消息路由：在需先按控制台内嵌指南嵌入到管理后台的 IM 服务功能配置页面（page_code: im_service_config）中，进入 全局消息 配置回调接收地址；必要时开通「Server API 发送消息实时路由」使服务端发出的消息也参与路由。部分场景（如含敏感词消息、状态消息、超级群扩展等）需工单申请。
需要用户多端或离线后仍能拉取历史消息（历史漫游）开通单群聊消息云端存储：在控制台 IM 服务 > 服务购买 中开通（需 IM 旗舰版或尊享版）。如需服务端 API 发送的消息也写入发件人历史，需配合「客户端如何同步已发消息」或多设备消息同步等能力。
需要同一用户多设备间同步收发消息在需先按控制台内嵌指南嵌入到管理后台的 IM 服务功能配置页面（page_code: im_service_config）中，进入 多端 开启多设备消息同步。若希望服务端 API 发送的消息也能同步到发件人离线的客户端，建议一并开启。

选好后，按对应方式在客户端或服务端实现发送/接收逻辑，并在控制台完成所需配置与开通。

从客户端管理消息​

实现方式一（推荐快速集成）：使用 IMKit 已实现好的 UI 页面——内置会话列表、聊天界面及各类型消息的发送、接收 UI，可直接集成使用。若在自定义页面需要发送消息，请使用 IMKit 的发送消息方法，以触发 IMKit 内置页面刷新。详见 IMKit 发送消息。

实现方式二（自研 UI）：在客户端使用 IMLib 的 Message 模型与消息内容体（MessageContent / MediaMessageContent）进行发送、接收、获取历史消息、撤回、删除、消息扩展、已读回执等。发送前选择或自定义消息类型，并注意该类型的存储与未读策略（MessageTag）。接收与历史消息在相应监听与接口中处理。自定义消息类型需正确配置 MessageTag，详见「自定义消息类型」文档。

文档：IMKit 发送消息（Android） | IMKit 发送消息（iOS）

从服务端管理消息​

实现方式：通过服务端 API 发送单聊普通消息、群聊消息、聊天室消息、超级群消息、系统消息等；可撤回、修改单聊或群聊消息、清除消息；可使用单群聊消息扩展、历史消息日志等。发送时需指定消息类型的 ObjectName 并按消息类型概述中的内容体结构传参。若需消息同步到业务服务器，在控制台配置全量消息路由及必要的「Server API 发送消息实时路由」等；若需历史漫游，开通单群聊消息云端存储。

文档：消息管理服务配置（服务端） | 消息类型概述 | 消息管理（发送单聊、群聊消息、撤回、清除、历史消息日志等）

消息内容审核​

如果需要审核消息内容或者防黑产，可以参考文档内容审核场景实践。

会话管理​

若您需要在应用内展示会话列表、未读消息数、置顶、草稿、免打扰等，或希望由业务服务端设置或同步会话置顶状态，可使用融云的会话管理能力。会话由 SDK 根据收发消息自动建立并维护，无需您主动创建；会话列表、未读数、置顶、草稿、免打扰、会话标签等主要在客户端通过 IMLib 接口获取与设置。融云支持在客户端和服务端分别参与部分会话能力：客户端可设置置顶、免打扰等，服务端可调用 API 设置会话置顶，置顶状态会保存到服务端并在多设备间同步（客户端 SDK 4.0.0 及以上版本）。

会话类型包括单聊、群组、超级群、聊天室、系统会话；会话实体（Conversation）中包含目标 ID、未读数、是否置顶、最后一条消息、草稿、免打扰状态等，详见会话介绍。

业务选型​

业务需求建议做法
在 App 内展示会话列表、未读数、置顶、草稿、免打扰、会话标签等，均由用户在端上操作以客户端为主：在客户端调用获取会话、处理未读消息数、删除会话、会话草稿、会话置顶、按会话或按类型设置免打扰、管理会话标签等接口；置顶、免打扰等状态会同步到服务端（客户端 4.0.0+），换设备后可自动同步。
需要由业务服务端设置某用户的某会话是否置顶（如运营策略、客服会话置顶）使用服务端 API：调用「会话置顶」接口（如 conversation/top/set.json），传入 userId、conversationType、targetId、setTop。设置生效后，最新置顶状态会同步到该用户客户端，可用于更新 UI。
既要用户在端上操作置顶、免打扰，又要在服务端统一设置或查询客户端 + 服务端：端上日常置顶、免打扰由用户操作；服务端在需要时调用置顶 API 或获取会话属性。客户端 4.0.0+ 的置顶会同步服务端，服务端设置的置顶也会下发给客户端。

提示：若选择以客户端为主，可直接使用 IMKit 已实现好的 UI 页面（默认会话列表、会话聊天页面等）。IMKit 已内置完整的会话管理及展示逻辑，使用默认页面时无需额外调用会话接口；如需自定义实现，可调用 IMLib 提供的底层 API 进行扩展，详见下文「使用 IMKit 提供的 UI 页面」。

实现要点​

  1. 会话来源：会话由 IMLib 根据消息的发送方、接收方及会话类型等自动建立与维护，无需单独「创建会话」；有收发消息即会产生对应会话。
  2. 置顶与多端同步：服务端会保存会话置顶状态。客户端 4.0.0+ 在端上设置的置顶会同步到服务端，换设备后自动同步；服务端通过 API 设置的置顶也会下发到客户端。
  3. 服务端能力范围：服务端目前主要提供会话置顶、会话标签、获取会话属性等接口；会话列表、未读、草稿、免打扰等以客户端能力为主。

从客户端管理会话​

若您希望快速接入会话能力，可直接使用 IMKit 已提供好的 UI 页面，无需自研会话列表与聊天界面。

IMKit 已内置完整的会话管理及展示逻辑，包括：

  • 会话列表：展示单聊、群组等会话，支持未读数、置顶、草稿、免打扰、最后一条消息等展示
  • 会话聊天页面：消息收发、输入框、历史消息加载等

使用默认会话列表和会话页面时，无需额外调用会话接口，SDK 会自动完成会话获取、未读处理、置顶与免打扰状态的展示等。

如需自定义实现（如自定义会话列表样式、会话项点击逻辑、聊天界面布局等），可调用 IMLib 提供的底层 API（获取会话、设置置顶、免打扰等）进行扩展，再结合 IMKit 的组件或自定义 View 实现所需效果。

文档：会话页面介绍（Android） | 会话页面介绍（iOS） | 会话页面介绍（Web）（其他端请查看对应平台文档中的「会话管理」章节）

从服务端管理会话​

实现方式：通过服务端 API 设置会话置顶：POST conversation/top/set.json，传入 userId、conversationType（如 1 单聊、3 群组、6 系统）、targetId、setTop（true / false）。频率限制 100 次/秒。设置成功后，该用户客户端的置顶状态会更新（需客户端 4.0.0+）。会话标签、获取会话属性等请参见服务端「会话管理」相关接口。

文档：会话置顶（服务端） | 会话管理（会话标签、获取会话属性等）