跳至主要內容

group

yh-third-dev2025/8/4大约 10 分钟

未特别说明情况下请求域名均为 https://chat-go.jwzhd.com
没写请求/响应项目表示不需要相关参数.

获取群聊信息

POST /v1/group/info

注意

此处响应数据部分项目需要在打开相应开关后才会出现,例如 private 必须打开群聊私有才能在响应数据中看到.

请求头

名称必须备注
token是无

请求体

message GroupInfoRequest {
  string group_id = 2; // 群聊 ID
}

响应数据

message GroupInfoResponse {
  Status status = 1;
  GroupData data = 2;
  repeated BotData bot = 3;

  // 群聊数据
  message GroupData {
    string group_id = 1;
    string name = 2;
    string avatar_url = 3;
    uint64 avatar_id = 4; // 头像 ID
    string introduction = 5;
    uint64 member = 6; // 群人数
    string create_by = 7; // 创建者
    bool direct_join = 8; // 进群免审核
    int32 permisson_level = 9; // 权限等级
    bool history_msg = 10; // 历史消息
    string category_name = 11; // 分类名
    uint64 category_id = 12; // 分类 ID
    bool private = 13; // 是否为私有群聊
    bool do_not_disturb = 14; // 免打扰
    uint64 community_id = 15; // 加入的社区 ID
    string community_name = 16; // 加入的社区名
    bool top = 19; // 会话置顶
    repeated string admin = 20; // 管理员列表
    uint64 create_time = 21; // 群聊创建时间
    string limited_msg_type = 22; // 被限制的消息类型,例如 1,2,3
    string owner = 23; // 群主
    bool recommandation = 24; // 是否加入群推荐
    repeated string tag_old = 26; // 标签(旧版)
    repeated Tag tag = 27;
    string my_group_nickname = 28; // 我的群昵称
    string group_code = 29; // 群口令
    bool hide_group_members = 30; // 隐藏群成员（开启时为 1）
    bool auto_delete_message = 32; // 消息自动销毁时间
    bool deny_members_upload_to_group_disk = 33; // 禁止群成员上传文件到群云盘（开启时为 1）
  }

  // 群聊中使用过的机器人数据
  message BotData {
    string id = 1;
    string name = 2;
    uint64 name_id = 3; // 机器人名称在数据库中序列,包括用户,群聊,机器人
    string avatar_url = 4;
    uint64 avatar_id = 5;
    string introduction = 6;
    string create_by = 7; // 创建者
    uint64 create_time = 8;
    uint64 headcount = 9; // 使用人数
    bool private = 10; // 是否为私有机器人
  }
}

获取群成员列表

POST /v1/group/list-member

请求头

名称必须备注
token是无

请求体

message ListMemberRequest {
  Data data = 2;

  message Data {
    int32 size = 1; // 分页大小
    int32 page = 2; // 页数
  }

  string group_id = 3; // 群聊 ID
  string keywords = 4; // 搜索关键词
}

响应数据

message ListMemberResponse {
  Status status = 1;
  repeated User user = 2;
  message User {
    string group_id = 1;
    UserInfo user_info = 2;

    message UserInfo {
      string user_id = 1;
      string name = 2;
      string avatar_url = 4;
      bool is_vip = 6;
    }
    int32 permission_level = 3; // 权限等级, 群主 100 管理员 2 普通用户无/0
    int64 gag_time = 4; // 禁言时间戳
    bool is_gag = 5; // 是否被禁言
  }
  int32 total = 3; // 总数
}

获取群聊语音房间

POST /v1/group/live-room

请求头

名称必须备注
token是无

请求体

{
  "groupId": "123" // 群聊 id
}

响应数据

{
  "code": 1,
  "data": {
    "rooms": [
      {
        "userId": "123", // 房间管理员用户 ID
        "roomId": "123", // 房间 ID
        "chatId": "123", // 房间所属对象 ID
        "title": "测试房间", // 房间名称
        "chatType": 2, // 房间所属对象类别，一般为2-群聊
        "status": 0, // 房间状态码
        "createBy": "123", // 房间创建用户 ID
        "createTime": 1231231230, //房间创建时间戳
        "nickname": "测试用户", // 房间创建用户名称
        "count": 123, // 房间内人数
        "avatarUrl": "https://..." // 房间头像 url
      }
    ]
  },
  "msg": "success"
}

