更新时间: 2021-04-06

# 功能描述

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

1、由于IMKit（含 UI 集成）依赖IMLib（无 UI 集成），所以其实IMLib中的全部能力，IMKit中都具备，比如聊天室，只不过聊天室会话暂时不提供开箱即用的 UI 组件。

2、聊天室会话中的消息，在消息量比较大的情况下，会有丢弃的可能，如有必达性消息发送的需要，可配合使用系统通知会话发送。若要提升聊天室消息的可靠性，可参考文档消息优先级以及消息白名单；具体聊天室消息丢弃策略，请参考知识库：消息丢弃策略 (opens new window)。

# 主要功能

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

# 与群组的区别

融云提供群组与聊天室业务，其主要区别如下，客户可根据自己的业务场景进行选择：

功能 群组（group） 聊天室（Chatroom）
场景 类似微信的群组，无论是否在线都会接收消息 类似直播间的弹幕，只有观看的时候接收消息
离线缓存消息 支持离线消息存储，存储时间可设置（1 ～ 7 天），默认存储 7 天。 无离线消息，只有在线用户才可收到聊天室消息
人数限制 默认一个群上限为 3000 人 聊天室人数无上限
消息提醒 离线状态，群组中有新消息时，支持远程推送（PUSH)通知 离开聊天室后不再接收消息
本地存储 移动端本地数据库存储，提供本地消息搜索接口 退出聊天室后同时删除本地聊天室消息，不支持消息搜索功能
云端存储 需开通单群聊消息云存储，可以提供 6 - 36 个月存储服务 需开通聊天室消息云存储，可以提供 2 - 12 个月存储服务
用户加入限制 一个用户可加入多个群组，无限制 默认一个用户只能加入一个聊天室，加入多个聊天室功能可在开发者后台自行开通
加入后消息获取逻辑 默认加入群组后，只能查看加入后群组中产生的消息。如需要查看群历史消息，则需要开通单群聊消息云存储后，再开通“查看加入前群消息”功能 加入后可获取聊天室中最新的 50 条消息。
销毁/解散逻辑 需要通过 AppServer 自行调用解散群组接口。 提供销毁聊天室接口，可通过 AppServer 调用。同时聊天室中 1 小时内没有消息产生时，将自动销毁聊天室。
消息可靠度 100% 可靠，不丢消息。 消息量较大时，超出消费上限的消息将被丢弃，查看详细
相关接口调用 SDK 不提供群组管理功能接口，通过 Server API 提供群组功能接口。 SDK 和 Server API 同时提供功能接口，销毁聊天室操作只能通过 Server API 方式调用。
发送消息频率 每个客户端 5 条/秒，服务端调用，每秒钟 20 条/秒 每个客户端 5 条/秒，服务端调用，每秒钟 100 条/秒

# 消息类型

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

# 内置消息说明

以下为融云内置消息类型说明：

# 内容类消息

融云内置了一些内容类消息：

消息类型 ObjectName
[文字消息] RC:TxtMsg
[语音消息] 旧消息类型 RC:VcMsg，新消息类型 RC:HQVCMsg
[图片消息] RC:ImgMsg
[GIF 图片消息] RC:GIFMsg
[图文消息] RC:ImgTextMsg
[文件消息] RC:FileMsg
[位置消息] RC:LBSMsg
[小视频消息] RC:SightMsg
[引用消息] RC:ReferenceMsg
[合并转发消息] RC:CombineMsg

内容类消息具体明细，请参考：消息类型-内容类消息文档。

# 位置消息
ObjectName 存储属性 计数属性 离线属性 推送属性 推送内容
RC:LBSMsg 存储 计数 存储 推送 [位置]

消息结构：

发送位置消息时 content 参数的 JSON 结构如下：

{
  "content":"bhZPzJXimRwrtvc=",
  "latitude":39.9139,
  "longitude":116.3917,
  "poi":"北京云中融信网络科技有限公司",
  "user":
  {
    "id":"4242",
    "name":"Robin",
    "portrait":"http://example.com/p1.png",
    "extra":"extra"
  },
  "extra":""
}

