创建群

接口说明：应用通过该接口可以创建群组。创建群的同时可以添加指定人员或者分支成员到群里面。 如果以人员身份建群，接口调用时需要携带user_token作为访问凭证。 不填user_token时会以应用智能机器人身份建群，需要开启应用智能机器人能力，参考智能机器人使用说明。请求方式：POST (HTTPS)，Content-Type: application/json请求地址：https://apigw-example.domain/v2/groups/create?app_token=APP_TOKEN&user_token=USER_TOKENquery参数说明：

请求数据示例：

{
    "name":"XXX群",
    "description":"群描述",
    "avatarId":"123456-xxxxxxxx",
    "orgId":123456,
    "ownerId":"123456-yyyyyyyy",
    "staffIdList":["123456-zzzzzzzz","123456-wwwwwww"],
    "departmentIdList":["123456-mmmmmmmm"]
}

请求参数字段说明：|参数|类型 |必须|说明 | |-------------|----------|----------|---------------------------------------------------------------------| | name | string | 是 | 群名称 | | description | string | 否 | 群描述 | | orgId | int | 是 | 创建群所在组织的组织ID，以人员身份建群时，填人员组织ID，以智能机器人身份建群时填应用组织ID | | ownerId | string | 否 | 群主openId（人员），会自动成为群成员。不指定群主时，如果user_token不为空，则以user_token对应的人员作为群主，如果user_token为空，则使用智能机器人作为群主| | avatarId | string | 否 | 群头像资源ID，通上传文件接口上传头像后获取，参考 上传文件 | | staffIdList | string array | 否 | 建群时加入群的人员openId列表，群成员不能少于3个，staffIdList和departmentIdList不能全为空 | | departmentIdList | string array | 否 | 把分支成员全部加入到群(含子分支），以智能机器人身份建群时不支持该字段 |

返回参数字段说明：|参数 |类型|描述 | |---------------|----------|------------| | groupId | string | 新创建的群Id | | totalMembers | int | 群成员数量 | | invalidStaff | string array | 无效人员ID列表 | | invalidDepartment |string array | 无效的分支ID列表 |

返回数据示例：

业务正常返回：

{
  "errCode":0 ,
  "errMsg":"ok",
   "data": {
      "groupId":"123456-KKKLLLMMM",
      "totalMembers":10,
      "invalidStaff":[],
      "invalidDepartment":[]
   }
}

业务异常返回：

{
    "errCode": 错误码 ,
    "errMsg": 对应的统一错误码描述
}

对应可能的错误码说明：

接口错误码

获取群详情

接口说明：根据群ID获取群详情信息。请求方式：GET (HTTPS)请求地址：https://apigw-example.domain/v2/groups/:group_id/info/fetch?app_token=APP_TOKEN&user_token=USER_TOKENquery参数说明：

param 参数说明：

返回参数字段说明：|参数|类型|描述 | |--------------------|----------|----------------------------| | name | string | 群名称 | | avatarId | string | 群头像的openId | | avatarUrl | string | 群头像下载地址 | | description | string | 群描述 | | owner | json obj | 群主信息。如果群主为机器人，该字段为空 | | owner.staffId | string | 群主ID | | owner.name | string | 群主名称 | | state | int | 群的状态：0代表正常状态，1代表群已解散 | | creator | json obj | 群创建者人员信息。如果创建者为机器人，只展示应用机器人名称，isBot=true | | creator.staffId | string | 群创建者人员ID。如果创建者为机器人，只展示应用机器人名称，isBot=true | | creator.name | string | 群创建者人员名称。如果创建者为机器人，只展示应用机器人名称，isBot=true | | creator.isBot | bool | 群创建者是否为机器人标志 | | manageMode | int | 群操作的管理类型：0代表每个人都有权限管理群，1代表只有群主有管理权限 | | locationShare | bool | 是否允许位置共享：false代表不允许，true代表允许 | | needsConfirm | bool | 加群是否需要确认：false代表不需要，true代表需要 | | isPublic | bool | 是否公开该群：false代表不公开，true代表公开 | | maxMembers | int | 最大可加入的群成员数量，包含群成员中的自然人，智能机器人，webhook机器人 | | totalMembers | int | 现有群成员数量，不包含群中机器人数量 | | maxHistoryMsgCount | int | 历史消息最大可查数量：负数代表不限制可查数量，0代表不能查看历史，正数代表可以查看的历史数量 | | remindAll | bool | 是否可以@群全员：false代表不可以，true代表可以 | | sendMsgStatus | bool | 是否开启群禁言：false代表未开启，true代表开启 |

返回数据示例：

业务正常返回：

{
    "errCode":0 ,
    "errMsg":"ok",
    "data": {
        "name":"Name",
        "avatarId":"123456-xxxxxxx"
        "avatarUrl":"https://www.example.com/xxxx"
        "description":"群描述",
        "owner": {
            "staffId":"123456-yyyyyy",
            "name":"xxx"
        },
        "state":0,
        "creator": {
            "staffId":"123456-zzzzzz",
            "name":"xxx"
        },
        "manageMode":0,
        "locationShare":false,
        "needsConfirm":false,
        "isPublic":false,
        "maxHistoryMsgCount":-1,
        "maxMembers":10,
        "totalMembers":3,
        "remindAll":true,
        "sendMsgStatus":true
   }
}

业务异常返回：

{
    "errCode": 错误码 ,
    "errMsg": 对应的统一错误码描述
}

对应可能的错误码说明： 接口错误码

更新群详情

接口说明：更新群的详情信息。更新内容涉及较多字段，各个字段是以键值对的形式提供，应用可根据自己的需求填写对应的键值对进行相关字段属性的更新。不需要更新的字段，不需要提供对应的键值对。请求方式：POST (HTTPS)，Content-Type: application/json请求地址：https://apigw-example.domain/v2/groups/:group_id/info/update?app_token=APP_TOKEN&user_token=USER_TOKENquery参数说明：

param 参数说明：

请求数据示例：

{
    "name":"群名称",
    "avatarId":"123456-xxxxxxxxx",
    "description":"这是群的简介",
    "ownerId":"123456-xxxxxx",
    "assistant":["123456-yyyyyyy","123456-zzzzzzzz"],
    "manageMode":0,
    "locationShare":false,
    "needsConfirm":false,
    "isPublic":false,
    "maxHistoryMsgCount":-1,
    "maxMembers":10,
    "remindAll":true,
    "sendMsgStatus":true
}

请求参数字段说明：|参数|类型|必须|说明 | |-------------------|-----|---------|----------------------------| | name | string | 否 | 群名称 | | avatarId | string | 否 | 群头像的openId | | description | string | 否 | 群描述 | | ownerId | string | 否 | 群主的人员openId，必须是群成员 | | assistant | string array | 否 | 助理群主的人员openId，必须是群成员 | | manageMode | int | 否 | 群操作的管理类型：0代表每个人都有权限管理群，1代表只有群主有管理权限，其他值无效 | | locationShare | bool | 否 | 是否允许位置共享：false代表不允许，true代表允许 | | needsConfirm | bool | 否 | 加群是否需要确认：false代表不需要，true代表需要 | | isPublic | bool | 否 | 是否公开该群：false代表不公开，true代表公开 | | maxHistoryMsgCount| int | 否 | 历史消息最大可查数量：负数代表不限制可查数量，0代表不能查看历史，正数代表可以查看的历史数量 | | maxMembers | int | 否 | 最大可加入的群成员数量，包含群成员中的自然人，智能机器人，webhook机器人 | | remindAll | bool | 否 | 是否可以@群全员：false代表不可以，true代表可以 | | sendMsgStatus | bool | 否 | 是否开启群禁言：false代表未开启，true代表开启 |

返回数据示例：

业务正常返回：

{
  "errCode":0 ,
  "errMsg":"ok",
}

业务异常返回：

{
    "errCode": 错误码 ,
    "errMsg": 对应的统一错误码描述
}

对应可能的错误码说明：

接口错误码

获取群成员

接口说明：根据群ID获取群成员信息。请求方式：GET (HTTPS)请求地址：https://apigw-example.domain/v2/groups/:group_id/members/fetch?app_token=APP_TOKEN&user_token=USER_TOKEN&page_offset=PAGE_OFFSET&page_size=PAGE_SIZEquery参数说明：

param 参数说明：

返回参数字段说明：|参数|类型|描述 | |--------------------|----------|----------------------------| | totalMembers | int | 群成员数量，不包含机器人 | | members | obj array| 成员列表 | | members.staffId | string | 群成员的人员openId | | members.name | string | 群成员的名称 | | members.avatarUrl | string | 群成员的头像下载链接地址 | | members.avatarId | string | 群成员头像的openId | | members.orgName | string | 群成员所在的组织名称 | | members.role | int | 群成员的角色类型：0-普通成员；1-助理群主；2-群主；| | members.status | int | 成员状态：0-未激活；1-正常；2-已冻结； 3-已删除；5-待删除； |

返回数据示例：

业务正常返回：

{
    "errCode":0 ,
    "errMsg":"ok",
    "data": {
        "totalMembers":10,
        "members": [
            {
                "staffId":"123456-xxxxxx",
                "name":"员工1",
                "avatarUrl":"http://路径",
                "avatarId":"123456-yyyyy",
                "orgNamme":"测试组织1",
                "role":2,
                "status":1
            },
            {
                "staffId":"123456-zzzzz",
                "name":"员工2",
                "avatarUrl":"http://路径",
                "avatarId":"123456-wwwwww",
                "orgNamme":"测试组织2",
                "role":1,
                "status":1
            }
        ]
   }
}

业务异常返回：

{
    "errCode": 错误码 ,
    "errMsg": 对应的统一错误码描述
}

对应可能的错误码说明： 接口错误码

更新群成员

接口说明：添加人员进群或删除群成员，使用智能机器人身份操作群时不允许拉部门成员进群请求方式：POST (HTTPS)，Content-Type: application/json请求地址：https://apigw-example.domain/v2/groups/:group_id/members/update?app_token=APP_TOKEN&user_token=USER_TOKENquery参数说明：

param 参数说明：

请求数据示例：

{
    "addUserList":["123456-xxxxxxx","123456-yyyyyyy"],
    "delUserList":["123456-zzzzzzz","123456-wwwwwww"],
    "addDepartmentIdList":["123456-mmmmmm"]
}

请求参数字段说明：|参数|类型|必须|说明 | |-------------------|-----|---------|----------------------------| |addUserList | string array | 否 | 需要添加入群的人员列表 | |delUserList | string array | 否 | 需要从群内移除的人员列表 | |addDepartmentIdList| string array | 否 | 将分支成员添加入群 |

返回参数字段说明：|参数|类型|说明 | |------------------|------|------------------------------| |totalMembers | int | 群成员总人数 | |invalidStaff | string array | 无效的人员ID列表 | |invalidDepartment | string array | 无效的分支ID列表 | |addedStaffCount | int | 新添加成功的群成员数量 | |deletedStaffCount | int | 新删除成功的群成员数量。当操作者（参见上面user_token字段描述）是群主时，可以删除任意群成员。当操作者是非群主时，只能删除由操作者加入群内的群成员。删除其他人员加入群的群成员时会提示无权限。 |

返回数据示例：

业务正常返回：

{
  "errCode":0 ,
  "errMsg":"ok",
  "data":{
      "totalMembers":10,
      "addedStaffCount":5 ,
      "deletedStaffCount":0,
      "invalidStaff":[],
      "invalidDepartment":[]
  }
}

业务异常返回：

{
    "errCode": 错误码 ,
    "errMsg": 对应的统一错误码描述
}

对应可能的错误码说明：

接口错误码

解散群

接口说明：解散群，需要以群主或助理群主的身份才可以解散。请求方式：POST (HTTPS)，Content-Type: application/json请求地址：https://apigw-example.domain/v2/groups/:group_id/delete?app_token=APP_ACCESS_TOKEN&user_token=USER_TOKENquery参数说明：

param 参数说明：

返回数据示例：

业务正常返回：

{
  "errCode":0 ,
  "errMsg":"ok"
}

业务异常返回：

{
    "errCode": 错误码 ,
    "errMsg": 对应的统一错误码描述
}

对应可能的错误码说明：

接口错误码