获取群指令列表

POST /v1/group/instruction-list

请求头

名称必须备注
token是无

请求体

{
  "groupId": "big" // 目标群聊
}

响应数据

{
  "code": 1,
  "data": {
    "instructions": [
      {
        "botId": "123", // 机器人 ID
        "botName": "测试机器人", // 机器人名称
        "name": "测试指令", // 指令名称
        "desc": "测试指令简介", // 指令简介
        "id": 123, // 指令 ID
        "sort": 0, // 未知
        "auth": 0 // 可用状态: 0-所有人可用，1-所有人禁用，2-群主可用，3-群主管理员可用
      },
      // ...
    ]
  },
  "msg": "success"
}

邀请加入群聊

POST /v1/group/invite

请求头

名称必须备注
token是无

请求体

{
  "chatId": "123", // 邀请成员 ID，必须添加目标对象为好友
  "chatType": 1, // 邀请成员类别，1-用户，3-机器人
  "groupId": "123" // 目标群聊
}

响应数据

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

踢出用户

POST /v1/group/remove-member

请求头

名称必须备注
token是必须为群主或管理员token

请求体

{
  "groupId": "123", // 目标群聊 ID
  "userId": "123" // 踢出用户 ID
}

响应体

正常
{
  "code": 1,
  "msg": "success"
}

禁言用户

POST /v1/group/gag-member

请求头

名称必须备注
token是必须为群主或管理员token

请求体

{
  "groupId": "123", // 目标群聊 ID
  "userId": "123", // 禁言用户 ID
  "gag": 0 // 禁言时间，只能为这些时间: 0-取消禁言，600-10分钟，3600-1小时，21600-6小时，43200-12小时，(-1)-永久禁言
}

响应体

正常
{
  "code": 1,
  "msg": "success"
}

获取群聊推荐分类

GET /v1/group/category

响应体

{
  "code": 1,
  "data": {
    "category": [
      {
        "id": 27,
        "name": "云湖",
        "parent_id": 0,
        "subItems": [
          {
            "id": 26,
            "name": "云湖反馈",
            "parent_id": 27,
            "subItems": null
          }
        ]
      },
      {
        "id": 6,
        "name": "技术",
        "parent_id": 0,
        "subItems": [
          {
            "id": 22,
            "name": "IT/互联网",
            "parent_id": 6,
            "subItems": null
          },
          {
            "id": 23,
            "name": "玩机",
            "parent_id": 6,
            "subItems": null
          },
          {
            "id": 24,
            "name": "其他技术",
            "parent_id": 6,
            "subItems": null
          }
        ]
      },
      {
        "id": 3,
        "name": "游戏",
        "parent_id": 0,
        "subItems": [
          {
            "id": 11,
            "name": "手游",
            "parent_id": 3,
            "subItems": null
          },
          {
            "id": 12,
            "name": "单机游戏",
            "parent_id": 3,
            "subItems": null
          },
          {
            "id": 13,
            "name": "主机游戏",
            "parent_id": 3,
            "subItems": null
          },
          {
            "id": 14,
            "name": "网络游戏",
            "parent_id": 3,
            "subItems": null
          },
          {
            "id": 15,
            "name": "其他游戏",
            "parent_id": 3,
            "subItems": null
          }
        ]
      },
      {
        "id": 5,
        "name": "兴趣爱好",
        "parent_id": 0,
        "subItems": [
          {
            "id": 16,
            "name": "影视",
            "parent_id": 5,
            "subItems": null
          },
          {
            "id": 17,
            "name": "摄影",
            "parent_id": 5,
            "subItems": null
          },
          {
            "id": 18,
            "name": "音乐",
            "parent_id": 5,
            "subItems": null
          },
          {
            "id": 19,
            "name": "动漫",
            "parent_id": 5,
            "subItems": null
          },
          {
            "id": 20,
            "name": "运动",
            "parent_id": 5,
            "subItems": null
          },
          {
            "id": 21,
            "name": "其他",
            "parent_id": 5,
            "subItems": null
          },
          {
            "id": 25,
            "name": "资讯订阅",
            "parent_id": 5,
            "subItems": null
          }
        ]
      },
      {
        "id": 2,
        "name": "其他",
        "parent_id": 0,
        "subItems": [
          {
            "id": 29,
            "name": "粉丝群",
            "parent_id": 2,
            "subItems": null
          },
          {
            "id": 28,
            "name": "地区",
            "parent_id": 2,
            "subItems": null
          },
          {
            "id": 8,
            "name": "同事",
            "parent_id": 2,
            "subItems": null
          },
          {
            "id": 9,
            "name": "朋友",
            "parent_id": 2,
            "subItems": null
          },
          {
            "id": 10,
            "name": "家人",
            "parent_id": 2,
            "subItems": null
          }
        ]
      }
    ]
  },
  "msg": "success"
}