已复制
1
2
3
4
5
6
7
8
9
10
11
12
13
14

属性说明：

名称 类型 必传 说明
content String 是 表示位置图片缩略图，格式为 JPG，以 Base64 进行 Encode 后需要将所有 \r\n 和 \r 和 \n 替换成空。
latitude String 是 位置的纬度值。
longitude String 是 位置的经度值。
poi String 是 表示位置的 poi 信息。
user String 否 消息中携带的用户信息，详细查看 user 参数说明。
extra String 否 扩展信息，可以放置任意的数据内容，也可以去掉此属性。

user 属性说明：

名称 说明
id 发送用户 Id。
name 发送用户需要显示的名称。
portrait 发送用户需要显示的头象。
extra 扩展信息，可以放置任意的数据内容。
# 提示小灰条消息
ObjectName 存储属性 计数属性 离线属性 推送属性 推送内容
RC:InfoNtf 存储 不计数 存储 不推送 无

消息结构：

发送小灰条消息时 content 参数的 JSON 结构如下：

{
  "message":"请在聊天中注意人身财产安全",
  "extra":""
}

已复制
1
2
3
4

属性说明：

名称 类型 必传 说明
message String 是 提示条消息内容。
extra String 否 扩展信息，可以放置任意的数据内容，也可以去掉此属性。
# 资料变更通知消息
ObjectName 存储属性 计数属性 离线属性 推送属性 推送内容
RC:ProfileNtf 存储 不计数 存储 不推送 无

消息结构：

发送用户资料变更消息时 content 参数的 JSON 结构如下：

{
  "operation":"Update",
  "data":"{\"nickname\":\"韩梅梅\", \"hometown\":\"beijing\"}",
  "extra":""
}

已复制
1
2
3
4
5

属性说明：

名称 类型 必传 说明
operation String 是 资料通知操作，可以自行定义。
data String 是 操作的数据。
extra String 否 扩展信息，可以放置任意的数据内容，也可以去掉此属性。
# 命令消息
ObjectName 存储属性 计数属性 离线属性 推送属性 推送内容
RC:CmdMsg 不存储 不计数 存储 不推送 无

消息结构：

运营平台向终端发送指令信息时可使用此命令消息，消息中 content 参数的 JSON 结构如下：

{
  "name":"AtPerson",
  "data":"{\"sourceId\":\"9527\"}"
}

已复制
1
2
3
4

属性说明：

名称 类型 必传 说明
name String 是 命令名称，可以自行定义。
data String 是 命令的内容。

# 常见问题

# 聊天室登录、重连问题

登录聊天室是否要先连接融云

必须先连接融云，所有接口都是连接融云后才可以调用。

是否可以实现匿名登录

从融云 SDK 的角度，都是需要确定一个 UserId 来与融云服务器连接，以保证其后所有的操作都有指向性。

但作为 App 应用层来讲，可以不暴露融云的 UserId，所谓匿名就是以一个随机的或者说不跟你们应用帐号绑定的 UserId 来登录。

断线情况如何处理

进入聊天室后如果出现断开连接，当与融云服务器的连接恢复后，SDK 会尝试重连聊天室。重连过程不需要用户参与，用户可以设置聊天室状态监听，来获取聊天室重连的状态信息。

# 聊天室消息问题

进入时如何获取最新消息

对于同一个聊天室，只存储该聊天室的 50 条最新消息，也就是说移动端用户进入聊天室时，最多能够拉取到最新的 50 条消息。

可通过融云加入聊天室方法，设置获取历史消息条数，加入后可获取到对应条数的历史消息。

如何发送用户进入聊天室消息

如用户加入聊天室时，需要发送“XX加入聊天室”的通知消息，可通过融云 Server API 发送聊天室消息接口，自行向聊天室中发送一条消息，可以在消息体中附加其他需要的信息属性。

如何向应用下所有聊天室发送消息

在直播聊天场景下，如需要向应用下所有聊天室发送消息时，可使用聊天室广播消息功能，发送后所有在聊天室中的用户都将收到此条消息，如：聊天室管理通知、优惠活动系统通知等。

