API 参考
在线调试

创建群组

更新时间: 2024/07/17 17:08:08

功能描述

该接口用于创建群组,包括高级群和超大群。

创建群组时,可通过设置群成员列表邀请用户入群。创建群组成功后,云信服务器会返回 team_id(群唯一标识),该字段需要保存,以便于加人与踢人等后续操作。

  • 超大群功能需要单独开通后才能使用,具体请参见 开通和配置群组功能
  • 如果创建时邀请的成员中存在加群数量超过限制的情况(每人最多加入 5000 个群组),会返回加群失败成员的云信账号。
  • 每个用户可创建的群数量有限制(默认最多创建 100 个群组),若需要扩展创建群组的数量,请前往云信控制台进行配置。

调用频率

单个应用默认最高调用频率请参考 频控说明

请求

URL

POST https://open.yunxinapi.com/im/v2/teams

请求 Header 的参数说明请参见 请求 Header

请求体参数

参数名称 类型 是否必选 描述
owner_account_id String 必选 群主(创建者)云信账号 ID。
team_type Integer 必选 群组类型。1:高级群;2:超大群。
name String 必选 群组名称,长度上限 64 位字符。
icon String 可选 群组头像的 URL 地址,例如 "https://netease/xxx.png" ,长度上限 1024 位字符。
announcement String 可选 群组公告,长度上限 1024 位字符。
intro String 可选 群组简介,长度上限 512 位字符。
members_limit Integer 可选 群组成员数上限(包含群主),默认为 200。可设置范围的为:[2 ~ 200]。若需要扩展群容量,请前往云信控制台配置。配置好后,该参数颗设置的范围为:[2 ~ 控制台设置的群人数上限]。
server_extension String 可选 自定义群组扩展字段,第三方可以跟据此属性自定义扩展自己的群属性,建议封装成 JSONObject 格式,{key:value}。长度上限 1024 位字符
invite_account_ids Array of strings 必选 创建群组时邀请入群的成员列表。
  • 单个元素为成员的云信账号 ID。
  • 无需添加群主(owner_account_id),群主(创建者)默认入群。
  • 群成员(包括群主)总数不超过 members_limit
  • invite_msg String 必选 邀请入群的附言,长度上限 150 位字符。
    extension String 可选 自定义扩展字段,即自定义的通知字段,JSON 格式,不会持久化。长度上限 512 位字符。该字段仅针对高级群,对超大群无效。
    configuration Object 必选 群组配置项。
    antispam_configuration Object 可选 安全通相关配置项。

    请求体示例

    json{
        "owner_account_id":"123456",
        "team_type":1,
        "invite_msg":"哈哈哈",
        "name":"test",
        "invite_account_ids":["1234567"],
        "configuration":{
           "join_mode":0     
        },
    }
    

    响应

    Header

    响应 Header 的参数说明请参见 响应 Header

    响应体参数

    参数名称 类型 描述 是否必返回
    code Integer 状态码,200 表示请求成功。
    msg String 提示信息。请求失败时返回错误信息,请求成功时返回 "success"。
    data Object 返回的 JSON 数据对象,请求失败则返回空对象。

    响应体示例

    json{
        "code": 200,
        "msg": "success",
        "data": {
            "failed_list": ["a", "b", "c"],
            "team_info": {
                "team_id": "123456",
                "icon": null,
                "announcement": null,
                "server_extension": "",
                "extension": "",
                "intro": null,
                "name": "test",
                "configuration": {
                    "update_team_info_mode": 0,
                    "invite_mode": 1,
                    "join_mode": 0,
                    "agree_mode": 1,
                    "update_extension_mode": 0,
                    "chat_banned_mode": 0
                }
            }
        }
    }
    

    错误码

    错误码 错误码描述 错误信息示例
    200 请求成功 success
    414 参数错误 parameter error
    416 频率超限 rate limit exceeded
    102404 用户不存在 account not exist
    108304 未配置大容量超大群的数量 extended super team limit not configured
    108305 加入群组超过上限 joined team limit exceeded
    108311 超大群服务未开通 super team service disabled
    108434 大容量超大群数量超限 extended super team limit
    108435 创建群组超过上限 created team limit
    108437 群人数超过上限 team invitation limit
    108451 群组信息未过反垃圾审核 team hit antispam
    500 服务端内部错误 internal server error
    503 服务器繁忙 server busy
    此文档是否对你有帮助?
    有帮助
    去反馈
    • 功能描述
    • 调用频率
    • 请求
    • URL
    • Header
    • 请求体参数
    • 请求体示例
    • 响应
    • Header
    • 响应体参数
    • 响应体示例
    • 错误码