搜索推荐群聊

POST /v1/group/recommend/list

请求体

{
  "categoryId": 22, // 群聊分类 id， 0 代表全部
  "keyword": "114514" // 搜索关键词，留空获取全部群聊
}

响应体

{
  "code": 1,
  "data": {
    "groups": [
      {
        "id": 9910,
        "groupId": "114514",
        "name": "这是群聊名字",
        "introduction": "这是个群聊介绍",
        "createBy": "114514", // 创建者 id
        "createTime": 1754113069, // 创建时间戳
        "avatarId": 43821, // 头像id
        "del_flag": 0,
        "avatarUrl": "https://chat-img.jwznb.com/3d805b635cc54829e461102ab315381b.gif", // 群头像 url
        "headcount": 16, // 群聊人数
        "readHistory": 1, // 是否开启新成员查看消息历史记录（1为开启，0为关闭）
        "alwaysAgree": 1, // 是否直接进群（1为开启，0为关闭）
        "categoryId": 22, // 群聊分类 id
        "category": "技术-IT/互联网", // 群聊分类名称
        "private": 0, // 群聊是否私有（1为开启，0为关闭）
        "banId": 0, //
        "gag": 0,  // 是否禁言（1为开启，0为关闭）
        "gagBy": "", // 被禁言的 id
        "msgTypeLimit": "" // 消息类型限制
      },
    // ...
    ]
  },
  "msg": "success"
}

设置消息类型限制

POST /v1/group/msg-type-limit

请求头

名称必须备注
token是必须是群主/管理员token

请求体

{
  "groupId": "群聊id",
  "type": "消息类型" // 1-文本消息，2-图片消息，3-Markdown消息，4-文件消息，6-帖子消息，7-表情消息，8-HTML消息，10-视频消息，11-语音消息，13-语音通话（限制多个消息类型一般是 1,2,3,4··· 之类）
}

响应体

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

编辑群聊信息

POST /v1/group/edit-group

提示

此编辑会覆盖原有设置,不是合并!

请求头

名称必须备注
token是群聊管理员token

请求体

message EditGroupRequest {
  string group_id = 2; // 目标群聊 ID
  string name = 3; // 群聊名称
  string introduction = 4; // 群聊简介
  string avatar_url = 5; // 群聊头像 url
  bool direct_join = 6; // 进群免审核,1 为开启
  bool history_msg = 7; // 历史消息,1 为开启
  string category_name = 8; // 分类名
  uint64 category_id = 9; // 分类 ID
  bool private = 10; // 是否私有,1 为私有
  bool hide_group_members = 11; // 隐藏群成员
}

响应体

message StatusResponse {
  Status status = 1;
}

获取群机器人列表

POST /v1/group/bot-list

请求头

名称必须备注
token是群内成员

请求体

group_id: "123" // 目标群聊 ID
ProtoBuf 数据结构
message edit_group_send {
  string group_id = 2; // 目标群聊 ID
}

响应体

