融云IM（即时通讯服务）

基础介绍

基础功能

单聊会话

功能	描述
离线消息	支持离线消息存储，存储时间可设置（1 ～ 7 天），默认存储 7 天。
消息提醒	离线状态，单聊中有新消息时，支持 Push 通知。
本地存储	接收过的消息存储在移动端本地，提供本地消息搜索功能。
历史消息	提供服务端消息存储功能，需开通单群聊消息云存储，默认存储时长为 6 个月。
消息删除	存储在本地和服务端的消息都支持删除功能。可以删除指定消息，也可以删除会话中全部历史消息。
消息搜索	支持按关键字或用户搜索本地指定会话的消息内容。
消息阅读回执	发送单聊消息后如需要查看消息的阅读状态，可以使用此功能来发送阅读回执请求。
消息撤回	消息发送成功后，可以撤回该条消息。IMLib 对撤回时间不做限制；IMKit 默认可撤回时间 2 分钟，时间可配置。
单聊会话免打扰	可设置指定单聊会话，收到新消息后是否提醒。默认进行新消息提醒。
单聊黑名单	不想接收到某一用户的消息时，可将此用户加入到黑名单中。应用中每个用户都可以设置自己的黑名单列表，请使用 Server API 接口设置黑名单。
单聊白名单	对用户相互发送消息有限制的客户，可使用用户白名单功能。将用户加入白名单后，才能收到该用户发送的单聊消息，请使用 Server API 接口设置白名单。 用户白名单服务与用户黑名单服务不能同时使用，融云默认开启用户黑名单服务，如需要开通白名单服务请提交工单申请开通。服务开通 30 分钟后生效，同时黑名单服务不再生效。
发送状态消息	在线用户会收到此条消息，离线用户不会再收到此条消息。状态消息不计数、不存储。

群聊会话

离线消息	支持离线消息存储，存储时间可设置（1 ～ 7 天），默认存储 7 天。
消息提醒	离线状态，群组中有新消息时，支持 Push 通知。
本地存储	接收过的消息存储在移动端本地，提供本地消息搜索功能。
历史消息	提供服务端消息存储功能，需开通单群聊消息云存储，默认存储时长为 6 个月。
消息删除	存储在本地和服务端的消息都支持删除功能。可以删除指定消息，也可以删除会话中全部历史消息。
消息搜索	支持按关键字或用户搜索本地指定会话的消息内容。
群消息阅读回执	发送群消息后如需要查看消息的阅读状态，可以使用此功能来发送阅读回执请求。
消息撤回	消息发送成功后，可以撤回该条消息。IMLib 对撤回时间不做限制；IMKit 默认可撤回时间 2 分钟，时间可配置。
群聊会话免打扰	可设置指定群聊会话，收到新消息后是否提醒，默认进行新消息提醒。
创建群组	App 内群组数量没有限制，默认一个群上限为 3000 人，可调整群上限，需要提交工单申请开通。
加入群组	每个群最大上限 3000 人，一个用户可加入多个群组，没有限制。默认加入群组后，只能查看加入后群组中产生的消息，如需要查看加入前的消息，则需要开通单群聊消息云存储后，再开通新用户获取加入群组前历史消息。
退出群组	将用户从群中移除，不再接收该群组的消息。
解散群组	将指定群组解散，所有成员都无法再接收该群的消息。
群成员查询	获取指定群组中群成员用户 Id。
刷新群组信息	支持更新群组名称。
同步用户所属群组	在集成融云前 App Server 已有群组数据，可使用此服务进行同步。
群组成员禁言	被禁言用户可以接收查看群组中其他用户消息，但不能通过客户端 SDK 发送消息。
群组整体禁言	指定群组所有成员不能发送消息，需要某些用户可以发言时，可将此用户加入到群禁言用户白名单中。
群组禁言用户白名单	群组被整体禁言后，禁言白名单中用户可以发送群消息。
发送群组消息	向群组中所有成员发送消息。
发送群组定向消息	向群中指定的一个或多个用户发送消息，群中其他用户无法收到该消息。
发送群组 @消息	发送群组中指定群成员需要特别关注的消息。
发送状态消息	在线用户会收到此条消息，离线用户不会再收到此条消息。状态消息不计数、不存储。

超级群会话

