即时通信 IM 创建群组

接口调用说明
通过该接口创建一个包含客服号的群组，该客服号会直接转人工，若没有客服在线，则该接口会返回失败。
接口请求限制
调用该接口之前，请先联系我们开通客服群聊功能。
该接口仅限智能客服试用版和高级版调用。
目前仅支持创建包含一个客服号的群组，且创建时必须指定初始成员列表，至少包含一个非客服号的成员。
创建群组后，再邀请其他客服号入群时，这些新入群的客服号暂不支持转人工。
该接口仅支持创建 Private 和 Public 类型的群。
请求 URL 示例
https://console.tim.qq.com/v4/desk_http_svc/create_group?sdkappid=88888888&identifier=admin&usersig=xxx&random=99999999&contenttype=json
请求参数说明
下表仅列出调用本接口时涉及修改的参数及其说明，更多参数详情请参见 REST API 简介。
参数
说明
v4/desk_http_svc/create_group
请求接口。
sdkappid
创建应用时即时通信 IM 控制台分配的 SDKAppID。
identifier
必须为 App 管理员账号，更多详情请参见 App 管理员。
usersig
App 管理员账号生成的签名，具体操作请参见 生成 UserSig。
random
请输入随机的32位无符号整数，取值范围0 - 4294967295。
contenttype
请求格式固定值为json。
请求包示例
{
  "Owner_Account": "user3", // 群主的 UserId（选填）
  "Type": "Public", // 群组类型：Private/Public（必填）
  "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", // 申请加群处理方式（选填）
  "MemberList": [ // 初始群成员列表，最多100个（选填）
      {
          "Member_Account": "user2", // 成员（必填）
          "Role": "Admin" // 赋予该成员的身份，目前备选项只有 Admin（选填）
      },
      {
          "Member_Account": "@customer_service_account"
      }
  ]
}
请求包字段说明
字段
类型
属性
说明
Owner_Account
String
选填
群主 ID（需是 已导入 的账号）。填写后自动添加到群成员中；如果不填，群没有群主。
Type
String
必填
群组形态，包括 Public（陌生人社交群），Private（即 Work，好友工作群）。
GroupId
String
必填
为了使得群组 ID 更加简单，便于记忆传播，腾讯云支持 App 在通过 REST API 创建群组时 自定义群组 ID。
Name
String
必填
群名称，最长100字节，使用 UTF-8 编码，1个汉字占3个字节。
Introduction
String
选填
群简介，最长400字节，使用 UTF-8 编码，1个汉字占3个字节。
Notification
String
选填
群公告，最长400字节，使用 UTF-8 编码，1个汉字占3个字节。
FaceUrl
String
选填
群头像 URL，最长500字节。
MaxMemberCount
Integer
选填
最大群成员数量，缺省时的默认值：付费套餐包上限，例如体验版是20，如果升级套餐包，需按照修改群基础资料修改这个字段。
ApplyJoinOption
String
选填
申请加群处理方式。包含 FreeAccess（自由加入），NeedPermission（需要验证），DisableApply（禁止加群），如果不填，具体默认项可参见 加群方式差异。
仅当创建支持申请加群的 群组 时，该字段有效。
InviteJoinOption
String
选填
邀请加群处理方式，包含 FreeAccess （直接邀请用户进群，不需要审批等操作）， NeedPermission 需要群管理员或者群主审批， DisableInvite 不支持 SDK 邀请进群， 该选项 AVChatRoom 群类型不支持。
AppDefinedData
Array
选填
群组维度的自定义字段，默认情况是没有的，可以通过 即时通信 IM 控制台 进行配置，详情请参阅 自定义字段。
MemberList
Array
必填
初始群成员列表，最多100个；成员信息字段详情请参阅 群成员资料。
AppMemberDefinedData
Array
选填
群成员维度的自定义字段，默认情况是没有的，可以通过 即时通信 IM 控制台 进行配置，详情请参见 自定义字段。
应答包体示例
{
  "ActionStatus": "OK",
  "ErrorInfo": "",
  "ErrorCode": 0,
  "GroupId": "MyFirstGroup"
}
应答包字段说明
字段
类型
说明
ActionStatus
String
请求处理的结果：
OK 表示处理成功
FAIL 表示失败
ErrorCode
Integer
错误码：
0表示成功
非0表示失败
ErrorInfo
String
错误信息
GroupId
String
创建成功之后的群 ID
错误码说明
除非发生网络错误（例如502错误），否则该接口的 HTTP 返回码均为200。真正的错误码，错误信息是通过应答包体中的 ErrorCode、ErrorInfo 来表示的。
公共错误码（60000到79999）参见 错误码 文档。
本 API 私有错误码如下：
错误码
含义说明
10002
服务器内部错误，请重试
10003
请求命令字非法
10004
参数非法，请根据错误描述检查请求是否正确
10005
请求包中导入的成员数量超过100，请减少MemberList参数中导入的成员数量
10006
操作频率限制，请尝试降低调用的频率。常见于单日净增群量过多，获取 App 中所有群组操作过于频繁
10007
操作权限不足，请根据错误信息检查请求参数。例如，指定的群组类型不允许拉人入群，但在请求包中填写了MemberList
10008
请求非法，可能是请求中携带的签名信息验证不正确，请再次尝试或  提交工单  联系技术客服
10016
App 后台通过第三方回调拒绝本次操作，请检查您的回调服务“创建群组之前回调”的返回值
10021
群组 ID 已被其他人使用，请选择其他的群组 ID
10025
该群组 ID 已经由您自己使用过，请您先解散该群组或者选择其他的群组 ID
10036
创建的音视频聊天室数量超过限制，请先解散部分音视频聊天室或者参考 价格说明 购买升级
10037
请求中指定了群主（Owner_Account），但该群主创建和加入的群组数量超过了限制。请该群主退出部分群组或者参考 价格说明 购买升级
10038
请求包中导入的成员数量超过了限制，请减少MemberList参数中导入的成员数量或者参考 价格说明 购买升级
10058
表示体验版超过100个群的限制，需要购买套餐包提升建群数量限制。
141001
分配人工客服失败，无可用客服在线。
141002
系统内部错误，请重试。
141004
请求参数非法，请检查后重试。
接口调试工具
通过 REST API 在线调试工具 调试本接口。
参考
解散群组（v4/group_open_http_svc/destroy_group）
可能触发的回调
﻿创建群组之前回调﻿
﻿创建群组之后回调﻿

