群组

群组的所有写操作都有可选line和payload参数。因为写操作会触发通知消息，如果系统默认通知消息不符合您的需求，可以使用这两个参数来自定义通知消息，详情请参考常见问题

1. 自定义群通知

所有的写操作都会触发群通知。群通知有两个作用，一个是用来告知用户状态改变；另外一个作用是触发客户端协议栈从服务器更新群信息。协议栈需要解析群通知内容来决定是否更新本地群信息，所以当需要自定义群通知时，一定要确保通知消息的内容和格式和消息类型保持不变，可以扩展jsoin的内容，或者使用extra，否则就会出现群信息更新不及时的问题。

2. 优先使用SDK

我们提供有Java版本的SDK，建议使用Java语言的客户使用这个SDK，其它语言可以按照本文档对接。

3. 创建群组

3.0.1. 地址

http://domain:18080/admin/group/create

3.0.2. body

参数	类型	必需	描述
operator	string	是	操作者用户ID
group	json	是	群参数，建议不填写群ID，由系统自动生成
to_lines	int[]	否	会话线路，默认为0
notify_message	json	否	消息负载，如果不填写，系统会发出内置通知消息，如果填写，覆盖系统通知消息

3.0.3. 响应

参数	类型	必需	描述
group_id	string	是	群组ID

3.0.4. 示例

curl -X POST -H "nonce:76616" -H "timestamp":"1558350862502" -H "sign":"b98f9b0717f59febccf1440067a7f50d9b31bdde" -H "Content-Type:application/json" -d   \
  "{                       \
    \"operator\":\"a\",       \
    \"group\":{                 \
        \"group_info\":{              \
               \"name\": \"老王和他的朋友们\",     \
               \"owner\": \"laowang\",      \
             \"type\": 3                  \
          },                              \
          \"members\": [                  \
          {                              \
                 \"member_id\": \"memberId1\",  \
                 \"alias\": \"老王的朋友1\",       \
                 \"type\": \"0\"        \
            }                            \
        ]                            \
      }                             \
    }"                                \
  http://localhost:18080/admin/group/create

{
  "code":0,
  "msg":"success",
  "result":{
    "group_id":"groupId1"
  }
}

4. 销毁群组

4.0.1. 地址

http://domain:18080/admin/group/del

4.0.2. body

参数	类型	必需	描述
operator	string	是	操作者用户ID
group_id	string	是	群组ID
to_lines	int[]	否	会话线路，默认为0
notify_message	json	否	消息负载，如果不填写，系统会发出内置通知消息，如果填写，覆盖系统通知消息

4.0.3. 响应

无

4.0.4. 示例

curl -X POST -H "nonce:76616" -H "timestamp":"1558350862502" -H "sign":"b98f9b0717f59febccf1440067a7f50d9b31bdde" -H "Content-Type:application/json" -d   \
  "{                       \
    \"operator\":\"a\",       \
    \"group_id\":\"groupId1\"    \
    }"                                \
  http://localhost:18080/admin/group/del

{
  "code":0,
  "msg":"success"
}

5. 获取群组信息

5.0.1. 地址

http://domain:18080/admin/group/get_info

5.0.2. body

参数	类型	必需	描述
groupId	string	是	群组ID，参数是驼峰式的，为了兼容旧的SDK保持现状吧

5.0.3. 响应

参数	类型	必需	描述
GroupInfo	json	是	群信息

5.0.4. 示例

curl -X POST -H "nonce:76616" -H "timestamp":"1558350862502" -H "sign":"b98f9b0717f59febccf1440067a7f50d9b31bdde" -H "Content-Type:application/json" -d   \
  "{                       \
    \"groupId\":\"groupId1\"    \
    }"                                \
  http://localhost:18080/admin/group/get_info

{
  "code":0,
  "msg":"success",
  "result":{
    "target_id":"groupId1",
    "name":"老王和他的朋友们",
    "owner":"laowang",
    "type":3
  }
}

6. 批量获取群组信息

6.0.1. 地址

http://domain:18080/admin/group/batch_infos

6.0.2. body

参数	类型	必需	描述
groupIds	string[]	是	群组ID数组

6.0.3. 响应

参数	类型	必需	描述
groupInfoList	json[]	是	群信息列表

6.0.4. 示例