# 点赞、礼物消息问题

如何发送展示点赞消息

通过融云提供的自定义消息功能，定义礼物的消息类型，实现点赞功能，鉴于有些用户会连续点击，建议做消息合并机制处理。比如设置定时器，每 5 秒触发一次，将 5 秒内所有的点赞数一次性发出去，降低服务器压力，保证重要消息的畅达。

如何发送展示礼物消息

通过融云提供的自定义消息功能，定义礼物的消息类型，实现礼物功能，展示方式就是界面上的一个 View，完全可以根据你们的需求来自定义。因为聊天室类型的应用 UI 都是特殊定制的，作为融云 SDK 来讲，只是负责消息通知，并不负责 UI 绘制。

# 聊天室用户信息显示

如何显示用户昵称和头像

融云不维护用户的信息，所以用户的昵称和头像信息都需要您自己来维护管理。详细请查看用户信息显示集成指南。

如何显示用户列表

用户列表显示逻辑是根据您的需求来确定。举一个例子：聊天室人数从几百到十几万不等，比如需求定为只显示 10 个用户的头像，那就可以根据用户等级或者加入时间的顺序，选取 10 个在线用户的信息来显示。可以由应用自己的服务器来维护这个用户列表，不定时通知给全体成员，也可以每个用户加入/退出聊天室时发送状态消息，由端上接收并维护这个列表。显示的方法也是移动端进行 UI 绘制。

如何显示用户等级信息

融云不维护用户的信息，所以关于用户信息和等级的显示，都需要您自己进行开发。通常有两种处理方式：

  1. 在收到消息需要展示用户信息的时候，您可以通过您的 Server 端接口获取到用户信息来展示。
  2. 用户在发送消息时把自己的信息附加到消息中，接收方通过解析消息获得用户信息。
# 聊天室管理功能

聊天室踢人功能实现

可通过调用融云 Server API 聊天室封禁服务接口，实现将用户踢出聊天室。

设置聊天室禁言用户

可通过融云 Server API 接口，设置聊天室禁言用户，被禁言用户不能在聊天室中发送消息，详细请查看聊天室成员禁言服务。

聊天室成员自动退出机制

聊天室中用户离线后从第一条新消息产生开始计时, 倒数 30 秒退出聊天室。或离线后聊天室中产生 30 条消息时会被自动退出聊天室。如应用场景中有驻留用户，不允许被自动退出聊天室，则需要将用户加入到聊天室白名单中。

聊天室用户白名单设置方法

可通过融云 Server API 接口，设置聊天室白名单，详细请查看聊天室用户白名单服务。

聊天室自动销毁机制

聊天室中 1 小时无人说话时，同时没有人加入聊天室时，会把聊天室内所有成员踢出聊天室并销毁聊天室。

聊天室不被自动销毁实现方式

可通过融云 Server API 接口，设置需要保活的聊天室，设置后聊天室不会被自动销毁，详细请查看聊天室保活服务。

用户如何同时加入多个聊天室

默认同一用户不能同时加入多个聊天室，可通过提交工单方式开启用户同时加入多个聊天室功能。同时，在开启多设备消息同步情况下，多端用户可同时加入到多个聊天室。

如何动态获取聊天室在线人数

调用 Server API 中的查询聊天室内用户方法，可通过返回值 total 获取聊天室中在线人数。

# 聊天室消息进阶功能

消息的分级与抛弃模型

当聊天室内人数众多，消息量会变得非常大，这时可能会出现服务端超过预设承载能力或者分发的消息量超过客户端消息接收能力的情况，这时，就需要引入消息分级机制。

融云并没有对任何消息进行抛弃，但是在消息量极大的情况下，比如 1 万人到百万左右的聊天室内，消息并发量极大的情况下，每个用户端能收发到的消息和体验已经很有限，因此消息抛弃指的是确保用户端总是能收到最重要的消息，因此不重要的消息看起来就像是被抛弃了。

在开发过程中，除官方的普通文本消息之外，开发者需要针对不同的消息类别定义不同的消息类型，以便通过消息的 ObjectName 设置消息分级。目前融云支持两级消息分类，分别是高优先级消息和低优先级消息。当发生消息抛弃行为时，优先抛弃低优先级消息。