status {
  request_id: 114514
  code: 1
  msg: "success"
}
// ...
ProtoBuf 数据结构
// 获取群机器人列表
message bot_list_send {
    string group_id = 2;
}

message bot_list {
    Status status = 1;
    repeated Bot_data bot = 2;

    repeated Instruction_data instruction = 3;

    message Instruction_data {
        int64 id = 1;
        string bot_id = 2;
        string name = 3; // 指令名
        string desc = 4; // 指令描述
        int32 type = 5; // 指令类型（1-普通指令, 2-直发指令, 5-自定义输入指令）
        string hint_text = 6; // 输入框提示文字
        string default_text = 7; // 输入框默认文字
        // int32 hidden/del_flag = 8; // 是否隐藏/删除,猜的,有误欢迎指正
        int64 sort = 9; // 和排序相关 不确定
        string form = 10; // 表单
        string bot_name = 11; // 机器人名称
    }
    repeated Menu_data menu = 4; // 快捷菜单相关

    message Menu_data {
        int64 id = 1;
        string bot_id = 2;
        // int32 hidden/del_flag = 3; // 是否隐藏/删除,猜的
        string name = 4;
        string content = 5; // 内容
        int32 menu_type = 6; // 按钮类型: 1-普通按钮 2-选中按钮 3-下拉选择
        int64 create_time = 7;
        // 8,9没找到
        int32 menu_action = 10; // 操作类型
        string select = 99; // 选择的选项,在选择按钮的时候也作为状态,选中为 1,未选中为 0
    }
}

移除群聊内机器人

POST /v1/group/remove-bot

请求头

名称必须备注
token是群内成员

请求体

{
  "groupId": "123", // 群聊 id
  "botId": "123" // 机器人 id
}

响应体

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

设置我的群昵称

POST /v1/group/edit-my-group-nickname

请求头

名称必须备注
token是群内成员

请求体

{
  "groupId": "123", // 目标群聊 ID
  "nickname": "测试群昵称" // 欲设置的群昵称
}

响应体

{
  "msg": "success"
}

设置群口令

POST /v1/group/edit-group-keyword
功能简介

在 /v1/group/info-add-friend 中
搜索群口令就会显示群口令绑定的相应群聊
也就是在聊天主页列表最顶上的搜索栏搜索指定群口令时会显示设置为该群口令的群聊

请求头

名称必须备注
token是必须为vip用户且是目标群群主

请求体

{
  "groupId": "123", // 目前群聊 ID
  "keyword": "测试群口令" // 欲设置的群口令
}

响应体

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

获取指定群口令关联群聊

POST /v1/group/info-add-friend

请求头

名称必须备注
token是无

请求体

keyword: "测试群口令" // 欲要搜索的群口令
ProtoBuf 数据结构
message info_add_friend_send {
  string keyword = 2; // 欲要搜索的群口令
}

响应体

status {
  request_id: 114514
  code: 1
  msg: "success"
}

Data {
  id: "123" // 群聊 ID
  name: "测试群名称" // 群聊名称
  avatar_url: "https://..." // 群聊头像 url
  avatar_id: 123; // 群聊头像 ID
  introduction: "测试群聊简介" // 群聊简介
  headcount: 123 // 群人数
  createBy: "123" // 群聊创建者 ID
  readHistory: 1 // 是否允许阅读历史信息: 0-不允许，1-允许
  limited_msg_type: "1" // 被限制的消息类型,如1,2,3,使用","分格
  keyword: "测试群口令" // 群聊设置的群口令
}
ProtoBuf 数据结构
message info_add_friend {
    Status status = 1;
    Data data = 1;

    message Data {
      string id = 1; // 群聊 ID
      string name = 2; // 群聊名称
      string avatar_url = 3; // 群聊头像 url
      uint64 avatar_id = 4; // 群聊头像 ID
      string introduction = 5; // 群聊简介
      uint64 headcount = 6; // 群人数
      string createBy = 7; // 群聊创建者 ID
      uint64 readHistory = 10; // 是否允许阅读历史信息: 0-不允许，1-允许
      string limited_msg_type = 22; // 被限制的消息类型,如1,2,3,使用","分格
      string keyword = 29; // 群聊设置的群口令
  }
}