功能	描述
创建超级群	App 内超级群数量没有限制，超级群无人数上限。
加入超级群	每个超级群无成员上限，一个用户可加入 100 个超级群。默认加入群组后，只能查看加入后群组中产生的消息，如需要查看加入前的消息，则需要开通新用户获取加入超级群前历史消息。
退出超级群	将用户从群中移除，不再接收该群组的消息。
解散超级群	将指定超级群解散，所有成员都无法再接收该群的消息。
群频道	每个超级群下，最多可以创建 50 个群频道，每个频道共用所属群的成员关系，成员可随意在不同群频道中发送消息，但不同频道间的消息相互隔离。
刷新群组信息	支持更新群组名称。
群组成员禁言	被禁言用户可以接收查看群组中其他用户消息，但不能通过客户端 SDK 发送消息。
群组整体禁言	指定群组所有成员不能发送消息，需要某些用户可以发言时，可将此用户加入到群禁言用户白名单中。
群组禁言用户白名单	群组被整体禁言后，禁言白名单中用户可以发送群消息。
消息提醒	离线状态，群组中有新消息时，支持 Push 通知，可对通知的类型灵活设置，如只对 @消息进行推送通知。
本地存储	接收过的消息存储在移动端本地。
历史消息	默认提供 7 天的历史消息云存储服务，如需要存储更长时间，可在开发者后台开通超级群消息云存储服务。
消息删除	存储在本地和服务端的消息都支持按时间进行删除。
消息撤回	消息发送成功后，可以撤回该条消息。IMLib 对撤回时间不做限制；IMKit 默认可撤回时间 2 分钟，时间可配置。
消息修改	对已经发送出去的消息提供内容修改能力。
超级群免打扰	可设置指定超级群，收到新消息后是否提醒，默认进行新消息提醒。
发送群组消息	向群组中所有成员发送消息。
发送群组 @消息	发送群组中指定群成员需要特别关注的消息。

聊天室会话

功能	描述
离线消息	不支持离线消息，只有当前在线用户可收到聊天室中消息。
人数限制	聊天室人数无上限。
消息提醒	聊天室消息没有消息提醒。
本地存储	退出聊天室后删除本地聊天室消息，不支持消息搜索功能。
历史消息	提供服务端消息存储功能，需开通聊天室消息云存储，默认存储时长为 2 个月。
创建聊天室	App 内的聊天室数量没有限制。
销毁聊天室	将指定聊天室解散，所有成员都无法再接收该聊天室的消息。
查询聊天室信息	查询聊天室基础信息，包括：聊天室 ID、名称、创建时间。
获取聊天室成员	获取聊天室成员信息，包括：用户 ID、加入时间。最多返回 500 个成员信息，支持按加入时间排序。
指定聊天室禁言	用户在指定聊天室中禁言。被禁言用户可以接收查看聊天室消息，但不能发送消息。
用户聊天室全局禁言	用户在应用的所有聊天室中禁言。被禁言用户可以接收查看聊天室消息，但不能发送消息。
聊天室用户封禁	被封禁用户将被踢出指定聊天室，并在设定的时间内不能再进入该聊天室。
指定聊天室全局禁言	对指定聊天室做禁言处理，聊天室中所有用户都不能发送消息。
聊天室低级别消息	可以设置某些指定消息类型的消息为低优先级。当服务器负载高时低优先级的消息优先被丢弃，这样可以让出资源给高优先级的消息，确保重要的消息不被丢弃。
消息白名单	白名单中的消息类型受到保护，在聊天室消息量较大的情况下也不被丢弃。
聊天室用户自动退出	聊天室用户离线后，从第一条新消息产生开始计时，倒数 30 秒自动退出聊天室；或离线后聊天室中产生 30 条消息时自动退出聊天室。
聊天室用户白名单	白名单中用户发送的消息受到保护，在聊天室消息量较大的情况下也不被丢弃。同时用户处于被保护状态，以避免自动退出聊天室。
聊天室保活	聊天室保活功能，可以确保聊天室在此状态下不被自动销毁，只能通过调用 API 接口销毁聊天室。
聊天室状态同步	聊天室发生状态变化时，将实时同步到开发者的应用服务器。目前支持的同步状态包括：创建、销毁、成员加入、成员退出聊天室。
聊天室属性自定义	每个聊天室中，最多允许设置 100 个属性信息，以 Key、Value 的方式存储。聊天室销毁后，聊天室中的自定义属性同时销毁。
消息撤回	消息发送成功后，可以撤回该条消息。IMLib 对撤回时间不做限制；IMKit 默认可撤回时间 2 分钟，时间可配置。

全量消息路由

