tencent cloud

功能说明

App 管理员可以通过该接口创建群组。

接口调用说明

适用的群组类型

即时通信 IM 内置上述群组类型，详情介绍请参见 群组系统。

注意：

• 如果指定群组类型为直播群（AVChatRoom）：
• 创建此类型群时不能拉人入群，如果创建时指定了拉入的群成员会返回10007错误；用户加入此类型群的唯一方式是主动申请加群；如果指定了群主，群主每次使用 AVChatroom（直播群）时都必须使用 SDK 接口执行进群操作。
• 如果指定群组类型为非直播群：
• 请求时如果没有指定群主也没有设置群成员列表，那么创建群数量没有限制。
• 请求时如果指定了群主或者设置了群成员列表，那么指定的群主或者群成员，会自动加入到该群中。
• App 中同时存在的所有群组类型群数量加和超过10万，需要支付一定费用。详情请参考 价格说明。
• 因为用户帐号可以同时加入的群组数量是有限制，用户已加入群数量达到上限时会造成加群/建群失败，详情请参考 价格说明。

请求 URL 示例

https://xxxxxx/v4/group_open_http_svc/create_group?sdkappid=88888888&identifier=admin&usersig=xxx&random=99999999&contenttype=json

请求参数说明

下表仅列出调用本接口时涉及修改的参数及其说明，更多参数详情请参考 REST API 简介。

最高调用频率

200次/秒。

请求包示例

• 基础形式
  创建群，Owner_Account 字段是选填的，如果需要指定群主，请确保 已经导入 群主 UserId 。不填则该群没有群主。

  {
    "Owner_Account": "leckie", // 群主的 UserId（选填）
    "Type": "Public", // 群组类型：Private/Public/ChatRoom/AVChatRoom/Community
    "Name": "TestGroup" // 群名称（必填）
  }
  

• 仅包含群基础信息
  创建群，并指定群简介、群公告等群基础信息。

  {
    "Owner_Account": "leckie", // 群主的 UserId（选填）
    "Type": "Public", // 群组类型：Private/Public/ChatRoom/AVChatRoom/Community
    "Name": "TestGroup", // 群名称（必填）
    "Introduction": "This is group Introduction", // 群简介（选填）
    "Notification": "This is group Notification", // 群公告（选填）
    "FaceUrl": "http://this.is.face.url", // 群头像 URL（选填）
    "MaxMemberCount": 500, // 最大群成员数量（选填）
    "ApplyJoinOption": "FreeAccess"  // 申请加群处理方式（选填）
  }
  

• 仅包含群成员信息
  创建群，并指定初始化群成员列表，群成员列表在请求包说明表中有描述。初始化成员时仅支持设置 Member_Account 和 Role 字段。

  {
    "Name": "TestGroup", // 群名称（必填）
    "Type": "Public", // 群组类型：Private/Public/ChatRoom/Community(不支持AVChatRoom)（必填）
    "MemberList": [ // 初始群成员列表，最多100个（选填）
         {
            "Member_Account": "bob", // 成员（必填）
            "Role": "Admin" // 赋予该成员的身份，目前备选项只有 Admin（选填）
         },
         {
            "Member_Account": "peter"
         }
     ]
  }
  

• 自定义群组 ID
  为了使得群组 ID 更加简单，腾讯云支持 App 在通过 REST API 创建群组时自定义群组 ID。

  {
    "Owner_Account": "leckie", // 群主的 UserId（选填）
    "Type": "Public", // 群组类型：Private/Public/ChatRoom/AVChatRoom/Community（必填）
    "GroupId": "MyFirstGroup", // 用户自定义群组 ID（选填）
    "Name": "TestGroup"   // 群名称（必填）
  }
  

• 仅包含群维度自定义信息
  创建群，并指定群维度的自定义字段。AppDefineData 默认是没有的，可以通过 即时通信 IM 控制台 进行配置，详见请求包字段说明表。

  {
    "Name": "TestGroup", // 群名称（必填）
    "Type": "Public", // 群组类型：Private/Public/ChatRoom/AVChatRoom/Community（必填）
    "AppDefinedData": [ // 群组维度的自定义字段（选填）
        {
            "Key": "GroupTestData1", // App 自定义的字段 Key
            "Value": "xxxxx" // 自定义字段的值
        },
        {
            "Key": " GroupTestData2",
            "Value": "abc\u0000\u0001" // 自定义字段支持二进制数据
        }
    ]
  }
  