设置群聊消息自动销毁时间

POST /v1/group/edit-auto-delete-message

请求头

名称必须备注
token是必须是群主token

请求体

{
  "groupId": "123", // 群聊 id
  "autoDeleteMessage": 0 // 消息自动销毁时间（0-永久不删，90-2个月后删除，365-1年后删除，730-2年后删除）
}

响应体

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

设置禁止群成员上传到群云盘

POST /v1/group/edit-stop-member-upload-group-file

请求头

名称必须备注
token是必须是群主token

请求体

{
 "groupId": "123456789", // 群聊 id
 "stopMemberUploadGroupFile":1 // 是否开启（0-关闭，1-开启）
}

响应体

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

创建群聊

POST /v1/group/create-group

请求头

名称必须备注
token是无

请求体

name: "测试群聊" // 群聊名称
introduction: "测试群聊" // 群聊简介
avatar_url: "https://..." // 头像 url
ProtoBuf 数据结构
message create_send {
    string name = 2;
    string introduction = 3;
    string avatar_url = 4;
}

响应数据

status {
  request_id: 114514
  code: 1
  msg: "success"
}
group_id: "123" // 新群聊 ID
ProtoBuf 数据结构
message dismiss_group {
    Status status = 1;
    string group_id = 2;
}

解散群聊

POST /v1/group/dismiss-group

请求头

名称必须备注
token是群主

请求体

group_id: "123123" // 群聊 ID
ProtoBuf 数据结构
message dismiss_send {
    string group_id = 2;
}

响应数据

status {
  request_id: 114514
  code: 1
  msg: "success"
}
ProtoBuf 数据结构
message dismiss_group {
    Status status = 1;
}

获取语音房间列表

POST /v1/group/live-room

请求头:

名称必须备注
token是无

请求体：

{
  "groupId": "big" // 群聊 id
}

响应体：

{
  "code": 1,
  "data": {
    "rooms": [
      {
        "userId": "1234567", // 用户 id
        "roomId": "c7552ca7c79546dd93baca4e4adxxxxx", // 房间 id
        "chatId": "123456789", // 房间所发起的会话 id
        "title": "", // 房间标题
        "chatType": 2, // 房间所发起的会话类型
        "status": 0, // 房间状态
        "createBy": "1234567", // 发起房间的用户 id
        "createTime": 1775881889, // 房间创建时间戳
        "nickname": "111", // 房间创建者名称
        "count": 1, // 房间人数
        "avatarUrl": "https://chat-img.jwznb.com/defalut-avatars/Nellie%20Bly.png" // 房间创建者头像 Url
      }
    ]
  },
  "msg": "success"
}

同意进群申请、同意机器人进群

POST /v1/group/agree-invite

请求头：

名称必须备注
token是无

请求体：

{
  "id": 123, // 申请 ID
  "agree": 1 // 1-通过请求，2-拒绝请求，3-显示请求过期，4-显示已解散
}

响应体：

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

用户被是否被该群踢过

POST /v1/group/member-is-removed

请求头：

名称必须备注
token是无

请求体：

{
  "userId": "123", // 用户 ID
  "groupId": "123" // 群聊 ID
}

响应体：

{
  "code": 1, // 1-踢过，2-没踢过
  "msg": "success" // 返回消息
}

加入群推荐

POST /v1/group/switch

请求头：

名称必须备注
token是无

请求体：

{
  "groupId": "123", // 群聊 ID
  "hide": 0 // 0-关闭隐藏（加入群推荐），1-隐藏（不加入群推荐）
}

响应体：

{
  "code": 1,
  "msg": "success"
}
在 GitHub 上编辑此页
最近更新:
贡献者: QianLin-Jiaxi,yyyytawa,shanfishapp,Kauid323,B84F2246,轻雨Purainty,ccd2s,MarisaDAZA
云湖非官方 API 文档
Copyright © 2026 yh-third-dev