功能	描述
全量消息路由	支持将单聊、群组、聊天室、客服的消息数据同步到开发者指定的应用服务器。

多设备消息同步

默认的情况下，融云仅支持 1 个 Web 端、1 个桌面端、1 个移动端同时在线。开通多设备消息同步功能后，可以支持多个 Web 端同时在线。同时支持 Web 端、桌面端和移动端之间的消息同步。

消息回调服务

功能	描述
消息回调服务	根据设置的条件，将符合条件的消息发送到设置的应用服务器地址，不直接发送给目标用户，根据应用服务器返回的响应结果决定是否下发。适用于对接内容审核服务的应用场景。

消息云存储

功能	描述
单群聊消息云端存储	提供单聊、群聊消息的云端保存服务。客户端可以获取云端历史消息，开通后历史消息默认保存 6 个月。
聊天室消息云存储	提供聊天室消息的云端保存服务。客户端可以获取云端历史消息，开通后历史消息默认保存 2 个月。

全量用户通知

通过融云开发者后台或调用 Server API 发送全量用户通知。可以给全部用户发送，也能指定部分用户发送，服务每小时只能发送 2 次，每天最多发送 3 次。
全量用户通知服务包括两个功能：一个是不落地通知（Push），一个是落地通知(Broadcast)。

• 不落地通知（Push） 通过远程推送的方式通知用户。

不落地通知产生一条远程推送抵达用户。其中 iOS 使用 APNs（Apple Push Notification service），Android 使用开发者在 SDK 中配置的推送服务，包括融云自研推送、小米、华为、魅族、OPPO、vivo、FCM。

• 落地通知（Broadcast） 通过融云消息的方式通知用户。

落地通知产生一条融云消息抵达用户。用户在线时能即时收到消息；当用户离线时，融云消息会默认生成一条远程推送。

