群组业务概述
群聊是即时通讯类应用中常见的多人通讯方式,一般包含两个及以上的用户。群组业务支持丰富的功能,包括群组成员管理、禁言管理,离线消息推送及历史消息记录漫游,适用于兴趣群、办公群、客服服务沟通等。
在控制台创建应用后,默认支持群组业务,不需要申请开通。在默认情况下,融云不维护群组成员的资料(头像、名称、群成员名片等)只负责将消息传达给群组中的所有用户。对于创建、解散、加入、退出群组等群组管理操作,必须由 App 服务器请求融云服务端 API 实现,融云客户端 SDK 不提供相应方法。如果您希望将群组及群成员资料信息托管在融云,请开启用户信息托管。
每个 App Key 下可创建的群组数量没有限制,单个群组成员上限为 3000 人,且单个用户可加入的群组数量不受限制。若需要实现历史记录漫游功能,可通过控制台 IM 服务管理页面为 App Key 开启单群聊消息云端存储服务,使用即时通讯服务提供的消息存储服务。该服务适用于 IM 旗舰版或IM 尊享版,具体功能与费请参阅官方价格说明页面及计费说明文档。
开启信息托管
信息托管功能是指将应用中的用户信息托管到融云服务器,由融云提供客户端和服务端的接口,帮助开发者管理和维护用户资料信息。开启该功能视为同意将这些信息存储在融云服务器上,开发者可通过融云提供的 API 设置和更新用户的资料信息。用户信息托管后,应用可以进一步使用融云提供的群组管理、群成员管理以及好友关系管理等 API,简化社交功能的开发和维护,提升应用的管理能力与用户体验。
如果您希望将群组及群成员资料信息托管在融云,可以在融云控制台(IM 服务>信息托管服务>功能设置)中开启服务后,使用托管服务中提供的群组管理功能,进行群组资料的管理和维护。融云信息托管服务中提供全新群组管理能力,支持通过服务端 API 和客户端 SDK 进行群组管理。
群组管理功能
- 未开启用户信息托管的群组
- 开启用户信息托管的群组
下表列出了即时通讯服务端提供的非托管能力的群组基础管理接口。
未开启使用融云信息托管服务时,群组业务逻辑,如群主、群管理员、群公告、邀请入群、群号搜索等,均需在应用侧自行实现。
功能分类 | 功能描述 | 即时通讯服务端 API |
---|---|---|
创建、解散群组 | 提供创建者用户 ID、群组 ID、和群名称,向即时通讯服务端申请建群。如解散群组,则群成员关 系不复存在。 | 创建群组、解散群组 |
加入、退出群组 | 加入群组后,默认可查看入群以后产生的新消息。退出群组后,不再接收该群的新消息。 | 加入群组、退出群组 |
修改即时通讯服务端的群组信息 | 修改在即时通讯的推送服务中使用的群组信息。 | 刷新群组信息 |
查询群组成员 | 查询指定群组所有成员的用户 ID 信息。 | 查询群组成员 |
查询用户所在群组 | 根据用户 ID 查询该用户加入的所有群组,返回群组 ID 及群组名称。即时通讯服务不存储群组资料信息,群组资料及群成员信息需要开发者在应用服务器自行维护,如应用服务端维护的用户群组关系有缺失时,可通过此接口来核对校验。 | 查询用户所在群组 |
同步用户所在群组 | 向即时通讯服务端同步指定用户当前所加入的所有群组,防止应用中的用户群组信息与即时通讯服务端的用户所属群信息不一致。如果在集成即时通讯服务前 App Server 上已有群组及成员数据,第一次连接即时通讯服务时,可使用此接口向即时通讯服务端同步已有的用户与群组对应关系。 | 同步用户所在群组 |
群组单人禁言 | 在指定的单个群组中或全部群组中,禁言一个或多个用户。被禁言用户可以接收查看群组中其他用户消息,但不能通过客户端 SDK 发送消息。 | 单人禁言 |
群组全体禁言 | 将群组全体成员禁言。被禁言群组的所有成员均不能发送消息,需要某些用户可以发言时,可将此用户加入到群禁言用户白名单中。 | 全体禁言 |
群组禁言用户白名单 | 群组被整体禁言后,禁言白名单中用户可以发送群消息。 | 全体成员禁言白名单 |
下表列出了信息托管服务中支持的群组托管功能接口。
- 使用信息托管服务,在进行群组管理操作时,群成员会收到操作状态通知回调,如:创建、主动加入、邀请加入、踢出、退出、解散、添加管理员、移除管理员、转移群主等,因为通知使用消息方式实现,所以将计入群消息的分发和下行数据统计。
- 通过非托管功能创建群组,如果需要使用群组托管能力,需要调用“导入群托管数据”接口,设置群组所有者(群主)及群组的默认权限后才能使用。
功能分类 | 功能描述 | 即时通讯服务端 API |
---|---|---|
创建群组 | 创建一个群组,默认群主为创建者。 | 创建群组-托管 |
解散群组 | 将指定群组解散,只有角色为群主的用户可以进行解散操作,解散后群成员关系不复存在。 | 解散群组-托管 |
设置群组资料 | 提供修改群组的名称、头像、简介等内置信息及自定义的群组资料信息。 | 设置群组资料-托管 |
批量获取群组资料 | 获取指定多个群组的资料信息。 | 批量获取群组资料-托管 |
踢出群组 | 指定用户踢出群组,只有具有踢出权限的用户可以进行此操作。 | 踢出群组-托管 |
转让群组 | 将群主角色转让给群组中其他成员,转让后可选择是否在群组中或退出群组。 | 转让群组-托管 |
加入群组 | 用户加入指定群组,用户加入的群组数没有上限限制。 | 加入群组-托管 |
退出群组 | 用户退出指定群组,退出后不再接收该群的新消息。 | 退出群组-托管 |
将指定用户踢出所有群组 | 将指定用户从所有不是群主角色的群组中踢出,该用户所有群主角色的群需要先转让群主后才能退出群组。 | 将指定用户踢出所有群组-托管 |
设置群管理员 | 设置指定一个群的成员为群管理员。 | 设置群管理员-托管 |
移除群管理员 | 移除管理员权限,将群管理员角色设置为普通群成员。 | 移除群管理员-托管 |
分页获取群成员信息 | 分页方式获取指定一个群组的成员信息。 | 分页获取群成员信息-托管 |
获取指定群成员信息 | 获取一个群组中指定多个成员的资料信息。 | 获取指定群成员信息-托管 |
设置群成员资料 | 设置一个群成员的备注名及自定义附加信息。 | 设置群成员资料-托管 |
设置群名称备注名 | 设置用户所在指定群组的群名称备注名,设置后该备注名只对设置用户有效,其他群成员不可见。 | 设置群名称备注名-托管 |
设置特别关注群成员 | 特别关注指定群成员后,该成员发送的消息不受免打扰的影响。 | 设置特别关注群成员-托管 |
分页查询应用下群组 | 分页方式获取指定 AppKey 下的群组列表。 | 分页查询应用下群组-托管 |
分页查询用户加入的群组 | 分页方式获取用户加入的所有群组列表。 | 分页查询用户加入的群组-托管 |
群组托管导入功能 | 针对不是使用群托管功能创建的群组,需要先通过此接口设置群主及群权限后,才能调用群托管相关功能。 | 群组托管导入功能-托管 |
群聊消息功能
群聊消息功能与单聊业务类似,共用部分 API 及配置。
否开启用户托管不影响群聊消息功能。
功能 | 描述 | 客户 端 API | 即时通讯服务端 API |
---|---|---|---|
发送消息 | 可发送普通消息与媒体消息,例如文本、图片、GIF 等。支持在发送消息时添加 @ 信息。 | 支持 | 发送群聊消息 |
发送群聊定向消息 | 可发送普通消息与媒体消息给群组中的指定的一个或多个成员,其他成员不会收到该消息。 | 支持 | 发送群聊定向消息 |
接收消息 | 监听并实时接收消息,或在客户端上线时接收离线消息。 | 支持 | 不提供该 API |
群聊消息已读回执 | 发送群消息后如需要查看消息的阅读状态,需要先发送回执请求,在通过接受者的响应获取已读数据。 | 支持 | 不提供该 API |
离线消息 | 支持离线消息存储,存储时间可设置(1 ~ 7 天),默认存储 7 天内的所有群消息,支持调整存储时长与存储的群消息数量。 | 支持 | 不提供该 API |
离线消息推送 | 离线状态下,群组中有新消息时,支持 Push 通知。 | 支持 | 不提供该 API |
撤回消息 | 消息发送成功后可撤回该条消息。 | 支持 | 撤回消息 |
本地搜索消息 | 消息存储在本地(移动端),支持按关键字或用户搜索本地指定会话的消息内容。 | 支持 | 不提供该 API |
获取历史消息 | 从本地数据库或远端获取历史消息。注意,从远端获取历史消息需要开通单群聊消息云存储服务,默认存储时长为 6 个月。 | 支持 | 不提供该 API |
获取历史消息日志 | 即时通讯服务端可以保存 APP 内所有会话的历史消息记录,历史消息记录以日志文件方式提供,并已经过压缩。您可以使用服务端 API 获取、删除指定 App 的历史消息日志 | 不提供该 API | 获取历史消息日志 |
本地插入消息 | 在本地数据库中插入消息。本地插入的消息不会实际发送给服务器和对方。 | 支持 | 不提供该 API |
删除消息 | 支持按会话删除本地和存储在服务器的指定消息或会话中全部历史消息。 | 支持 | 消息清除 |
单群聊消息扩展 | 为原始消息增加状态标识(扩展数据为 KV 键值对),提供添加、删除、查询扩展信息的接口。 | 支持 | 单/群聊消息扩展 |
自定义消息类型 | 如果内置消息类型满足不了您的需求,可以自定义消息类型。支持自定义普通消息类型与自定义媒体消息类型。服务端直接发送自定义消息即可,注意消息内容结构需要与客户端定义的消息类型保持一致。 | 支持 | 发送群聊消息 |
默认新入群的成员的用户仅可接收加入群组后产生的消息。如果需要查看入群之前的历史消息,请为 App Key 开启以下两项服务(请注意区分开发/生产环境):
从控制台 IM 服务管理页面开启单群聊消息云端存储服务。开启该服务后,可使用即时通讯服务提供的消息存储服务,实现消息历史记录漫游。IM 旗舰版或IM 尊享版可开通该服务。具体功能与费用以官方价格说明页面及计费说明文档为准。
- 从控制台免费基础功能页面开启新用户获取加入群组前历史消息。
群聊会话功能
群聊会话功能与单聊业务类似,共用部分 API 及配置。
否开启用户托管不影响群聊会话功能。
功能 | 描述 | 客户端 API | 即时通讯服务端 API |
---|---|---|---|
获取会话 | SDK 会根据收发的消息在本地数据库中生成对应会话。您可以从本地数据库获取 SDK 生成的会话列表。 | 支持 | 不提供该 API |
获取会话未读消息 | 从指定会话中获取未读消息,可满足 App 跳转到第一条未读消息、展示全部未读 @ 消息的需求。 | 支持 | 不提供该 API |
处理会话未读消息数 | 获取或清除会话中的未读消息数,可用于 UI 展示。 | 支持 | 不提供该 API |
删除会话 | 从 SDK 生成的会话列表中删除一个会话或多个会话 | 支持 | 不提供该 API |
会话草稿 | 保存一条草稿内容至指定会话。 | 支持 | 不提供该 API |
输入状态 | 可设置指定的群聊会话,收到新的消息后是否进行提醒,默认进行新消息提醒。 | 支持 | 不提供该 API |
管理会话标签 | 创建和管理标签信息数据,用于对会话进行标记分组。每个用户最多可以创建 20 个标签。App 用户创建的标签信息数据会同步即时通讯服务端。 | 支持 | 不提供该 API |
设置与使用会话标签 | 使用会话标签对会话进行分组。 | 支持 | 不提供该 API |
会话置顶 | 在会话列表中将指定会话置顶。 | 支持 | 会话置顶 |
会话免打扰 | 控制用户在客户端设备离线时,是否可针对离线消息接收推送通知。支持按照会话或按会话类型设置免打扰。 | 支持 | 免打扰功能概述 |
多端同步会话免打扰/置顶状态 | SDK 提供了会话状态(置顶或免打扰)同步机制,通过设置会话状态同步监听器,当在其它端修改会话状态时,可在本端实时监听到会话状态的改变。 | 支持 | 不提供该 API |
多端同步阅读状态 | 在同一用户账户的多个设备间主动同步会话的阅读状态。 | 支持 | 不提供该 API |
群组与聊天室的区别
即时通讯服务提供群组与聊天室业务,其主要区别如下,客户可根据自己的业务场景进行选择:
功能 | 群组(group) | 聊天室(Chatroom) |
---|---|---|
场景 | 类似微信的群组,无论是否在线都会接收消息 | 只有在线用户可接收消息,可用于直播、社区、游戏、广场交友、兴趣讨论等场景。 |
离线缓存消息 | 支持离线消息存储,存储时间可设置(1 ~ 7 天),默认存储 7 天。 | 无离线消息,只有在线用户才可收到聊天室消息 |
人数限制 | 默认一个群上限为 3000 人 | 聊天室人数无上限 |
消息提醒 | 离线状态,群组中有新消息时,支持远程推送(PUSH)通知 | 离开聊天室后不再接收消息 |
本地存储 | 移动端本地数据库存储,提供本地消息搜索接口 | 退出聊天室后同时删除本地聊天室消息,不支持消息搜索功能 |
云端存储 | 需开通单群聊消息云存储,可以提供 6 - 36 个月存储服务 | 需开通聊天室消息云存储,可以提供 2 - 36 个月存储服务 |
用户加入限制 | 一个用户可加入多个群组,无限制 | 默认一个用户只能加入一个聊天室,加入多个聊天室功能可在控制台自行开通 |
加入后消息获取逻辑 | 默认加入群组后,只能查看加入后群组中产生的消息。如需要查看群历史消息,则需要开通单群聊消息云存储后,再开通“查看加入前群消息”功能 | 加入后可获取聊天室中最新的 50 条消息。 |
销毁/解散逻辑 | 需要通过 AppServer 自行调用解散群组接口。 | 提供销毁聊天室接口,可通过 AppServer 调用。同时聊天室中 1 小时内没有消息产生时,将自动销毁聊天室。 |
消息可靠度 | 100% 可靠,不丢消息。 | 消息量较大时,超出服务端消费上限的消息将被主动抛弃。您可通过用户白名单、消息白名单、自定义消息级别等服务,改变消息抛 弃策略。如果用户在聊天室的用户白名单内,该用户所发送的消息在消息量大时也不会被抛弃。 如需了解服务端消费上限与如何改变消息抛弃策略,可参见服务端文档消息优先级服务、聊天室白名单服务。 |
相关接口调用 | SDK 不提供群组管理功能接口,通过 Server API 提供群组功能接口。 | SDK 和 Server API 同时提供功能接口,销毁聊天室操作只能通过 Server API 方式调用。 |
发送消息频率 | 每个客户端 5 条/秒;服务端调用,20 条/秒 | 每个客户端 5 条/秒;服务端调用,100 条/秒 |