单群聊选型实践
本文基于融云 IMLib 能力，系统梳理应用接入单群聊社交场景时的常见需求，并提供对应的解决方案与实现指引。同时，本文也对可能遇到的问题及关键细节加以提示，帮助您快速理解业务逻辑，高效完成功能落地。如果您基于 IMKit 实现，可参考 IMKit 单群聊场景实践。
- 本文档主要针对单聊及普通群聊（限制人数 3000 人）场景。
- 其他会话类型的详细介绍与区别，请参考会话类型说明（Android）。
SDK 选型（当前文档基于融云 IMLib 能力）
若您需要在应用内集成融云即时通讯能力，需在 IMLib 与 IMKit 两款 SDK 间做出选择。融云 IM 客户端 SDK 提供丰富的组件与接口，大部分能力开箱即用，您可根据业务需求灵活选型。
融云 IM 支持单聊、群聊、超级群、聊天室等多种业务形态，配合 IM 服务端 API，可满足丰富的业务需求。
业务选型
| 业务需求 | 建议做法 |
|---|---|
| 需要将 IM 核心能力深度集成，基于业务有特定的 UI 展示需求，需要完全自定义 UI | 选择 IMLib：封装了通信核心能力和会话、消息等对象，不含任何 UI 组件，可给予您最大的灵活性。 |
| 希望快速上线，直接使用成熟的会话界面 | 选择 IMKit：集成会话界面（UI），提供开箱即用的单聊、群聊能力，可大幅缩短开发周期。 |
| 需要快速上线，但需要对界面做一定定制 | 选择 IMKit：通过丰富的 API 自定义界面功能，或使用官方插件扩展能力，在成熟 UI 基础上按需调整。 |
两款 SDK 对比
| 特性 | IMLib | IMKit |
|---|---|---|
| 定位 | 即时通讯能力库 | 即时通讯界面库 |
| UI 组件 | 不含任何 UI | 集成会话界面、消息列表、用户托管页面等 |
| 支持业务 | 单聊、群聊、聊天室、超级群 | 单聊、群聊（超级群、聊天室无现成 UI） |
| 灵活性 | 极高，可完全自定义 | 高，可定制或扩展 |
| 开发周期 | IMLib SDK 接入较快，UI 开发周期取决于业务需求 | 较短 |
| 依赖关系 | 独立使用 | 依赖 IMLib |
实现要点
- 业务形态：单聊、群聊功能无需额外开通，创建应用后即可使用。
- 平台支持：IMLib 支持 Android、iOS、Web、HarmonyOS、Flutter、React Native、Unity、uni-app、小程序；IMKit 支持 Android、iOS、Web、HarmonyOS、Flutter、uni-app（Web 端需搭配 IMLib 5.x 使用）。
- 版本建议：各平台 IMLib 建议使用 5.x 系列；IMKit 对应 5.x 系列。HarmonyOS 建议使用当前最新版本 SDK。
- 包体积：集成前可查阅集成 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 版本时将面临较高的合并成本，排查问题也会更加复杂。同时，由于代码经过定制，官方技术支持团队将无法为修改后的源码提供直接的技术保障和问题排查支持。请在集成前综合评估长期维护的投入。
准备工作
创建应用与数据中心选型指南
注册开发者账号
- 访问融云控制台注册您的开发者账号。注册成功后，控制台会自动在开发环境中为您创建一个应用。
- 在控制台的密钥管理页面，获取您的应用在开发环境的 App Key。您可在密钥管理页面查看应用的信息，如 App Key、App Secret、所属数据中心（默认为北京）。
创建新应用（含数据中心选择）
如果您的应用在海外上线且用户主要在海外，在创建应用前，您可以根据消息传输需求及合规要求，选择适合您业务的海外数据中心。 文档：海外数据中心使用指南
| 业务场景 | 推荐数据中心 | 说明 |
|---|---|---|
| 国内业务 | 中国（北京） | 默认选项，用户主要在中国大陆 |
| 出海业务（东南亚） | 新加坡 | 用户主要分布在东南亚地区 |
| 出海业务（北美） | 北美（俄勒冈） | 用户主要分布在北美地区 |
| 出海业务（中东） | 沙特 | 用户主要分布在中东地区 |
| 全球化业务 | 根据主用户群选择 | 选择用户最集中的区域对应的数据中心 |
创建方式
- 打开融云控制台应用管理页面。
- 单击创建应用。您将在创建应用的弹窗中选择数据中心。
- 在创建应用对话框中输入您的应用名称、应用简介、应用类型、运营阶段、数据中心。
- 每个应用均拥有两个不同的 App Key，分别对应开发环境与生产环境，且两个环境之间数据相互隔离。在您的应用正式上线前，建议切换到生产环境的 App Key，以便完成上线前全流程测试和最终发布。
- 应用创建后，数据中心不可修改（不支持跨数据中心迁移和上线），请谨慎选择。
用户介绍
App 用户需要接入融云服务才能使用即时通讯功能。对于融云来说，用户是指持有由融云分发的有效 Token、接入并使用即时通讯服务的 App 用户。同一个用户可能拥有多个有效的访问令牌（Token），这些令牌均可用于登录系统。在进行限制时，系统以用户为单位进行控制，而不是以单个令牌 为单位。令牌的失效机制基于时间，即可以将指定时间之前的 Token 作废。
注册用户
应用服务端（App Server）应向融云服务端提供 App 用户的用户 ID（userId），以换取唯一用户 Token。对融云来说，这个以 userId 获取 Token 的步骤即注册用户，且必须通过调用 Server API 来完成。
为方便您快速体验测试，您也可以在创建应用后，在开发者后台中获取用户 Token 进行测试。
应用客户端必须持有有效 Token，才能成功连接到融云服务端，使用融云即时通讯服务。
注册用户数限制
多端同时在线
多端同时在线是指同一用户账号从多个平台同时连接到融云即时通讯服务的功能。默认情况下，融云支持多端设备同时在线（同一用户账号可在移动端、Web 端、桌面端、小程序端最多一个设备上同时在线），该功能无需开 通即可使用。
默认多端设备之间不会进行消息同步。例如 Web 端与移动端同时登录，Web 端接收到消息后，移动端不会再接收到该消息。如需多端同步，请开通多设备消息同步服务。
多端登录限制说明
默认的情况下，同一用户账号可在移动端、Web 端、桌面端、小程序端最多一个设备上同时在线。
| 平台类别 | 限制 | IM SDK 支持平台列表 |
|---|---|---|
| 移动端 | 默认仅支持一个移动端设备连接。如需支持移动端多设备登录 ，请[提交工单]咨询详情。 | Android、iOS、HarmonyOS |
| 桌面端 | 默认仅支持一个桌面端设备连接。 | Electron 框架（通过 Web 端 SDK 的 Electron 模块支持） |
| Web 端 | 默认仅支持一个 Web 页面连接（每个浏览器标签页认为是一个连接）。在控制台自助开通多设备消息同步服务后，自动支持多 Web 页面连接。 | Web |
| 小程序端 | 默认仅支持一个小程序连接。如需支持小程序多设备登录 ，您可以在融云控制台，在 IM 服务>功能配置>多端，开通小程序多端服务。 | 小程序 |
导入 SDK
在开始之前，请确保已创建应用并完成客户端 SDK 集成（Android）（iOS / Web / 其他端请查看对应平台文档中的「SDK 集成」章节）。
维护与展示用户信息
若您需要在应用内展示用户资料（昵称、头像等），并希望其他用户（如会话对方、好友）看到的是最新资料，可按以下两种方式实现。
融云默认不存储您应用内的用户信息，您需要先决定：由业务自己维护，还是交给融云托管并自动下发更新。若选用托管，融云支持在客户端和服务端分别设置、查询用户信息，您可按现有架构与习惯选择在客户端更新或由服务端统一写入，选好后按对应方式接入即可。
业务选型
| 业务需求 | 建议做法 |
|---|---|
| 已有用户中心，希望资料完全自管、不存融云 | 自建维护：在业务库存储昵称、头像等，用户改资料后由您通过自有通道或消息通知会话对方、好友刷新；融云不参与存储与同步。 |
| 希望用户改完资料后，会话对方、好友等自动看到最新昵称、头像，不想自建同步逻辑 | 采用用户信息托 管：把用户资料同步到融云，后续变更由融云向订阅或好友关系用户推送更新，您只需在客户端收通知并刷新 UI。 |
方式一：自建维护
实现方式：用户信息保存在您自己的数据库，在客户端或服务端按需从您的接口拉取并展示。当某用户修改资料后，需由您主动通知与其有会话或好友关系的用户更新（例如通过系统消息或自有推送），否则对方会继续看到旧缓存。
适用场景：已有成熟用户体系、希望数据完全在自己侧的业务。
方式二：采用用户信息托管
设置用户信息的入口：融云支持在客户端和服务端分别设置与查询用户信息，您可按需选择其一或组合使用。例如：用户改资料时在客户端直接调用 SDK 更新；或由业务服务端在用户注册、编辑资料时调用服务端 API 写入融云；批量查询、分页拉取在服务端和客户端也均有对应接口。
实现方式：
- 在融云控制台无需额外开通（服务已默认开启）。
- 将用户资料（昵称、头像等）写入融云：服务端可调用设置用户信息等 API；客户端可调用更新当前用户资料的接口。按您现有架构选择在端上更新或由服务端统一写入即可。
- 对需要「跟随别人资料变更」的用户，在客户端发起用户信息与权限变更订阅；对方改资料后，融云会推送变更，您在监听里刷新 UI 即可，无需自己发通知。
若还需控制「谁能看到我的资料」（所有人 / 仅好友 / 都不可见），可在客户端设置用户信息可见权限；搜索用户等能力见文档。
文档：用户信息托管（Android） | 设置用户信息（服务端）
黑名单管理
本节帮助您根据业务需求选择使用用户白名单、用户黑名单或**好友关系管理（融云托管）**来实现单聊消息限制能力。
默认情况下，App Key 下所有用户均已开启用户黑名单服务。在即时通讯服务端建立黑名单关系的同时，在自有应用服务器维护一份黑名单数据，便于业务查询与统计。
如使用融云提供的好友关系管理服务，默认非好友间也可以正常发送消息。如需要限制为仅好友可以发送消息，可以在融云控制台 IM 服务 > 功能配置 > 好友 > 仅好友可以相互发送单聊消息 中开启该功能。
业务选型
| 要点 | 说明 |
|---|---|
| 默认所有人可聊，少数人可以「拉黑」不想聊的人 | 黑名单 |
| 默认所有人不可聊，只有加好友或加入白名单的人才能互相发单聊 | 白名单 / 仅好友可以相互发送单聊消息 |
您的单聊默认规则是什么？
│
├── 默认「所有人可以互相发单聊」
│ │
│ └── 选【黑名单】
│ （用户通过拉黑排除不想聊的人）
│
└── 默认「只有好友/指定人才可以发单聊」
│
└── 选【白名单/加好友】
（用户通过加好友/加白名单开放聊天权限）
能力与限制
| 要点 | 说明 |
|---|---|
| 人数上限 | 均为 3000 个用户 |
| 黑名单与白名单互斥 | 黑名单与白名单服务不能同时开启。开启白名单后黑名单功能失效，原黑名单数据保留，关闭白名单后仍可恢复。 |
| 单向拉黑 | 拉黑为单向操作：您拉黑用户 A 后，A 无法向您发单聊（会收到 405 错误），您仍可向 A 发消息，A 可正常接收。 |
- 服务端 API 发送单聊消息默认不校验黑名单。若需受黑名单限制，请在调用时设置参数
verifyBlacklist = 1。 - 用户白名单服务：也可限制单聊消息，按「发件人是否在白名单内」过滤；仅白名单内用户的消息可送达当前用户。详见用户白名单服务概述。
文档：从服务端管理黑名单 | 从客户端管理黑名单（Android）（iOS / Web / 其他端请查看对应平台文档中的「黑名单管理」章节） | 单聊用户白名单概述
好友管理（托管）
若您需要在应用内提供「好友」能力（添加好友、删除好友、好友列表、好友申请及同意、拒绝等），可使用融云的好友管理服务。融云支持在客户端和服务端分别管理好友关系，您可按现有架构选择在端上完成全部操作，或由服务端发起添加、删除等，按需实现即可。
好友管理依赖用户信息托管，该服务已默认开通；好友增删、申请状态变更等会通过事件回调同步到端上，需在连接前设置好友事件监听器才能收到通知。
业务选型
| 业务需求 | 建议做法 |
|---|---|
| 添加、删除好友、同意、拒绝申请、好友列表等均在 App 内由用户操作完成 | 以客户端为主：在客户端调用添加好友、解除好友、获取好友列表、同意或拒绝好友申请等接口；在 SDK 初始化后、连接前设置好友事件监听，在回调中刷新 UI。 |
| 需要由业务服务端代发添加好友、批量同步好友关系或做后台运营操作 | 使用服务端 API：调用服务端「添加好友」等接口（如 friend/add.json），可指定 optType 为按对方验证等级或直接加为好友；其他能力见服务端好友相关 API。 |
| 既要用户在端上操作，又要在服务端同步或代发 | 客户端 + 服务端：端上完成日常添加、删除、同意或拒绝，服务端在需要时调用 API 发起添加或查询，二者可同时使用。 |
选好后，注意在客户端连接前设置好友事件监听，并按要求配置加好友权限（见下）。
实现要点
- 开通：好友管理属于信息托管能力，已默认开通。
- 好友事件监听：在 IMLib 初始化之后、建立连接之前设置，否则无法收到好友添加、删除、申请状态变更、好友信息变更等回调。
- 加好友权限：可设置为「任何人直接添加」「需要同意后添加」「不允许任何人添加」。未设置时以 App Key 默认为准；若为「需要同意」，对方会收到申请，需调用「同意或拒绝」接口完成流程。
- 限制：单用户最多 3000 个好友；单次解除好友最多 100 个；检查好友关系单次最多 20 个；好友申请有效期为 7 天，超期需重新发起。
若需在好友列表中展示好友在线状态或动态感知好友资料变更，需在开发者后台开启「客户端好友在线状态变更通知」和「客户端好友资料变更通知」，并在订阅监听中处理 FRIEND_ONLINE_STATUS / FRIEND_USER_PROFILE 类型事件。
从客户端管理好友
实现方式：在客户端调用 IMLib 好友相关接 口：添加好友（可带 extra）、设置或获取加好友权限、解除好友、检查好友关系、分页获取好友申请列表、同意或拒绝好友申请、获取好友列表、设置好友备注与扩展信息、按昵称搜索好友等。在连接前注册好友事件监听，在监听回调中处理相关事件并更新界面。
文档：好友管理（Android IMLib）（iOS / Web / 其他端请查看对应平台文档中的「好友管理」或「用户管理」章节）
从服务端管理好友
实现方式：通过服务端 API 发起添加好友等操作。例如添加好友：POST friend/add.json，传入 userId（发起人）、targetId（被添加人）、optType（1：按对方验证等级，2：直接加为好友）、可选 extra。频率限制 100 次/秒。删除好友、获取好友列表、同意或拒绝申请等请参见服务端「好友管理（信息托管）」相关接口。
文档：添加好友（服务端） | 服务端 IM 用户管理 - 好友相关 API
在线状态
若您需要在应用内展示用户在线、离线（如会话列表绿点、联系人状态），或基于在线状态做业务逻辑（如优先推荐在线用户、约课选在线讲 师），可按以下方式接入。
融云会自动上报用户的连接状态（在线、离线），您只需选择如何接收这些状态：通过服务端回调推送到您的业务服务器，或通过客户端订阅在端上直接收到状态变更。两种方式可单独使用，也可同时使用。
业务选型
| 业务需求 | 建议做法 |
|---|---|
| 只在 App 内展示在线状态（会话列表、好友列表绿点等） | 使用 客户端订阅：在控制台开通「客户端用户在线状态订阅」，在客户端对需要展示状态的用户发起订阅，在订阅监听里收到状态变更后更新 UI。 |
| 需要在自有服务器记录、统计或分析谁在线、离线 | 使用 服务端订阅：在控制台配置「用户在线状态订阅」回调地址，用户上线、离线、登出时融云会 POST 到您的服务器，您落库或做后续逻辑即可。 |
| 既要界面展示，又要在后台用状态数据 | 两种都接：服务端做全量同步与报表，客户端做列表绿点等展示。 |
客户端订阅在线状态（状态在端上展示）
适用场景：在 IM 会话列表、联系人/好友列表等界面实时展示「在线/离线」绿点等。
具体实现：
- 在融云控制台开通 客户端用户在线状态订阅 服务（IM 服务-服务购买）。
- 在客户端连接前注册在线状态订阅监听（
SubscribeType.ONLINE_STATUS），在监听回调中根据状态变更更新 UI。 - 对需要展示状态的用户（如当前会话列表中的用户、好友列表）调用订阅接口发起订阅，并设置合理有效期；被订阅用户上线、离线时，会在监听中收到通知。
- 订阅有数量与时长限制（如单次最多 200 人、总订阅上限 1000 人等），过期后需重新订阅，详见文档。
文档：订阅用户在线状态（Android IMLib） （iOS / Web / 其他端请查看对应平台文档中的「订阅用户在线状态」或「用户管理」章节。）
服务端订阅在线状态
适用场景：需要在业务服务器侧感知用户上线、离线、登出，用于落库、风控、统计或多端同步。
具体实现：
- 在融云控制台为该 App Key 配置用户在线状态订阅回调地址（若服务器有 IP 限制，需配置回调 IP 白名单）。
- 在您的服务端实现该地址的 HTTP 接口，接收融云 POST 的状态变更 body （含
userid、status（0 上线 / 1 离线 / 2 登出）、os、time等），按业务需要落库或触发逻辑。 - 若需主动查询某用户当前是否在线，可调用服务端 API 查询用户在线状态。
- 只做界面展示 → 接客户端订阅即可。
- 只在服务端用状态 → 接服务端订阅（配置回调 + 处理 POST）。
- 既要展示又要后台用 → 两种都接，互不冲突。
群组管理
若您需要在应用内提供群聊能力，并希望由融云参与群组与群成员的管理（群主、管理员、群公告、邀请入群、权限等），需要先明确是否使用信息托管。未开启托管时，群组管理仅能通过服务端 API 完成，客户端不提供建群、加退群等接口；开启托管后，融云支持在客户端和服务端分别进行群组管理，您可按需在端上或由业务服务器调用 API 实现。
- 本文档主要针对单聊及普通群聊（限制人数 3000 人）场景。
- 会话类型的详细介绍与区别，请参考会话类型说明（Android）。
信息托管服务已默认开通。开启托管后，创建群、修改群资料、踢出、退出、解散、转让等操作会通过群事件回调同步给群成员，需在客户端连接前设置群事件监听器才能收到通知。
业务选型
| 业务需求 | 建议做法 |
|---|---|
| 只需基础群聊：建群、加群、退群由业务服务器控制，不需要群主、管理员、群公告等托管能力 | 不启用群组托管：群组创建、解散、加入、退出、查询群成员、同步用户所在群组等全部通过旧版服务端 API 完成；群资料与群成员关系由您自有服务器维护。客户端仅收发消息，不提供群管理接口。 |
| 需要群主、管理员、群公告、邀请入群、踢人、转让群主等，且希望用户在 App 内直接操作 | 启用信息托管 + 以客户端为主：在客户端调用创建群组、修改群资料、踢出、退出、解散、转让等接口；在连接前设置 GroupEventListener，在回调中处理群操作、群资料变更、加群申请等并更新 UI。 |
| 需要上述托管能力，但建群、踢人、解散等由业务服务端发起或与端上混合使用 | 启用信息托管 + 服务端 API：通过服务端「创建群组-托管」「踢出群组-托管」「解散群组-托管」等 API 操作；与客户端 SDK 可同时使用，按需在端上或服务端发起即可。 |
说明：若您此前已通过原接口（如 /group/create.json）创建过群组，要使用托管能力（群主、管理员、群资料等），需先调用导入群托管数据接口，设置群主及群默认权限后再使用托管相关接口。
实现要点
- 开通：群组业务默认支持；若使用群组托管（群主、群资料、群成员资料等），依赖信息托管服务，已默认开通。
- 群事件监听（仅托管且使用客户端时）：在 IMLib 初始化之后、建立连接之前设置
GroupEventListener，否则无法收到群操作、群资料变更、加群申请、群备注名与特别关注多端同步等回调。 - 限制：单群成员上限 3000 人，单用户加入群数量无限制；客户端创建群时若同时邀请成员，单次最多 30 人；踢出群组单次最多 100 人。群组资料中的扩展信息需在控制台配置群组自定义属性后使用。
- 托管下的通知：群组操作（创建、加入、踢出、退出、解散、转让、管理员变更等）会以状态通知方式下发给群成员，会计入消息分发与下行统计。
从客户端管理群组（需信息托管）
实现方式：在客户端调用 IMLib 群组管理接口：创建群组（可带群资料与邀请名单，受「被邀请人是否需同意」等权限约束）、修改群组资料、踢出群成员、退出群组、解散群组、转让群主；并可设置或查询群组备注名。在连接前注册群事件监听，在回调中处理群组相关回调等并更新界面。加群方式、邀请入群、群成员管理等见「加入群组管理」「群成员管理」等文档。
文档：群组管理（Android IMLib）（iOS / Web / 其他端请查看对应平台文档中的「群组业务」>「群组管理」章节）
从服务端管理群组
未启用托管时：创建群组、解散群组、加入群组、退出群组、查询群组成员、查询或同步用户所在群组、刷新群组信息、群组禁言等，均通过即时通讯服务端 API 完成。融云不存储群资料，群名称、群成员关系等需在您自有服务器维护。未启用托管创建群组方式：创建群组
启用托管时：除上述基础接口外，可使用托管类接口：创建群组、解散群组、设置群组资料、批量获取群组资料、踢出、退出、转让、加入群组、将用户踢出所有群组、设置或移除群管理员、分页获取群成员、设置群成员资料、设置群名称备注名、特别关注、分页查询应用下群组及用户加入的群组等。非托管创建的群需先调用「导入群托管数据」后再使用托管接口。启用托管创建群组方式：创建群组
文档：群组业务概述（服务端） | 群组业务（创建群组、解散群组、加入退出、群组业务（信息托管开启）等）
消息管理
若您需要在应用内实现单聊、群聊等消息的发送与接收，或由业务服务端代发消息、将消息同步到自有服务器、使用历史消息云存储等，需要先明确消息由谁发、谁收、是否落库到业务侧、是否需要云端历史。融云支持在客户端与服务端分别参与消息链路：客户端通过 SDK 收发消息并在本地存储；服务端可通过 API 发送单聊、群聊消息。若需消息同步到业务服务器或历史消息存储，需在控制台进行功能配置或服务购买。
消息类型（文本、图片、语音等）有统一的类型标识（ObjectName）与内容体结构，不同类型在是否存储、是否计入未读、是否支持离线与推送等方面策略不同，发送前建议先了解消息类型概述。
业务选型
| 业务需求 | 建议做法 |
|---|---|
| 仅在 App 内由用户收发消息，无需服务端代发、也无需消息同步到业务库 | 以客户端为主：在客户端调用发送、接收消息、获取历史消息等接口；选择或自定义消息类型时注意其存储与未读策略。服务端无需配置消息相关能力。 |
| 需要由业务服务端代发单聊、群聊、系统消息等 | 使用服务端消息 API：调用「发送单聊消息」「发送群聊消息」等接口，按消息类型的 ObjectName 与内容体结构传参。注意：服务端发送的消息默认仅存入收件人在服务端的历史记录；若需同时存入发件人端，请参考「客户端如何同步已发消息」。 |
| 需要将单聊、群聊等消息全量同步到自有服务器（落库、风控、审计等） | 配置全量消息路由：在控制台 IM 服务 > 功能配置 > 全局消息 中配置回调接收地址；必要时开通「Server API 发送消息实时路由」使服务端发出的消息也参与路由。部分场景（如含敏感词消息、状态消息、超级群扩展等）需工单申请。 |
| 需要用户多端或离线后仍能拉取历史消息（历史漫游） | 开通单群聊消息云端存储：在控制台 IM 服务 > 服务购买 中开通（需 IM 旗舰版或尊享版）。如需服务端 API 发送的消息也写入发件人历史，需配合「客户端如何同步已发消息」或多设备消息同步等能力。 |
| 需要同一用户多设备间同步收发消息 | 在控制 台 IM 服务 > 功能配置 > 多端 中开启多设备消息同步。若希望服务端 API 发送的消息也能同步到发件人离线的客户端，建议一并开启。 |
选好后，按对应方式在客户端或服务端实现发送/接收逻辑，并在控制台完成所需配置与开通。
实现要点
- 消息类型：融云提供预定义类型（文本、图片、语音、文件、位置、引用、合并转发等）及通知类、状态类、信令类等；内容体结构需与消息类型概述一致。自定义消息需继承
MessageContent/MediaMessageContent并正确设置MessageTag（客户端）。 - 服务端发消息的落库：通过服务端 API 发送的消息，默认只写入收件人在服务端的历史记录；若需在发件人端也保留，请参考客户端如何同步已发消息或开通多设备消息同步等。
- 控制台与消息相关的配置（消息管理服务配置）：全量消息路由（同步到业务服务器）、Server API 发送消息实时路由、Server API 发送消息过滤敏感词、Server API 历史消息日志下载、多设备消息同步等，均在 IM 服务 > 功能配置 中配置；单群聊消息云端存储在 IM 服务 > 服务购买 中开通。
从客户端管理消息
实现方式：在客户端使用 IMLib 的 Message 模型与消息内容体（MessageContent / MediaMessageContent）进行发送、接收、获取历史消息、撤回、删除、消息扩展、已读回执等。发送前选择或自定义消息类型，并注意该类型的存储与未读策略（MessageTag）。接收与历史消息在相应监听与接口中处理。自定义消息类型需正确配置 MessageTag，详见自定义消息类型文档。
文档：消息介绍（Android IMLib） | 发送消息 | 接收消息 | 获取历史消息（iOS / Web / 其他端请查看对应平台文档中的「消息管理」章节）
从服务端管理消息
实现方式：通过服务端 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+ 的置顶会同步服务端，服务端设置的置顶也会下发给客户端。 |
说明：若客户端 SDK 版本低于 4.0.0，通过服务端 API 设置的会话置顶状态不会同步到客户端。
实现要点
- 会话来源：会话由 IMLib 根据消息的发送方、接收方及会话类型等自动建立与维护，无需单独「创建会话」；有收发消息即会产生对应会话。
- 置顶与多端同步：服务端会保存会话置顶状态。客户端 4.0.0+ 在端上设置的置顶会同步到服务端，换设备后自动同步；服务端通过 API 设置的置顶也会下发到客户端。
- 服务端能力范围：服务端目前主要提供会话置顶、会话标签、获取会话属性接口；会话列表、未读、草稿、免打扰等以客户端能力为主。
从客户端管理会话
实现方式：在客户端调用 IMLib 会话相关接口：获取会话列表（可按会话类型、标签）、获取或清除会话未读消息数、获取会话未读消息、删除会话、设置或获取会话草稿、设置会话置顶、按会话或按会话类型或按频道设置免打扰、管理会话标签并设置与使用会话标 签等。监听多端同步（置顶、免打扰、阅读状态）可在相应监听器中刷新 UI。会话实体 Conversation 中的 isTop、unreadMessageCount、draft、notificationStatus 等可直接用于列表展示。
文档：会话介绍（Android IMLib） | 获取会话 | 会话置顶 | 免打扰功能概述 | 多端同步免打扰、置顶（iOS / Web / 其他端请查看对应平台文档中的「会话管理」章节）
从服务端管理会话
实现方式：通过服务端 API 设置会话置顶：POST conversation/top/set.json，传入 userId、conversationType（如 1 单聊、3 群组、6 系统）、targetId、setTop（true / false）。频率限制 100 次/秒。设置成功后，该用户客户端的置顶状态会更新（需客户端 4.0.0+）。会话标签、获取会话属性等请参见服务端「会话管理」相关接口。
文档：会话置顶（服务端） | 会话管理（会话标签、获取会话属性）