业务流程

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-xFhbU5BH-1669550215339)(https://cdn.nlark.com/yuque/0/2022/svg/25403851/1669298915479-ee8ddeeb-7fc8-48f6-a20b-f956e38ab9e0.svg#clientId=ub6764d73-02c4-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=405&id=uf20182bc&margin=%5Bobject%20Object%5D&name=8e7cf1d95743912d6d91325f41e8a625.svg&originHeight=405&originWidth=933&originalType=binary&ratio=1&rotation=0&showTitle=false&size=14672&status=done&style=none&taskId=uf9c1dcb0-51cf-4a8b-9ae7-a47147cb51b&title=&width=933#crop=0&crop=0&crop=1&crop=1&id=TpMMn&originHeight=405&originWidth=933&originalType=binary&ratio=1&rotation=0&showTitle=false&status=done&style=none&title=)]

SDK体系架构

• IMKit： 融云将即时通信产品中最复杂的会话列表、聊天窗口、消息内容展现、会话设置等功能封装为组件，通过简短的代码，就可以直接将以上界面集成到 App 产品中，省去大量的开发调试时间。融云同时支持业内最丰富的自定义界面组件功能，可以针对自己界面需求自由设计开发。

• IMLib： IMLib（IM 通讯能力库）是不含界面的基础 IM 通讯能力库，封装了通信能力和会话、消息等对象。引用到 App 工程中后，需要开发者自己实现 UI 界面，相对较轻量，适用于对 UI 有较高订制需求的开发者。

• Protocol 是融云的核心协议栈，使用融云自定义的私有二进制协议。主要特点是是轻量化，有序可靠，不丢消息。Protocol 部分使用 Native 语言开发，在 Android 和 iOS 平台上保证业务一致性，便于开发者商用化自己的产品。
  

集成流程

消息结构

消息分类

消息分类	消息行为状态标识
内容类消息	表示一个用户间发送的包含具体内容的消息，需要展现在聊天界面上，如文字消息、语音消息等。
通知类消息	表示一个通知信息，可能展现在聊天界面上，如提示条通知。
状态类消息	表示一个状态，用来实现如“对方正在输入”的功能。
信令类消息	融云在实现 SDK 自身业务功能时使用的，开发者不需要对其做任何处理。

内容类消息

消息类型	描述
文字消息	用来发送文字类消息，其中可以包括表情、超链接（IMKit 中会自动识别），客户端收到消息后存入数据库、计入未读消息数。
语音消息	发送高质量的短语音消息，录制的语音文件存储到融云服务端，语音文件格式为 AAC，时长上限为 60 秒，客户端收到消息后存入数据库、计入未读消息数。
图片消息	用来发送图片类消息，客户端收到消息后存入数据库、计入未读消息数。图片缩略图格式为 JPG，开发者自定义图片消息时，缩略图大小建议不超过 100k。
GIF 图片消息	用来发送 GIF 动态图片消息，客户端收到消息后存入数据库、计入未读消息数。
图文消息	用来发送图文消息，包含一个标题，一段文字内容和一张图片，客户端收到消息后存入数据库、计入未读消息数。
文件消息	用来发送文件类消息，客户端收到消息后存入数据库、计入未读消息数。
位置消息	用来发送地理位置消息，客户端收到消息后存入数据库、计入未读消息数。
小视频消息	用来发送小视频消息，支持录制发送及选择本地视频文件发送两种方式。录制时长不超过 10 秒，本地选择视频时长不超过 2 分钟，小视频文件格式为 mp4，客户端收到消息后存入数据库、计入未读消息数。
合并转发消息	IMKit SDK 中发送的合并转发消息类型，合并后的消息以 HTML 文件的方式存储到融云服务端，客户端收到消息后计入未读消息数、进行存储。
公众服务单图文消息	用来发送单图文消息，客户端收到消息后计入未读消息数、进行存储。
公众服务多图文消息	用来发送多图文消息，客户端收到消息后计入未读消息数、进行存储。

内置通知类消息

消息分类	描述
提示小灰条通知消息	用来发送在聊天会话页面显示的提示条（小灰条）通知，客户端收到消息后进行存储，不计入未读消息数，此类型消息没有 Push 通知。
联系人（好友）通知消息	用来发送联系人操作（加好友等）的通知消息，客户端收到消息后进行存储，不计入未读消息数，此类型消息没有 Push 通知。
资料消息通知	用来发送用户资料变更通知消息，客户端收到消息后进行存储，不计入未读消息数，此类型消息没有 Push 通知。
通用命令消息	用来发送通用的指令通知消息，消息内可以定义任意 JSON 内容，客户端收到消息后进行存储，不计入未读消息数，此类型消息没有 Push 通知。
群组通知消息	用来发送群组操作的通知消息，客户端收到消息后进行存储，不计入未读消息数，此类型消息没有 Push 通知。 比如创建群组、修改群名称、添加群成员、移除群成员、退出群组、解散群组
已读通知消息	用来发送消息已经被接收到的状态消息，客户端收到消息后不计入未读消息数、不存储，此类型消息没有 Push 通知。
公众服务命令消息	公众服务中用来发送通用的指令通知消息，消息内可以定义任意 JSON 内容，客户端收到消息后不计入未读消息数、不存储。
命令消息	用来发送通用的指令通知消息，消息内可以定义任意 JSON 内容，与通用命令通知消息的区别是不存储、不计数，此类型消息没有 Push 通知。
聊天室属性通知消息	用来发送聊天室设置属性后的通知消息，客户端收到消息后进行存储，不计入未读消息数，此类型消息没有 Push 通知。

内置状态类消息

消息类型	描述
对方正在输入状态消息	用来发送对方正在输入时的状态消息，客户端收到消息后不计入未读消息数、不存储。
群消息已读状态回执	用来发送群组中已读的消息状态，客户端收到消息后不计入未读消息数、不存储。

内置信令消息

音视频功能信令消息

消息类型	描述
RC:VCAccept	实时音视频接受
RC:VCHangup	实时音视频挂断
RC:VCInvite	实时音视频邀请
RC:VCModifyMedia	实时音视频切换
RC:VCModifyMem	实时音视频成员变化
RC:VCRinging	实时音视频响铃

客服信令消息

消息类型	描述
RC:CSCha	客服转换模式：如机器人转人工，由客户端给客服系统发
RC:CsChaR	客服转换模式结果响应，由客服系统下发给客户端
RC:CsHs	客服请求握手，由客户端给客服系统发
RC:CsHsR	客服握手响应，由客服系统下发给客户端
RC:CsSp	客服挂断(用户主动挂断)，由客户端给客服系统发
RC:CsEnd	客服挂断(客服后台系统主动)，由客服系统下发给客户端
RC:CsUpdate	客服模式更新，由客服系统下发给客户端
RC:CsPullEva	客服后台邀请评价，由客服系统下发给客户端
RC:CsEva	客服评价，由客户端给客服系统发
RC:CsPLM	客服后台邀请留言，由客服系统下发给客户端
RC:CsLM	客服留言，由客户端给客服系统发

已读回执信令消息

消息类型	描述
RC:ReadNtf	已读状态
RC:SRSMsg	同步消息已读状态
RC:RRReqMsg	请求消息回执
RC:RRRspMsg	消息回执响应

其他信令消息

消息类型	描述
RC:ProfileNtf	公众账号信息
RC:UIUMsg	用户信息更新
RC:RcCmd	撤回消息

常用名词解释

• 会话：指二人或多人进行消息通讯的聊天场景，融云支持单聊、群聊、聊天室、客服、系统等会话类型。

• 单聊：指两个用户一对一进行聊天，两个用户间可以是好友也可以是陌生人，融云不对用户的关系进行维护管理，会话关系由融云负责建立并保持，当 App 在后台运行或者 App 进程被杀死后，有新消息时会收到推送通知。

• 群组：群组指两个以上用户一起进行聊天，群组成员信息由 App 提供并进行维系，融云只负责将消息传达给群组中的所有用户， App 在后台运行或者 App 进程被杀死后可以收到推送通知。每个群最大人数上限为 3000 人，App 内的群组数量没有限制。

• 聊天室：聊天室成员不设用户上限，海量消息并发即时到达，用户退出聊天界面后即视为离开聊天室，不会再接收到任何聊天室中消息，没有推送通知功能。会话关系由融云负责建立并保持连接，通过 SDK 相关接口，可以让用户加入或者退出聊天室。

• 客服：用户与您的 App 后台客服进行消息通讯，支持文字、图片、位置、语音、表情、图文等消息类型，支持单客服和多客服服务，提供“机器人”和“人工”配合使用，可设置“机器人”或者“人工”优先接待功能。

• 应用公众服务：为 App 开发者提供 App 内建公众服务能力，通过在融云开发者站点创建 App 公众号，帮助 App 快速覆盖用户需求。

• 公众服务：是在应用开发者和公众帐号运营者之间建立的对接平台，应用开发者可以通过平台引入公众服务资源，帮助 App 快速覆盖用户需求。

• 会话列表：指各种会话依照顺序先后排列的界面，其中会话列表中的每一个列表项称之为一条会话。排列的先后顺序会依赖于置顶、最新会话、未读会话和时间等因素，聊天室类型的会话不会进入到会话列表中。

• 通知：是一种用户界面展现概念，是指在设备端以某种形式弹出一条提示。通知分为本地通知（Local Notification）和远程通知（Remote Notification）。

  • 本地通知指的是您的应用程序在前台、或者在后台但仍然在生命周期存活，此时收到消息，会直接通过前台的应用程序弹出提示窗口。
  • 远程通知指的是您的应用程序已经完全退出，应用进程已经不存在，此时通过 iOS 上的 APNS 系统服务或者 Android 上的服务进程收到消息，并弹出提示栏。大家开发和调试过程中，务必要清楚本地通知和远程通知的区别。

• 推送：推送（Push）是一种技术概念，是指从服务端实时发送远程通知到客户端。典型的推送服务是类似 APNS（Apple Push Notification Service）、GCM（Google Cloud Messaging） 等服务，在国内，由于谷歌服务不能使用，必须使用第三方或者自己研发的服务来推送，或者，通过融云使用长连接技术来实现 IM 服务，和典型的 Push 服务具有相同的长连接机制，所以，开发者也可以直接使用融云来实现推送功能。

• 在某些场合，iOS 平台的推送（通过 APNS 的 Push）和远程通知（Remote Notification）表示相同的意思，可以互相替换使用。

• 广播：广播（Broadcast）是一种业务概念，是通过后台管理界面或者调用服务端接口，向 App 中的所有用户发送一条消息。通常“广播”和“推送”是开发者容易产生混淆的地方。

• 系统消息：系统消息（System Message）是一种业务概念，是指利用系统帐号（非用户帐号，用户不可登录）向用户发送的消息，既可以是通过调用广播接口发送给所有人的消息，也可以是加好友等单条通知消息。在融云平台中，其实并不存在系统消息的概念，一般系统消息特指会话类型（ConversationType）为“系统（SYSTEM）”的会话中的消息。

• 离线消息：当目标用户不在线的时候，融云服务器会将用户未收到的消息保留 7 天，7 天内用户登录连接融云后，还会收到其他用户发送过来的消息，如果 7 天内没有连接融云，服务器将抛弃掉过期的消息。目前单聊、群组、系统会话支持离线消息，聊天室因为特殊的使用场景，不支持离线消息。