curl -X POST -H "nonce:76616" -H "timestamp":"1558350862502" -H "sign":"b98f9b0717f59febccf1440067a7f50d9b31bdde" -H "Content-Type:application/json" -d   \
  "[                       \
    \"groupId1\",\"groupId2\",\"groupId3\"    \
    ]"                                \
  http://localhost:18080/admin/group/batch_infos

{
  "code":0,
  "msg":"success",
  "result":{
    "groupInfoList":[
      {
        "target_id":"groupId1",
        "name":"老王和他的朋友们",
        "owner":"laowang",
        "type":3  
      },
      {
        "target_id":"groupId2",
        "name":"老王和他的朋友们",
        "owner":"laowang",
        "type":3  
      },
      {
        "target_id":"groupId3",
        "name":"老王和他的朋友们",
        "owner":"laowang",
        "type":3  
      },
    ]
  }
}

7. 转移群组

7.0.1. 地址

http://domain:18080/admin/group/transfer

7.0.2. body

参数	类型	必需	描述
operator	string	是	操作者用户ID
group_id	string	是	群组ID
new_owner	string	是	新群主用户ID
to_lines	int[]	否	会话线路，默认为0
notify_message	json	否	消息负载，如果不填写，系统会发出内置通知消息，如果填写，覆盖系统通知消息

7.0.3. 响应

无

7.0.4. 示例

curl -X POST -H "nonce:76616" -H "timestamp":"1558350862502" -H "sign":"b98f9b0717f59febccf1440067a7f50d9b31bdde" -H "Content-Type:application/json" -d   \
  "{                       \
    \"operator\":\"a\",       \
    \"group_id\":\"groupId1\",    \
    \"new_owner\":\"newOwner\",    \
    }"                                \
  http://localhost:18080/admin/group/transfer

{
  "code":0,
  "msg":"success"
}

8. 修改群组信息

8.0.1. 地址

http://domain:18080/admin/group/modify

8.0.2. body

参数	类型	必需	描述
operator	string	是	操作者用户ID
group_id	string	是	群组ID
type	int	是	修改资料类型, 0 群名, 1 群头像, 2 群extra, 3 群全局禁言, 4 群加入方式, 5 禁止私聊, 6 是否允许搜索群组, 7 是否允许新成员查看历史消息, 8 群组最大成员数
value	string	是	修改资料的值，请仔细阅读后面针对value字段的说明
to_lines	int[]	否	会话线路，默认为0
notify_message	json	否	消息负载，如果不填写，系统会发出内置通知消息，如果填写，覆盖系统通知消息

value在不同的type下具有不同的意义。boolean值转化为"0"和"1", int类型转化为字符串，比如“1”/”2“/“3”。

type	type含义	value类型	value含义
0	群名	string	群名称
1	群头像	string	群头像链接地址
2	群extra	string	群附加信息，系统不会发默认群通知，如果需要群通知，请自定义新的群通知，然后发送时带上对应消息payload
3	群全局禁言	boolean	0 取消禁言；1全局禁言
4	群加入方式	int	0 所有人都可以加入；1 仅群成员邀请加入；2仅群管理员或群主邀请加入。更复杂控制，请应用服务进行二次开发
5	禁止私聊	boolean	0 允许私聊；1 禁止群成员私聊
6	是否允许搜索群组	boolean	0 不允许；1 允许。实际上IM服务没有实现此功能，如果应用二开搜索功能可以使用此字段
7	是否允许新加入成员查看历史消息	boolean	0 不允许；1 允许
8	群组最大成员数	int
9	超级群组（专业版IM服务支持）	int	0普通群组，1超级群组

8.0.3. 响应

无

8.0.4. 示例

curl -X POST -H "nonce:76616" -H "timestamp":"1558350862502" -H "sign":"b98f9b0717f59febccf1440067a7f50d9b31bdde" -H "Content-Type:application/json" -d   \
  "{                       \
    \"operator\":\"a\",       \
    \"group_id\":\"groupId1\",    \
    \"type\":3,    \
    \"value\":\"1\"    \
    }"                                \
  http://localhost:18080/admin/group/modify

{
  "code":0,
  "msg":"success"
}

9. 获取群组成员列表

9.0.1. 地址

http://domain:18080/admin/group/member/list