参数	说明
v4/desk_http_svc/create_group	请求接口。
sdkappid	创建应用时即时通信 IM 控制台分配的 SDKAppID。
identifier	必须为 App 管理员账号，更多详情请参见 App 管理员。
usersig	App 管理员账号生成的签名，具体操作请参见生成 UserSig。
random	请输入随机的32位无符号整数，取值范围0 - 4294967295。
contenttype	请求格式固定值为`json`。

字段	类型	属性	说明
Owner_Account	String	选填	群主 ID（需是已导入的账号）。填写后自动添加到群成员中；如果不填，群没有群主。
Type	String	必填	群组形态，包括 Public（陌生人社交群），Private（即 Work，好友工作群）。
GroupId	String	必填	为了使得群组 ID 更加简单，便于记忆传播，腾讯云支持 App 在通过 REST API 创建群组时自定义群组 ID。
Name	String	必填	群名称，最长100字节，使用 UTF-8 编码，1个汉字占3个字节。
Introduction	String	选填	群简介，最长400字节，使用 UTF-8 编码，1个汉字占3个字节。
Notification	String	选填	群公告，最长400字节，使用 UTF-8 编码，1个汉字占3个字节。
FaceUrl	String	选填	群头像 URL，最长500字节。
MaxMemberCount	Integer	选填	最大群成员数量，缺省时的默认值：付费套餐包上限，例如体验版是20，如果升级套餐包，需按照修改群基础资料修改这个字段。
ApplyJoinOption	String	选填	申请加群处理方式。包含 FreeAccess（自由加入），NeedPermission（需要验证），DisableApply（禁止加群），如果不填，具体默认项可参见加群方式差异。仅当创建支持申请加群的群组时，该字段有效。
InviteJoinOption	String	选填	邀请加群处理方式，包含 FreeAccess （直接邀请用户进群，不需要审批等操作）， NeedPermission 需要群管理员或者群主审批， DisableInvite 不支持 SDK 邀请进群，该选项 AVChatRoom 群类型不支持。
AppDefinedData	Array	选填	群组维度的自定义字段，默认情况是没有的，可以通过即时通信 IM 控制台进行配置，详情请参阅自定义字段。
MemberList	Array	必填	初始群成员列表，最多100个；成员信息字段详情请参阅群成员资料。
AppMemberDefinedData	Array	选填	群成员维度的自定义字段，默认情况是没有的，可以通过即时通信 IM 控制台进行配置，详情请参见自定义字段。

错误码	含义说明
10002	服务器内部错误，请重试
10003	请求命令字非法
10004	参数非法，请根据错误描述检查请求是否正确
10005	请求包中导入的成员数量超过100，请减少`MemberList`参数中导入的成员数量
10006	操作频率限制，请尝试降低调用的频率。常见于单日净增群量过多，获取 App 中所有群组操作过于频繁
10007	操作权限不足，请根据错误信息检查请求参数。例如，指定的群组类型不允许拉人入群，但在请求包中填写了`MemberList`
10008	请求非法，可能是请求中携带的签名信息验证不正确，请再次尝试或提交工单联系技术客服
10016	App 后台通过第三方回调拒绝本次操作，请检查您的回调服务“创建群组之前回调”的返回值
10021	群组 ID 已被其他人使用，请选择其他的群组 ID
10025	该群组 ID 已经由您自己使用过，请您先解散该群组或者选择其他的群组 ID
10036	创建的音视频聊天室数量超过限制，请先解散部分音视频聊天室或者参考价格说明购买升级
10037	请求中指定了群主（Owner_Account），但该群主创建和加入的群组数量超过了限制。请该群主退出部分群组或者参考价格说明购买升级
10038	请求包中导入的成员数量超过了限制，请减少`MemberList`参数中导入的成员数量或者参考价格说明购买升级
10058	表示体验版超过100个群的限制，需要购买套餐包提升建群数量限制。
141001	分配人工客服失败，无可用客服在线。
141002	系统内部错误，请重试。
141004	请求参数非法，请检查后重试。

创建群组

本页目录：

接口调用说明

接口请求限制

请求 URL 示例

请求参数说明

请求包示例

请求包字段说明

应答包体示例

应答包字段说明

错误码说明

接口调试工具

参考

可能触发的回调