App 管理员可以根据群组 ID 获取群组的详细信息。
群组类型 ID | 是否支持此 REST API |
---|---|
Private | 支持,同新版本中的 Work(好友工作群) |
Public | 支持 |
ChatRoom | 支持,同新版本中的 Meeting(临时会议群) |
AVChatRoom | 支持 |
Community(社群) | 支持 |
即时通信 IM 内置上述群组类型,详情介绍请参见 群组系统。
https://xxxxxx/v4/group_open_http_svc/get_group_info?sdkappid=88888888&identifier=admin&usersig=xxx&random=99999999&contenttype=json
下表仅列出调用本接口时涉及修改的参数及其说明,更多参数详情请参考 REST API 简介。
参数 | 说明 |
---|---|
xxxxxx | SDKAppID 所在国家/地区对应的专属域名:console.tim.qq.com adminapisgp.im.qcloud.com adminapikr.im.qcloud.com adminapiger.im.qcloud.com adminapiind.im.qcloud.com adminapiusa.im.qcloud.com |
v4/group_open_http_svc/get_group_info | 请求接口 |
sdkappid | 创建应用时即时通信 IM 控制台分配的 SDKAppID |
identifier | 必须为 App 管理员帐号,更多详情请参见 App 管理员 |
usersig | App 管理员帐号生成的签名,具体操作请参见 生成 UserSig |
random | 请输入随机的32位无符号整数,取值范围0 - 4294967295 |
contenttype | 请求格式固定值为json |
200次/秒。
基础形式
用来获取群组的详细信息(所有群基础信息、群成员信息和自定义信息),请求中只包含群 ID 的列表,一次请求最多支持50个群组。
{
"GroupIdList": [ // 群组列表(必填)
"@TGS#1NVTZEAE4",
"@TGS#1CXTZEAET"
]
}
拉取指定的信息
可以指定拉取的基础信息字段,在 GroupBaseInfoFilter 中设置。
可以指定拉取的成员信息字段,在 MemberInfoFilter 中设置。
可以指定拉取的群组维度的自定字段,在 AppDefinedDataFilter_Group 中设置(该字段默认没有,需要额外开通,请求包字段表中有说明)。
可以指定拉取的群成员维度的自定字段,在 AppDefinedDataFilter_GroupMember(该字段默认没有,需要额外开通,请求包字段表中有说明)。
如果设置了过滤器,没有在过滤器中指明的字段将不被拉取。
{
"GroupIdList": [ // 群组列表,必填
"@TGS#1NVTZEAE4",
"@TGS#1CXTZEAET"
],
"ResponseFilter": { // 返回
"GroupBaseInfoFilter": [ // 如果基础信息字段,请在此数组中添加
"Type",
"Name",
"Introduction",
"Notification"
],
"MemberInfoFilter": [ // 如果需要成员信息,请添加此数组
"Account", // 成员ID
"Role"
],
"AppDefinedDataFilter_Group": [ // 群组维度的自定义字段过滤,该默认情况是没有的
"GroupTestData1",
"GroupTestData2"
],
"AppDefinedDataFilter_GroupMember": [ // 群成员维度自定义字段过滤,该默认情况是没有的
"MemberDefined2",
"MemberDefined1"
]
}
}
字段 | 类型 | 属性 | 说明 |
---|---|---|---|
GroupIdList | Array | 必填 | 需要拉取的群组列表 |
ResponseFilter | Object | 选填 | 包含三个过滤器:GroupBaseInfoFilter,MemberInfoFilter,AppDefinedDataFilter_Group,分别是基础信息字段过滤器,成员信息字段过滤器,群组维度的自定义字段过滤器 |
GroupBaseInfoFilter | Array | 选填 | 基础信息字段过滤器,指定需要获取的基础信息字段,基础信息字段详情请参阅 群基础资料 |
MemberInfoFilter | Array | 选填 | 成员信息字段过滤器,指定需要获取的成员信息字段,成员信息字段详情请参阅 群成员资料 |
AppDefinedDataFilter_Group | Array | 选填 | 该字段用来群组维度的自定义字段过滤器,指定需要获取的群组维度的自定义字段,详情请参阅 自定义字段 |
AppDefinedDataFilter_GroupMember | Array | 选填 | 该字段用来群成员维度的自定义字段过滤器,指定需要获取的群成员维度的自定义字段,详情请参阅 自定义字段 |
基础形式
{
"ActionStatus": "OK",
"ErrorInfo": "", // 这里的 ErrorInfo 无意义,需要判断每个群组的 ErrorInfo
"ErrorCode": 0, // 这里的 ErrorCode 无意义,需要判断每个群组的 ErrorCode
"GroupInfo": [ // 返回结果为群组信息数组,为简单起见这里仅列出一个群
{
"GroupId": "@TGS#2J4SZEAEL",
"ErrorCode": 0, // 针对该群组的返回结果
"ErrorInfo": "" , // 针对该群组的返回结果
"Type": "Public", // 群组类型
"Name": "MyFirstGroup", // 群组名称
"Appid":1400001001,//即时通信应用的 SDKAppID
"Introduction": "TestGroup", // 群组简介
"Notification": "TestGroup", // 群组通知
"FaceUrl": "http://this.is.face.url", // 群组头像
"Owner_Account": "leckie", // 群主 ID
"CreateTime": 1426976500, // 群组创建时间(UTC 时间)
"LastInfoTime": 1426976500, // 最后群资料变更时间(UTC 时间)
"LastMsgTime": 1426976600, // 群内最后一条消息的时间(UTC 时间)
"NextMsgSeq": 1234,
"MemberNum": 2, // 当前群成员数量
"MaxMemberNum": 50, // 最大群成员数量
"ApplyJoinOption": "FreeAccess", // 申请加群处理方式
"MuteAllMember": "On", // 群全员禁言状态
"AppDefinedData": [ // 群组维度的自定义字段
{
"Key": "GroupTestData1", // 自定义字段的key
"Value": "xxxx" // 自定义字段的值
},
{
"Key": "GroupTestData2",
"Value": "abc\u0000\u0001" // 自定义字段支持二进制数据
}
],
"MemberList": [ // 群成员列表
{
"Member_Account": "leckie", // 成员 ID
"Role": "Owner", // 群内角色
"JoinTime": 1425976500, // 入群时间(UTC 时间)
"MsgSeq": 1233,
"MsgFlag": "AcceptAndNotify", // 消息屏蔽选项
"LastSendMsgTime": 1425976500, // 最后发言时间(UTC 时间)
"MuteUntil": 1431069882, // 禁言截止时间(UTC 时间)
"AppMemberDefinedData": [ // 群成员自定义字段
{
"Key": "MemberDefined1",
"Value": "ModifyDefined1"
},
{
"Key": "MemberDefined2",
"Value": "ModifyDefined2"
}
]
},
{
"Member_Account": "peter",
"Role": "Member",
"JoinTime": 1425976500, // 入群时间
"MsgSeq": 1233,
"MsgFlag": "AcceptAndNotify",
"LastSendMsgTime": 1425976500, // 最后一次发消息的时间
"MuteUntil": 0, // 0表示未被禁言,否则为禁言的截止时间
"AppMemberDefinedData":[ // 群成员自定义字段
{
"Key": "MemberDefined1",
"Value": "ModifyDefined1"
},
{
"Key":"MemberDefined2",
"Value":"ModifyDefined2"
}
]
}
]
}
]
}
拉取指定的信息
{
"ActionStatus": "OK",
"ErrorInfo": "", // 这里的 ErrorInfo 无意义,需要判断每个群组的 ErrorInfo
"ErrorCode": 0, // 这里的 ErrorCode 无意义,需要判断每个群组的 ErrorCode
"GroupInfo": [ // 返回结果为群组信息数组,为简单起见这里仅列出一个群
{
"GroupId": "@TGS#2J4SZEAEL",
"ErrorCode": 0, // 针对该群组的返回结果
"ErrorInfo":"" , // 针对该群组的返回结果
"Type": "Public", // 群组类型
"Name": "MyFirstGroup", // 群组名称
"Introduction": "TestGroup", // 群组简介
"Notification": "TestGroup", // 群组通知
"AppDefinedData": [ // 群组维度的自定义字段
{
"Key": "GroupTestData1", // 自定义字段的 key
"Value": "xxxx" // 自定义字段的值
},
{
"Key": "GroupTestData2",
"Value": "abc\u0000\u0001" // 自定义字段支持二进制数据
}
],
"MemberList": [ // 群成员列表
{
"Member_Account": "leckie", // 成员 ID
"Role": "Owner", // 群内角色
"AppMemberDefinedData":[ // 群成员自定义字段
{
"Key":"MemberDefined1",
"Value":"ModifyDefined1"
},
{
"Key":"MemberDefined2",
"Value":"ModifyDefined2"
}
]
},
{
"Member_Account": "peter",
"Role": "Member",
"AppMemberDefinedData":[ // 群成员自定义字段
{
"Key":"MemberDefined1",
"Value":"ModifyDefined1"
},
{
"Key":"MemberDefined2",
"Value":"ModifyDefined2"
}
]
}
]
}
]
}
字段 | 类型 | 说明 |
---|---|---|
ActionStatus | String | 请求处理的结果,OK 表示处理成功,FAIL 表示失败 |
ErrorCode | Integer | 错误码,0表示成功,非0表示失败 |
ErrorInfo | String | 错误信息 |
GroupInfo | Array | 返回结果为群组信息数组,内容包括群基础资料字段、群成员资料字段、群组维度自定义字段和群成员维度自定义字段,字段详情请参阅 群组数据结构介绍 |
除非发生网络错误(例如502错误),否则该接口的 HTTP 返回码均为200。真正的错误码,错误信息是通过应答包体中的 ErrorCode、ErrorInfo 来表示的。
公共错误码(60000到79999)参见 错误码 文档。
本 API 私有错误码如下:
错误码 | 含义说明 |
---|---|
10002 | 系统错误,请再次尝试或联系技术客服 |
10003 | 请求命令非法,请再次尝试或联系技术客服 |
10004 | 参数非法。请根据应答包中的 ErrorInfo 字段,检查必填字段是否填充,或者字段的填充是否满足协议要求 |
10007 | 操作权限不足。请确认操作者是否是 App 管理员 |
10010 | 群组不存在,或者曾经存在过,但是目前已经被解散 |
10015 | 群组 ID 非法,请检查群组 ID 是否填写正确 |
10018 | 应答包长度超限。因为请求的内容过多,导致应答包超过了最大包长(1MB),请尝试减少单次请求的数据量 |
通过 REST API 在线调试工具 调试本接口。
本页内容是否解决了您的问题?