9.0.2. body

参数	类型	必需	描述
groupId	string	是	群组ID，参数是驼峰式的，为了兼容旧的SDK保持现状吧

9.0.3. 响应

参数	类型	必需	描述
GroupMember	list<json>	是	群成员

9.0.4. 示例

curl -X POST -H "nonce:76616" -H "timestamp":"1558350862502" -H "sign":"b98f9b0717f59febccf1440067a7f50d9b31bdde" -H "Content-Type:application/json" -d   \
  "{                       \
    \"groupId\":\"groupId1\"    \
    }"                                \
  http://localhost:18080/admin/group/member/list

{
  "code":0,
  "msg":"success",
  "result":[{
    "member_id":"groupMember1",
    "alias":"laoda",
    "type":2
  },
  {
    "member_id":"groupMember1",
    "type":0
  }
  ]
}

10. 获取群组成员

10.0.1. 地址

http://domain:18080/admin/group/member/get

10.0.2. body

参数	类型	必需	描述
groupId	string	是	群组ID
memberId	string	是	成员用户ID

10.0.3. 响应

参数	类型	必需	描述
GroupMember	json	是	群成员

10.0.4. 示例

curl -X POST -H "nonce:76616" -H "timestamp":"1558350862502" -H "sign":"b98f9b0717f59febccf1440067a7f50d9b31bdde" -H "Content-Type:application/json" -d   \
  "{                       \
    \"groupId\":\"groupId1\",    \
    \"memberId\":\"userId1\"    \
    }"                                \
  http://domain:18080/admin/group/member/get

{
  "code":0,
  "msg":"success",
  "result":{
    "member_id":"userId1",
    "alias":"laoda",
    "type":2
  }
}

11. 添加群组成员

11.0.1. 地址

http://domain:18080/admin/group/member/add

11.0.2. body

参数	类型	必需	描述
operator	string	是	操作者用户ID
group_id	string	是	群组ID
members	list<json>	是	群成员，成员类型只能为0/1
to_lines	int[]	否	会话线路，默认为0
member_extra	string	否	群成员的extra信息
notify_message	json	否	消息负载，如果不填写，系统会发出内置通知消息，如果填写，覆盖系统通知消息

11.0.3. 响应

无

11.0.4. 示例

curl -X POST -H "nonce:76616" -H "timestamp":"1558350862502" -H "sign":"b98f9b0717f59febccf1440067a7f50d9b31bdde" -H "Content-Type:application/json" -d   \
  "{                       \
    \"operator\":\"a\",       \
    \"group_id\":\"groupId1\",    \
    \"members\": [                  \
        {                              \
          \"member_id\": \"memberId1\",  \
          \"alias\": \"老王的朋友2\",       \
          \"type\": \"0\"        \
        }                            \
      ]                            \
    }"                                \
  http://localhost:18080/admin/group/member/add

{
  "code":0,
  "msg":"success"
}

12. 移除群组成员

12.0.1. 地址

http://domain:18080/admin/group/member/del

12.0.2. body

参数	类型	必需	描述
operator	string	是	操作者用户ID
group_id	string	是	群组ID
members	list	是	群成员id，不能包含群主。
to_lines	int[]	否	会话线路，默认为0
notify_message	json	否	消息负载，如果不填写，系统会发出内置通知消息，如果填写，覆盖系统通知消息

12.0.3. 响应

无

12.0.4. 示例

curl -X POST -H "nonce:76616" -H "timestamp":"1558350862502" -H "sign":"b98f9b0717f59febccf1440067a7f50d9b31bdde" -H "Content-Type:application/json" -d   \
  "{                       \
    \"operator\":\"a\",       \
    \"group_id\":\"groupId1\",    \
    \"members\": [                  \
        \"memberId1\",  \
        \"memberId2\"  \
      ]                            \
    }"                                \
  http://localhost:18080/admin/group/member/del

{
  "code":0,
  "msg":"success"
}

13. 群组成员退出

13.0.1. 地址

http://domain:18080/admin/group/member/quit

13.0.2. body

参数	类型	必需	描述
operator	string	是	退群用户ID
group_id	string	是	群组ID
to_lines	int[]	否	会话线路，默认为0
notify_message	json	否	消息负载，如果不填写，系统会发出内置通知消息，如果填写，覆盖系统通知消息

