Rongyun IM (instant messaging service)

Basic introduction

basic function

Single chat session

Function	describe
offline message	Supports offline message storage, the storage time can be set (1 ~ 7 days), and the default storage is 7 days.
message notification	In offline state, Push notification is supported when there are new messages in single chat.
local storage	Received messages are stored locally on the mobile terminal, providing a local message search function.
historical news	Provides server-side message storage function. You need to activate single group chat message cloud storage. The default storage period is 6 months.
Message deletion	Messages stored locally and on the server support deletion. You can delete specified messages or delete all historical messages in the session.
Message search	Supports searching the message content of local specified conversations by keyword or user.
Message read receipt	If you need to check the reading status of the message after sending a private chat message, you can use this function to send a read receipt request.
Message withdrawn	After the message is sent successfully, the message can be withdrawn. IMLib has no limit on the recall time; IMKit has a default recall time of 2 minutes, and the time is configurable.
Single chat conversation without interruption	You can set a specific single chat session and whether to be reminded when new messages are received. New message reminder is performed by default.
Single chat blacklist	If you do not want to receive messages from a certain user, you can add the user to the blacklist. Each user in the application can set his or her own blacklist. Please use the Server API interface to set the blacklist.
Single chat whitelist	Customers who have restrictions on users sending messages to each other can use the user whitelist feature. Only after adding a user to the whitelist can you receive private chat messages from that user. Please use the Server API interface to set up the whitelist. The user whitelist service and the user blacklist service cannot be used at the same time. Rongyun enables the user blacklist service by default. If you need to activate the whitelist service, please submit a work order to apply for activation. It will take effect 30 minutes after the service is activated, and the blacklist service will no longer take effect.
Send status message	Online users will receive this message, and offline users will no longer receive this message. Status messages are not counted or stored.

Group chat session

offline message	Supports offline message storage, the storage time can be set (1 ~ 7 days), and the default storage is 7 days.
message notification	In offline state, Push notification is supported when there are new messages in the group.
local storage	Received messages are stored locally on the mobile terminal, providing a local message search function.
historical news	Provides server-side message storage function. You need to activate single group chat message cloud storage. The default storage period is 6 months.
Message deletion	Messages stored locally and on the server support deletion. You can delete specified messages or delete all historical messages in the session.
Message search	Supports searching the message content of local specified conversations by keyword or user.
Group message read receipt	If you need to check the reading status of the message after sending a group message, you can use this function to send a read receipt request.
Message withdrawn	After the message is sent successfully, the message can be withdrawn. IMLib has no limit on the recall time; IMKit has a default recall time of 2 minutes, and the time is configurable.
Do not disturb group chat sessions	You can set a designated group chat session and whether to be reminded when new messages are received. New message reminders are performed by default.
Create group	There is no limit on the number of groups in the App. The default limit for a group is 3,000 people. The group limit can be adjusted and you need to submit a work order to apply for activation.
Join group	Each group has a maximum limit of 3,000 people, and one user can join multiple groups without restrictions. By default, after joining a group, you can only view messages generated in the group after joining. If you need to view messages before joining, you need to activate single group chat message cloud storage, and then activate a new user to obtain historical messages before joining the group.
Exit group	Remove the user from the group and no longer receive messages from the group.
Disband group	Disband the specified group and all members will no longer be able to receive messages from the group.
Group member query	Get the user ID of the group member in the specified group.
Refresh group information	Support updating group name.
Sync user groups	App Server already has group data before integrating with Rongyun, and this service can be used for synchronization.
Ban group members	A banned user can receive messages from other users in the viewing group, but cannot send messages through the client SDK.
Ban group as a whole	All members of the specified group cannot send messages. If you need certain users to be able to speak, you can add this user to the group's banned user whitelist.
Group banned user whitelist	After the group is banned as a whole, users in the banned whitelist can send group messages.
Send group message	Send a message to all members of the group.
Send group targeted messages	Send a message to one or more specified users in the group. Other users in the group cannot receive the message.
Send group@message	Send messages to specific group members that require special attention.
Send status message	Online users will receive this message, and offline users will no longer receive this message. Status messages are not counted or stored.

supergroup session

Function	describe
Create supergroup	There is no limit on the number of super groups in the app, and there is no upper limit on the number of people in a super group.
Join a supergroup	There is no upper limit for members in each super group, and one user can join 100 super groups. By default, after joining a group, you can only view messages generated in the group after joining. If you need to view messages before joining, you need to activate a new user to obtain historical messages before joining the super group.
Exit supergroup	Remove the user from the group and no longer receive messages from the group.
disband supergroup	Disband the specified supergroup and all members will no longer be able to receive messages from the group.
group channel	每个超级群下，最多可以创建 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 天内没有连接融云，服务器将抛弃掉过期的消息。目前单聊、群组、系统会话支持离线消息，聊天室因为特殊的使用场景，不支持离线消息。