更新时间: 2021-03-08
# 功能描述
1、群组指两个以上用户一起进行聊天，群组成员信息由 App 提供并进行维系，融云只负责将消息传达给群组中的所有用户。
2、App 在后台运行或者 App 进程被杀死后可以收到推送通知。
3、每个群最大人数上限为 3000 人，App 内的群组数量没有限制，每个用户加入和创建的群组数量没有限制。
4、群主、群管理员、群公告、邀请入群、群号搜索等均为群组业务逻辑，需在 App 侧实现，融云提供必要的管理接口。
# 群组与聊天室的区别
融云提供群组与聊天室业务，其主要区别如下，客户可根据自己的业务场景进行选择：
| 功能 | 群组（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 条/秒 |
# 实现方法
# 创建群组
1、融云不会托管用户，也不管理群组的业务逻辑，因此群组的业务逻辑全部在 App 服务器进行实现，对于客户端开发人员来说，创建群组只需要与 App 服务端交互即可。
2、客户端请求 App 服务端创建群组，App 服务端调用融云创建群组接口，群组 ID 由 App 服务器自行生成，调用融云接口创建成功后，同时返回给客户端。
3、创建群组，并将用户加入该群组，用户将可以收到该群的消息。
4、每个群群成员上限 3000 人，App 内的群组数量没有限制，每个用户加入和创建的群组数量没有限制。
调用频率： 无限制
时序图如下：
请求地址： https://数据中心域名/group/create.json
请求方法： POST
签名规则： 所有请求融云服务端 API 接口的请求均需要进行规则校验，详细请参考 通用 API 接口签名规则
输入参数：
| 参数 | 类型 | 必传 | 说明 |
|---|---|---|---|
| userId | String | 是 | 要加入群的用户 Id，最多不超过 1000 个。 |
| groupId | String | 是 | 创建群组 Id，支持大小写英文字母、数字、部分特殊符号 + = - _ 的组合方式，最大长度 64 字节。 |
| groupName | String | 是 | 群组 Id 对应的名称，用于在发送群组消息显示远程 Push 通知时使用，如群组名称改变需要调用刷新群组信息接口同步。 |
返回结果：
| 返回值 | 返回类型 | 说明 |
|---|---|---|
| code | Int | 返回码，200 为正常。 |
示例代码：
Request：
POST /group/create.json HTTP/1.1 Host: api-cn.ronghub.com App-Key: uwd1c0sxdlx2 Timestamp: 1408710653491 Nonce: 14314 Signature: 45beb7cc7307889a8e711219a47b7cf6a5b000e8 Content-Type: Application/x-www-form-urlencoded userId=1&userId=2&groupId=123&groupName=TestGroup已复制
2
3
4
5
6
7
8
9
Response：
HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8 {"code":200}已复制
2
3
4
常见问题
融云不维护群的基本信息（头像、名称、群成员名片等），需要由开发者应用服务器维护。
在客户端想绕开 App 服务器直接使用融云的 SDK 创建群组这是不可能的，融云移动端 SDK 不提供创建群组的方法。
融云在创建群组、用户加入、退出群组等完成群组操作后，不会发送通知消息。创建群组、成功加入及退出群组等群通知消息，需要由客户根据自身的业务场景决定，是否发送、什么时候发送。
以融云 SealTalk 创建群组为例，发送群组通知消息的流程如下：
App 请求自己的 App Server 创建群组。
App Server 调用融云创建群组 API 接口申请创建群组。
融云 API 接口返回 200 成功后，使用发送群消息 API 接口，发送创建群组通知消息。
# 解散群组
1、将群组解散，所有用户都无法再接收该群的消息。
2、用户在 App 进行解散群组操作，该解散操作请求 App 服务器，由 App 服务器调用融云解散群组接口解散群组。
3、在开通单群聊消息云存储情况下，群组解散后，群的成员关系已经不存在，通过客户端无法在获取群存储在服务端的历史消息，保存到客户端本地的历史消息仍然可以查看。
调用频率： 无限制
时序图如下：
| 名称 | 必填 | 参数限制 | 说明 |
|---|---|---|---|
| 用户 Id | 必传 | 64 字节 | 要退出群的用户 Id。 |
| 群组 Id | 必传 | 64 字节 | 要退出的群组的 Id。 |
输入参数：
| 参数 | 类型 | 必传 | 说明 |
|---|---|---|---|
| userId | String | 是 | 操作解散群的用户 Id，可以为任何用户 Id ，非群组创建者也可以解散群组。 |
| groupId | String | 是 | 要解散的群 Id。 |
返回结果：
| 返回值 | 返回类型 | 说明 |
|---|---|---|
| code | Int | 返回码，200 为正常。 |
示例代码：
请求地址： https://数据中心域名/group/dismiss.json
请求方法： POST
签名规则： 所有请求融云服务端 API 接口的请求均需要进行规则校验，详细请参考 通用 API 接口签名规则
Request：
POST /group/dismiss.json HTTP/1.1 Host: api-cn.ronghub.com App-Key: uwd1c0sxdlx2 Timestamp: 1408710653491 Nonce: 14314 Signature: 45beb7cc7307889a8e711219a47b7cf6a5b000e8 Content-Type: Application/x-www-form-urlencoded userId=1&groupId=123已复制
2
3
4
5
6
7
8
9
Response：
HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8 {"code":200}已复制
2
3
4
常见问题
1、调用解散群组接口不会主动向 SDK 发送通知消息，如果希望给用户发送解散群组通知消息，可发送系统消息方式进行通知。
2、如开通了单群聊历史消息云存储服务，在解散群组后，服务端不会主动清除该群组的历史消息，如果再创建同样 ID 的群，客户端仍然可以拉取到之前的历史消息。如果需要清除可调用服务端删除消息功能进行清除。
# 加入群组
1、融云不会托管用户，也不管理群组的业务逻辑，因此群组的业务逻辑全部在 App 服务器进行实现，对于客户端开发人员来说，加入群组只需要与 App 服务端交互即可。
2、客户端请求 App 服务端加入群组，App 服务端调用融云加入群组接口，群组 ID 由 App 服务器管理，调用融云接口创建成功后，同时返回给客户端。
3、用户加入该群组后，用户将可以收到该群的消息。
4、默认加入群组后，只能查看加入后群组中产生的消息。如果用户加入群时希望看到群历史记录，需开通 “单群聊历史消息云存储 ” 功能，并且在开发者后台开通 “新用户获取加入群组前历史消息” 功能即可。
5、每个群群成员上限 3000 人，App 内的群组数量没有限制，每个用户加入和创建的群组数量没有限制。
调用频率： 无限制
时序图如下：
| 名称 | 必填 | 参数限制 | 说明 |
|---|---|---|---|
| 群组 Id | 必传 | 64 字节 | 要创建的群组的 Id，支持大小写英文字母、数字、部分特殊符号 + = - _ 的组合方式。 |
| 群组名称 | 必传 | 60 个字符 | 用来在 Push 推送时显示群组的名称，如果群组名称变更，可通过“更新群组信息”接口同步更新。 |
| 群组成员列表 | 必传 | 1000 个 | 要加入群的用户 Id，超过 1000 个的用户，可通过多次提交的方式添加。 |
输入参数：
| 参数 | 类型 | 必传 | 说明 |
|---|---|---|---|
| userId | String | 是 | 要加入群的用户 Id，可提交多个，最多不超过 1000 个。 |
| groupId | String | 是 | 要加入的群 Id。 |
| groupName | String | 是 | 要加入的群 Id 对应的名称。 |
返回结果：
| 返回值 | 返回类型 | 说明 |
|---|---|---|
| code | Int | 返回码，200 为正常。 |
示例代码：
请求地址： https://数据中心域名/group/join.json
请求方法： POST
签名规则： 所有请求融云服务端 API 接口的请求均需要进行规则校验，详细请参考 通用 API 接口签名规则
Request：
POST /group/join.json HTTP/1.1 Host: api-cn.ronghub.com App-Key: uwd1c0sxdlx2 Timestamp: 1408710653491 Nonce: 14314 Signature: 45beb7cc7307889a8e711219a47b7cf6a5b000e8 Content-Type: Application/x-www-form-urlencoded userId=1&userId=2&groupId=123&groupName=TestGroup已复制
2
3
4
5
6
7
8
9
Response：
HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8 {"code":200}已复制
2
3
4
# 退出群组
1、将用户从群中移除，不再接收该群组的消息。
2、用户在 App 进行退出群组操作，该退出操作请求 App 服务器，由 App 服务器调用融云退出群组接口将该用户移除群组，移除后不再接收该群组的消息。
调用频率： 无限制
时序图如下：
| 名称 | 必填 | 参数限制 | 说明 |
|---|---|---|---|
| 用户 Id | 必传 | 64 字节 | 要退出群的用户 Id。 |
| 群组 Id | 必传 | 64 字节 | 要退出的群组的 Id。 |
请求地址： https://数据中心域名/group/quit.json
请求方法： POST
签名规则： 所有请求融云服务端 API 接口的请求均需要进行规则校验，详细请参考 通用 API 接口签名规则
输入参数：
| 参数 | 类型 | 必传 | 说明 |
|---|---|---|---|
| userId | String | 是 | 要退出群的用户 Id，可提交多个，最多不超过 1000 个。 |
| groupId | String | 是 | 要退出的群 Id。 |
返回结果：
| 返回值 | 返回类型 | 说明 |
|---|---|---|
| code | Int | 返回码，200 为正常。 |
示例代码：
Request：
POST /group/quit.json HTTP/1.1 Host: api-cn.ronghub.com App-Key: uwd1c0sxdlx2 Timestamp: 1408710653491 Nonce: 14314 Signature: 45beb7cc7307889a8e711219a47b7cf6a5b000e8 Content-Type: Application/x-www-form-urlencoded userId=1&userId=2&groupId=123已复制
2
3
4
5
6
7
8
9
Response：
HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8 {"code":200}已复制
2
3
4
常见问题
1、融云不维护群的基本信息（头像、名称、群成员名片等），需要由开发者应用服务器维护。
2、调用退出群组接口不会主动向 SDK 发送通知消息，如果希望给用户发送退出群组通知消息，可发送系统消息方式进行通知。
# 群组成员查询
查询指定群组下，所有群成员 ID 信息。
调用频率： 无限制
| 名称 | 必填 | 长度限制 | 限制说明 |
|---|---|---|---|
| 群组 Id | 必传 | 64 字节 | 要查询的群组的 Id |
请求地址： https://数据中心域名/group/user/query.json
请求方法： POST
签名规则： 所有请求融云服务端 API 接口的请求均需要进行规则校验，详细请参考 通用 API 接口签名规则
输入参数：
| 参数 | 类型 | 必传 | 说明 |
|---|---|---|---|
| groupId | String | 是 | 群 Id。 |
返回结果：
| 返回值 | 返回类型 | 说明 |
|---|---|---|
| code | Int | 返回码，200 为正常。 |
| users | String | 群成员数组。 |
| id | String | 群成员 ID。 |
示例代码：
Request：
POST /group/user/query.json HTTP/1.1 Host: api-cn.ronghub.com App-Key: uwd1c0sxdlx2 Nonce: 14314 Timestamp: 1408710653491 Signature: 45beb7cc7307889a8e711219a47b7cf6a5b000e8 Content-Type: application/x-www-form-urlencoded groupId=123已复制
2
3
4
5
6
7
8
9
Response：
HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8 {"code":200,"users":[{"id":"10001"},{"id":"10002"},{"id":"10000"},{"id":"10003"}]}已复制
2
3
4
# 刷新群组信息
当群组名称变更时，App Server 应该调用此接口刷新在融云侧保存的群组信息，以保证融云发送远程推送（PUSH）提醒的时候，能够正确显示相关内容信息。
刷新群组信息后 5 分钟内生效，Push 推送时将显示刷新后的群组名称。
调用频率： 无限制
| 名称 | 必填 | 长度限制 | 限制说明 |
|---|---|---|---|
| 群组 Id | 必传 | 64 字节 | 要修改的群组的 Id |
| 群组名称 | 必传 | 60 个字符 | 要修改的群组的名称 |
请求地址： https://数据中心域名/group/refresh.json
请求方法： POST
签名规则： 所有请求融云服务端 API 接口的请求均需要进行规则校验，详细请参考 通用 API 接口签名规则
输入参数：
| 参数 | 类型 | 必传 | 说明 |
|---|---|---|---|
| groupId | String | 是 | 群组 Id。 |
| groupName | String | 是 | 群组名称。 |
返回结果：
| 返回值 | 返回类型 | 说明 |
|---|---|---|
| code | Int | 返回码，200 为正常。 |
示例代码：
Request：
POST /group/refresh.json HTTP/1.1 Host: api-cn.ronghub.com App-Key: uwd1c0sxdlx2 Nonce: 14314 Timestamp: 1408710653491 Signature: 45beb7cc7307889a8e711219a47b7cf6a5b000e8 Content-Type: application/x-www-form-urlencoded groupId=123&groupName=new已复制
2
3
4
5
6
7
8
9
Response：
HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8 {"code":200,"users":[{"id":"10001"},{"id":"10002"},{"id":"10000"},{"id":"10003"}]}已复制
2
3
4
注意事项:
此功能不会更新客户端的群组信息，客户端群信息功能查看 iOS 群信息 或 Android 群信息 开发文档。
# 查询用户所在群组
根据用户 ID 查询该用户加入的所有群组信息
调用频率： 无限制
| 名称 | 必填 | 长度限制 | 说明 |
|---|---|---|---|
| 用户 Id | 必传 | 64 字节 | 要查询的用户 Id |
请求地址： https://数据中心域名/user/group/query.json
请求方法： POST
签名规则： 所有请求融云服务端 API 接口的请求均需要进行规则校验，详细请参考 通用 API 接口签名规则
输入参数：
| 参数 | 类型 | 必传 | 说明 |
|---|---|---|---|
| userId | String | 是 | 用户 Id。 |
返回结果：
| 返回值 | 返回类型 | 说明 |
|---|---|---|
| code | Int | 返回码，200 为正常。 |
| groups | String | 用户加入的群信息数组。 |
| name | String | 群名称。 |
| id | String | 群组 Id。 |
示例代码：
Request：
POST /user/group/query.json HTTP/1.1 Host: api-cn.ronghub.com App-Key: uwd1c0sxdlx2 Nonce: 14314 Timestamp: 1408710653491 Signature: 45beb7cc7307889a8e711219a47b7cf6a5b000e8 Content-Type: application/x-www-form-urlencoded userId=123已复制
2
3
4
5
6
7
8
9
Response：
HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8 { "code":200, "groups":[ { "name":"GroupName_1", "id":"GroupId_1" }, { "name":"GroupName_8", "id":"GroupId_8" }] }已复制
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# 同步用户群组
如果在集成融云前 App Server 已有群组数据，可使用此服务进行同步，当第一次连接融云服务器时，需要向融云服务器提交 userId 对应的用户当前所加入的所有群组，此接口主要为防止应用中用户群信息同融云已知的用户所属群信息不同步。
请求地址： https://数据中心域名/group/sync.json
请求方法： POST
签名规则： 所有请求融云服务端 API 接口的请求均需要进行规则校验，详细请参考 通用 API 接口签名规则
输入参数：
| 参数 | 类型 | 必传 | 说明 |
|---|---|---|---|
| userId | String | 是 | 被同步群信息的用户 Id。 |
| group[id]=name | String | 否 | 该用户所属的群信息，如群 Id 已经存在，则不会刷新对应群组名称，如果想刷新群组名称请调用刷新群组信息方法。此参数可传多个，参见下面示例。 |
当不提交 group[id]=name 参数时，表示解除 userId 对应群的绑定关系；
返回结果：
| 返回值 | 返回类型 | 说明 |
|---|---|---|
| code | Int | 返回码，200 为正常。 |
示例代码：
Request：
POST /group/sync.json HTTP/1.1 Host: api-cn.ronghub.com App-Key: uwd1c0sxdlx2 Timestamp: 1408710653491 Nonce: 14314 Signature: 45beb7cc7307889a8e711219a47b7cf6a5b000e8 Content-Type: application/x-www-form-urlencoded userId=2014&group[10001]=TestGroup1&group[10002]=TestGroup2&group[10003]=TestGroup3已复制
2
3
4
5
6
7
8
9
Response：
HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8 {"code":200}已复制
2
3
4