13.0.3. 响应

无

13.0.4. 示例

curl -X POST -H "nonce:76616" -H "timestamp":"1558350862502" -H "sign":"b98f9b0717f59febccf1440067a7f50d9b31bdde" -H "Content-Type:application/json" -d   \
  "{                       \
    \"operator\":\"a\",       \
    \"group_id\":\"groupId1\"    \
    }"                                \
  http://localhost:18080/admin/group/member/quit

{
  "code":0,
  "msg":"success"
}

14. 设置/修改群组成员昵称

14.0.1. 地址

http://domain:18080/admin/group/member/set_alias

14.0.2. body

参数	类型	必需	描述
operator	string	是	操作者用户ID
group_id	string	是	群组ID
memberId	string	是	群组成员用户ID
alias	string	否	群昵称
to_lines	int[]	否	会话线路，默认为0
notify_message	json	否	消息负载，如果不填写，系统会发出内置通知消息，如果填写，覆盖系统通知消息

14.0.3. 响应

无

14.0.4. 示例

curl -X POST -H "nonce:76616" -H "timestamp":"1558350862502" -H "sign":"b98f9b0717f59febccf1440067a7f50d9b31bdde" -H "Content-Type:application/json" -d   \
  "{                       \
    \"operator\":\"a\",       \
    \"group_id\":\"groupId1\",    \
    \"memberId\":\"memberId1\",   \
    \"alias\":\"hello\"   \
    }"                                \
  http://localhost:18080/admin/group/member/set_alias

{
  "code":0,
  "msg":"success"
}

15. 设置/修改群组成员附加信息

15.0.1. 地址

http://domain:18080/admin/group/member/set_extra

15.0.2. body

参数	类型	必需	描述
operator	string	是	操作者用户ID
group_id	string	是	群组ID
memberId	string	是	群组成员用户ID
extra	string	否	群成员附加信息
to_lines	int[]	否	会话线路，默认为0
notify_message	json	否	消息负载，如果不填写，系统会发出内置通知消息，如果填写，覆盖系统通知消息

15.0.3. 响应

无

15.0.4. 示例

curl -X POST -H "nonce:76616" -H "timestamp":"1558350862502" -H "sign":"b98f9b0717f59febccf1440067a7f50d9b31bdde" -H "Content-Type:application/json" -d   \
  "{                       \
    \"operator\":\"a\",       \
    \"group_id\":\"groupId1\",    \
    \"memberId\":\"memberId1\",   \
    \"extra\":\"hello extra\"   \
    }"                                \
  http://localhost:18080/admin/group/member/set_extra

{
  "code":0,
  "msg":"success"
}

16. 设置/取消群管理员

16.0.1. 地址

http://domain:18080/admin/group/manager/set

16.0.2. body

参数	类型	必需	描述
operator	string	是	操作者用户ID
group_id	string	是	群组ID
members	list	是	群成员ID
is_manager	boolean	是	true 设置为群管理；false 取消群管理员。
to_lines	int[]	否	会话线路，默认为0
notify_message	json	否	消息负载，如果不填写，系统会发出内置通知消息，如果填写，覆盖系统通知消息

16.0.3. 响应

无

16.0.4. 示例

curl -X POST -H "nonce:76616" -H "timestamp":"1558350862502" -H "sign":"b98f9b0717f59febccf1440067a7f50d9b31bdde" -H "Content-Type:application/json" -d   \
  "{                       \
    \"operator\":\"a\",       \
    \"group_id\":\"groupId1\",    \
    \"members\": [                  \
        \"memberId1\",  \
      ]                            \
    }"                                \
  http://localhost:18080/admin/group/manager/set

{
  "code":0,
  "msg":"success"
}

17. 设置/取消群白名单成员

17.0.1. 地址

http://domain:18080/admin/group/manager/allow

17.0.2. body

参数	类型	必需	描述
operator	string	是	操作者用户ID
group_id	string	是	群组ID
members	list	是	群成员ID
is_manager	boolean	是	true 设置为群白名单成员；false 取消群白名单成员。
to_lines	int[]	否	会话线路，默认为0
notify_message	json	否	消息负载，如果不填写，系统会发出内置通知消息，如果填写，覆盖系统通知消息

17.0.3. 响应