• 仅包含群成员维度自定义信息
  创建群，并指定群成员维度的自定义字段。AppMemberDefinedData 默认是没有的，可以通过 即时通信 IM 控制台 进行配置后使用，详见 请求包字段说明表。

  {
    "Owner_Account": "leckie", // 群主的 UserId（选填）
    "Type": "Public", // 群组类型：Private/Public/ChatRoom/Community(不支持AVChatRoom)（必填）
    "Name": "TestGroup", // 群名称（必填）
    "MemberList": [
       {
          "Member_Account":"bob",
          "AppMemberDefinedData":[ // 群成员维度自定义字段（选填）
               {
                   "Key": "MemberDefined1", // 群成员维度自定义的 Key
                   "Value": "MemberData1" // 群成员维度自定义字段值
               },
               {
                   "Key": "MemberDefined2",
                   "Value": "MemberData2"
               }
           ]
       },
       {
          "Member_Account":"peter",
          "AppMemberDefinedData":[
               {
                   "Key": "MemberDefined1",
                   "Value": "MemberData1"
               },
               {
                   "Key": "MemberDefined2",
                   "Value": "MemberData2"
               }
           ]
       }
    ]
  }
  

• 仅包含支持话题参数形式
  创建群组，并指定其类型为社群且支持话题。

  {
    "Type": "Community",     //群组类型 (必填)
    "Name": "TestCommunityGroup", //群组名称 (必填)
    "SupportTopic": 1            //是否支持话题选项, 1代表支持,0代表不支持
  }
  

• ALL IN ONE

  {
    "Owner_Account": "leckie", // 群主的 UserId（选填）
    "Type": "Public", // 群组类型：Private/Public/ChatRoom/Community(不支持AVChatRoom)（必填）
    "GroupId":"MyFirstGroup", // 用户自定义群组 ID（选填）
    "Name": "TestGroup", // 群名称（必填）
    "Introduction": "This is group Introduction", // 群简介（选填）
    "Notification": "This is group Notification", // 群公告（选填）
    "FaceUrl": "http://this.is.face.url", // 群头像 URL（选填）
    "MaxMemberCount": 500, // 最大群成员数量（选填）
    "ApplyJoinOption": "FreeAccess", // 申请加群处理方式（选填）
    "AppDefinedData": [ // 群组维度的自定义字段（选填）
        {
            "Key": "GroupTestData1", // App 自定义的字段 Key
            "Value": "xxxxx" // 自定义字段的值
        },
        {
            "Key": "GroupTestData2",
            "Value": "abc\u0000\u0001" // 自定义字段支持二进制数据
        }
    ],
    "MemberList": [ // 初始群成员列表，最多100个（选填）
        {
            "Member_Account": "bob", // 成员（必填）
            "Role": "Admin", // 赋予该成员的身份，目前备选项只有 Admin（选填）
            "AppMemberDefinedData":[ // 群成员维度自定义字段（选填）
               {
                   "Key":"MemberDefined1", // 群成员维度自定义的 Key
                   "Value":"MemberData1" // 群成员维度自定义字段值
               },
               {
                   "Key":"MemberDefined2",
                   "Value":"MemberData2"
               }
           ]
        },
        {
            "Member_Account": "peter",
            "AppMemberDefinedData":[
               {
                   "Key":"MemberDefined1",
                   "Value":"MemberData1"
               },
               {
                   "Key":"MemberDefined2",
                   "Value":"MemberData2"
               }
           ]
        }
    ]
  }
  

请求包字段说明

应答包体示例

• 基础形式、仅包含群基础信息、仅包含群成员信息和仅包含自定义信息

  {
    "ActionStatus": "OK",
    "ErrorInfo": "",
    "ErrorCode": 0,
    "GroupId": "@TGS#2J4SZEAEL"
  }
  

• 仅包含支持话题参数形式

  {
    "ActionStatus": "OK",
    "ErrorInfo": "",
    "ErrorCode": 0,
    "GroupId": "@TGS#_@TGS#cRDH3HIM62CP",
    "HugeGroupFlag": 0,
    "Type": "Community"
  }
  

• 自定义群组 ID 和 ALL IN ONE

  {
    "ActionStatus": "OK",
    "ErrorInfo": "",
    "ErrorCode": 0,
    "GroupId": "MyFirstGroup"
  }
  

应答包字段说明

错误码说明

除非发生网络错误（例如502错误），否则该接口的 HTTP 返回码均为200。真正的错误码，错误信息是通过应答包体中的 ErrorCode、ErrorInfo 来表示的。
公共错误码（60000到79999）参见 错误码 文档。
本 API 私有错误码如下：

接口调试工具

通过 REST API 在线调试工具 调试本接口。

参考

解散群组（v4/group_open_http_svc/destroy_group）

可能触发的回调

• 创建群组之前回调
• 创建群组之后回调