消息量大时的丢弃策略

聊天室场景下，融云服务端默认单个聊天室中上行消息处理能力是每 200 毫秒 40 条，其中 20 条为高优先级消息使用配额，另外 20 条为高优先级和低优先级消息共同使用。

在聊天室消息量较大的情况下，融云服务器会按消息发送的时间顺序，将超出消费上限的最新消息丢弃，确保服务器稳定。

针对以上情况，为保证聊天室中重要消息不被丢弃，融云提供了以下服务：

  1. 聊天室用户白名单功能，白名单中用户发送的消息受到保护，在聊天室消息量较大的情况下也不被丢弃。

  2. 聊天室消息白名单功能，该名单中的消息受到保护，在聊天室消息量较大的情况下也不被丢弃。

  3. 聊天室低级别消息设置，该功能为设置低优先级的消息类型，在聊天室消息量较大的情况下，此类型的消息将被优先抛弃，确保重要消息不被丢弃。

注：未设置情况下融云的所有消息均为高优先级消息。

以上功能设置后，服务端收到聊天室上行消息时，根据消息类型的设置状态，处理逻辑如下：

  1. 上行消息为低优先级消息，则占用高优先级和低优先级共有的 20 条消息配额，如配额已经用完，之后收到的低优先级消息将被抛弃，不占用高优先级的配额。

  2. 上行消息为默认高优先级消息，则先占用高优先级的 20 条消息配额，如配额已经用完，高优先级和低优先级共用的 20 条配额未占用完时，则占用高低优先级消息的共同配额，直到全部占用，之后收到的高、低优先级消息都将被抛弃。

  3. 上行消息为设置的聊天室消息白名单中的消息或用户白名单中的用户发送的消息时，该类消息不会丢弃，但会占用每 200 毫秒 40 条的消息配额，优先占用高、低优先级消息共用的 20 条配额，其次占用高优先级消息的 20 条配额。配额被全部占用后，再收到高、低优先级的消息时都将被丢弃，但如收到白名单中的消息时则不会被丢弃，按时间顺序正常下发。

注：单个聊天室可消费的每 200 毫秒 40 条的上行消息配额，开通专有云后可进行配置。

如何统计聊天室点赞消息数

您可以通过开通服务端实时消息路由来实现此功能，用户在发送点赞消息时，这条消息同步给您的应用服务器。您的应用服务器通过消息类型来分析统计这些数据。

查看服务端实时消息路由功能介绍。

如何实现消息回看功能

如果直播聊天室中需要实现消息回看功能，则需要开通聊天室消息云端存储功能。开通成功后，可通过接口获取聊天室中历史消息，消息回看 UI 界面的展示需要由您自己实现。

聊天室中存储的消息类型及自定义消息如何设置存储，请查看聊天室消息云端存储功能介绍。

# 多端情况下退出聊天室

多端情况下，一端退出聊天室其他终端是否同步退出聊天室

在开通了多端同时登录情况下，用户登录多个终端，加入聊天室后，如在一端退出聊天室，其他端不会同步退出，仍然可以收到聊天室中的消息，如果需要一端退出聊天室后，其他已登录的终端也一起退出聊天室，则需要在退出时发送一条命令消息通知其他端退出聊天室，此步骤需要开发者自行实现。

另外，需要注意如果用户登录终端 A 后，加入了聊天室并在聊天室的会话界面中，这时用户又登录了终端 B ，但未进入聊天室会话界面，这时 A 、B 两个终端都会收接聊天室的消息，只是 B 端的聊天室消息不进行展示。如用户在 A 端退出聊天室，这时融云认为用户在 B 端仍然在聊天室中，会继续向 B 端发送聊天室消息。如果需要 B 端同时也退出聊天室，则需要 A 端在退出时发送一条命令消息通知其他端退出聊天室，此步骤需要开发者自行实现。

文档是否解决您的问题 ?

如果遇到产品相关问题，您可 提交工单 寻求帮助