无

17.0.4. 示例

curl -X POST -H "nonce:76616" -H "timestamp":"1558350862502" -H "sign":"b98f9b0717f59febccf1440067a7f50d9b31bdde" -H "Content-Type:application/json" -d   \
  "{                       \
    \"operator\":\"a\",       \
    \"group_id\":\"groupId1\",    \
    \"members\": [                  \
        \"memberId1\",  \
      ]                            \
    }"                                \
  http://localhost:18080/admin/group/manager/allow

{
  "code":0,
  "msg":"success"
}

18. 获取用户的群列表（不建议高频使用，以防止有性能问题）

18.0.1. 地址

http://domain:18080/admin/group/of_user

18.0.2. body

参数	类型	必需	描述
userId	string	是	用户ID，参数是驼峰式的，为了兼容旧的SDK保持现状吧

18.0.3. 响应

参数	类型	必需	描述
groupIds	list	是	群id列表

18.0.4. 示例

curl -X POST -H "nonce:76616" -H "timestamp":"1558350862502" -H "sign":"b98f9b0717f59febccf1440067a7f50d9b31bdde" -H "Content-Type:application/json" -d   \
  "{                       \
    \"userId\":\"userId1\"    \
    }"                                \
  http://localhost:18080/admin/group/of_user

{
  "code":0,
  "msg":"success",
  "result":{
    "groupIds":["groupId1", "groupId2", "groupId3"]
  }
}

19. 获取2个用户的共同群列表（不建议高频使用，以防止有性能问题）

19.0.1. 地址

http://domain:18080/admin/group/common_group

19.0.2. body

参数	类型	必需	描述
first	string	是	用户ID
second	string	是	用户ID

19.0.3. 响应

参数	类型	必需	描述
groupIds	list	是	群id列表

19.0.4. 示例

curl -X POST -H "nonce:76616" -H "timestamp":"1558350862502" -H "sign":"b98f9b0717f59febccf1440067a7f50d9b31bdde" -H "Content-Type:application/json" -d   \
  "{                       \
    \"first\":\"userId1\",    \
    \"second\":\"userId2\",    \
    }"                                \
  http://localhost:18080/admin/group/common_group

{
  "code":0,
  "msg":"success",
  "result":{
    "groupIds":["groupId1", "groupId2", "groupId3"]
  }
}

20. 按成员类型获取用户群组列表

根据成员类型获取用户的群组列表（不建议高频使用，以防止有性能问题）。

20.0.1. 地址

http://domain:18080/admin/group/of_user_by_type

20.0.2. body

参数	类型	必需	描述
userId	string	是	用户ID
groupMemberType	int[]	是	成员类型列表(0普通成员, 1管理员, 2群主)

20.0.3. 响应

参数	类型	必需	描述
groupIds	list	是	群id列表

20.0.4. 示例

curl -X POST -H "nonce:76616" -H "timestamp":"1558350862502" -H "sign":"b98f9b0717f59febccf1440067a7f50d9b31bdde" -H "Content-Type:application/json" -d   \
  "{                       \
    \"userId\":\"userId1\",    \
    \"groupMemberType\":[0, 2]    \
    }"                                \
  http://localhost:18080/admin/group/of_user_by_type

{
  "code":0,
  "msg":"success",
  "result":{
    "groupIds":["groupId1", "groupId2"]
  }
}

21. 禁言群成员

设置或取消群成员的禁言状态。

21.0.1. 地址

http://domain:18080/admin/group/manager/mute

21.0.2. body

参数	类型	必需	描述
operator	string	是	操作者用户ID
group_id	string	是	群组ID
members	list	是	群成员ID列表
is_manager	boolean	是	true 设置为禁言；false 取消禁言
to_lines	int[]	否	会话线路，默认为0
notify_message	json	否	消息负载，如果不填写，系统会发出内置通知消息，如果填写，覆盖系统通知消息

21.0.3. 响应

无

21.0.4. 示例

curl -X POST -H "nonce:76616" -H "timestamp":"1558350862502" -H "sign":"b98f9b0717f59febccf1440067a7f50d9b31bdde" -H "Content-Type:application/json" -d   \
  "{                       \
    \"operator\":\"admin\",       \
    \"group_id\":\"groupId1\",    \
    \"members\": [                  \
        \"memberId1\"  \
      ],                            \
    \"is_manager\": true                            \
    }"                                \
  http://localhost:18080/admin/group/manager/mute

{
  "code":0,
  "msg":"success"
}

22. 设置群备注

为用户设置群组的备注信息。

22.0.1. 地址

http://domain:18080/admin/user/put_setting

此接口复用用户设置接口，设置scope=6, key=groupId

22.0.2. body

参数	类型	必需	描述
userId	string	是	用户ID
scope	int	是	范围，设置为6
key	string	是	群组ID
value	string	是	备注内容

22.0.3. 响应

无

22.0.4. 示例

curl -X POST -H "nonce:76616" -H "timestamp":"1558350862502" -H "sign":"b98f9b0717f59febccf1440067a7f50d9b31bdde" -H "Content-Type:application/json" -d   \
  "{                       \
    \"userId\":\"user1\",       \
    \"scope\": 6,    \
    \"key\": \"groupId1\",   \
    \"value\": \"重要群组\"   \
    }"                                \
  http://localhost:18080/admin/user/put_setting

{
  "code":0,
  "msg":"success"
}

23. 获取群备注

获取用户对群组的备注信息。

23.0.1. 地址

http://domain:18080/admin/user/get_setting

此接口复用用户设置接口，获取scope=6, key=groupId

23.0.2. body

参数	类型	必需	描述
userId	string	是	用户ID
scope	int	是	范围，设置为6
key	string	是	群组ID

23.0.3. 响应

参数	类型	必需	描述
scope	int	是	范围
key	string	是	键
value	string	是	备注内容

23.0.4. 示例

curl -X POST -H "nonce:76616" -H "timestamp":"1558350862502" -H "sign":"b98f9b0717f59febccf1440067a7f50d9b31bdde" -H "Content-Type:application/json" -d   \
  "{                       \
    \"userId\":\"user1\",       \
    \"scope\": 6,    \
    \"key\": \"groupId1\"   \
    }"                                \
  http://localhost:18080/admin/user/get_setting

{
  "code":0,
  "msg":"success",
  "result":{
    "scope":6,
    "key":"groupId1",
    "value":"重要群组"
  }
}

24. 收藏群组

为用户设置群组的收藏状态。

24.0.1. 地址

http://domain:18080/admin/user/put_setting

此接口复用用户设置接口，设置scope=26, key=groupId, value为"1"表示收藏，"0"表示取消收藏

24.0.2. body

参数	类型	必需	描述
userId	string	是	用户ID
scope	int	是	范围，设置为26
key	string	是	群组ID
value	string	是	"1"收藏，"0"取消收藏

24.0.3. 响应

无

24.0.4. 示例

curl -X POST -H "nonce:76616" -H "timestamp":"1558350862502" -H "sign":"b98f9b0717f59febccf1440067a7f50d9b31bdde" -H "Content-Type:application/json" -d   \
  "{                       \
    \"userId\":\"user1\",       \
    \"scope\": 26,    \
    \"key\": \"groupId1\",   \
    \"value\": \"1\"   \
    }"                                \
  http://localhost:18080/admin/user/put_setting

{
  "code":0,
  "msg":"success"
}

25. 是否收藏群组

获取用户是否收藏了指定群组。

25.0.1. 地址

http://domain:18080/admin/user/get_setting

此接口复用用户设置接口，获取scope=26, key=groupId

25.0.2. body

参数	类型	必需	描述
userId	string	是	用户ID
scope	int	是	范围，设置为26
key	string	是	群组ID

25.0.3. 响应

参数	类型	必需	描述
scope	int	是	范围
key	string	是	键
value	string	是	"1"已收藏，"0"未收藏

25.0.4. 示例

curl -X POST -H "nonce:76616" -H "timestamp":"1558350862502" -H "sign":"b98f9b0717f59febccf1440067a7f50d9b31bdde" -H "Content-Type:application/json" -d   \
  "{                       \
    \"userId\":\"user1\",       \
    \"scope\": 26,    \
    \"key\": \"groupId1\"   \
    }"                                \
  http://localhost:18080/admin/user/get_setting

{
  "code":0,
  "msg":"success",
  "result":{
    "scope":26,
    "key":"groupId1",
    "value":"1"
  }
}