群开放开发者接口文档
文档背景介绍
本文档为QQ群开放平台接口说明文档(beta版),旨在说明群开放平台当前提供的核心能力:群关系链读取、成员资料读取、群资料读取、应用发送消息、应用分享等。

群开放平台与第三方交互说明:
1)授权逻辑
应用上线后,用户可添加群应用到自己的应用列表中。用户点击应用后,如果未授权,群应用平台会提示用户进行授权;如果用户已授权,则直接跳转到应用的入口地址, 并带上如下参数:
//thirdparty.com/index.cgi?access_token=6d356e402420b0ec36df9918xxxxxxxx&expires_in=7776000&openid=55E8960584D19C24BB6C7DDExxxxxxx&openkey=6d356e402420b0ec36df9918xxxxxxxx&group_openid=22BDE4FE838B4A1BE01F3Bxxxxxx&appid=101234000&_wv=1027
2) 参数说明
获取到以上参数是第三方访问群的开放接口的基础, 这些数据允许第三方保存。
其中appid, openkey, openid, group_openid是调用所有群的开放接口都必传的参数,
(其他必传参数可参考//wiki.open.qq.com/wiki/API3.0%E6%96%87%E6%A1%A3#.E5.85.AC.E5.85.B1.E5.8F.82.E6.95.B0.E8.AF.B4.E6.98.8E)用于应用身份和用户身份的验证,切勿泄漏。此外,access_token与openkey相同,expires_in参数说明openkey在多久后失效,单位为秒。 每个接口还有各自独有的参数,遵循接口文档添加即可。
1. 群关系链读取
1.1 功能说明
获取群内已经授权给本应用的成员列表,以及成员的简单资料(昵称、性别、头像),成员以openid形式提供。
1.2 接口说明
1.2.1 接口调用url
https://graph.qq.com/v3/qqqun/get_group_members_auth
1.2.2 请求参数:
1) 共用参数
//wiki.open.qq.com/wiki/API3.0%E6%96%87%E6%A1%A3#.E5.85.AC.E5.85.B1.E5.8F.82.E6.95.B0.E8.AF.B4.E6.98.8E
2) 私有参数
参数名称 必须 类型 描述
group_openid string 指定群的key
3) 返回参数
参数名称 类型 描述
ret number 返回码
msg string 如果错误,返回错误信息
is_lost number 判断是否有数据丢失。如果应用不使用cache,不需要关心此参数。
0:或者不返回:没有数据丢失,可以缓存。
1:有部分数据丢失或错误,不要缓存。
openid string 成员QQ号码对应的openid
items array 群关系链数组
items.openid String 成员openid
items.nickname String 昵称
items.gender String 性别
items.figureurl_qq String 大小为40×40像素的QQ头像URL
items.role Number 群成员身份: 3-管理员 2-群主. 其他为空
1.3 调用实例
1.3.1 请求实例
// graph.qq.com/v3/qqqun/ get_group_members_auth?openid=F2BDF90dhksdjlkjs5AB9D902&openkey=5C8C87FC9C42C7588lsajlsajFDD97D4C0&pf=qqqun&appid=10121834&format=json&userip=10.0.0.1&group_openid=22BDE4sdsadadavbfg3BAB6ECA171A &sig=3E7xBczQvzsfvsdf5%2FadsdasIgRRg14%3D
1.3.2 返回数据实例:
{ "ret":0, "is_lost":0, "items":[ {"openid":"9CE729C9927532BABBB57F6AB000925B"…}, {"openid":"08B8273CACFBE0D9F57CAB4E7D8BDBF0"…} ] }
1.3.3 错误返回实例:
{ "ret":1002, "msg":"请先登录" }
2. 群内成员资料读取
2.1 功能说明
获取群内某个成员的详细资料,该成员必须是已授权给本应用,否则返回错误。
2.2 接口说明
2.2.1 调用url
https://graph.qq.com/v3/qqqun/get_group_userinfo_auth
2.2.2 参数说明
1) 共用参数
//wiki.open.qq.com/wiki/API3.0%E6%96%87%E6%A1%A3#.E5.85.AC.E5.85.B1.E5.8F.82.E6.95.B0.E8.AF.B4.E6.98.8E
2) 私有参数
参数名称 必须 类型 描述
group_openid String 指定群的key
user_openid String 指定群友的key
3) 返回参数
参数名称 类型 描述
ret Number 返回码
msg String 如果错误,返回错误信息
is_lost Number 判断是否有数据丢失。如果应用不使用cache,不需要关心此参数。
0:或者不返回:没有数据丢失,可以缓存。
1:有部分数据丢失或错误,不要缓存。
openid String 群友openid
nickname String 昵称
gender String 性别
figureurl_qq_1 String 大小为40×40像素的QQ头像URL
figureurl_qq_2 String 大小为100×100像素的QQ头像URL。需要注意,不是所有的用户都拥有QQ的100x100的头像,但40x40像素则是一定会有。
country String 国家
province String 省份
city String 城市
qq_level String QQ等级
vip Number 是否为会员(0:不是,1:是)
vip_level Number 会员等级
2.3 调用实例
2.3.1 请求实例
// graph.qq.com/v3/qqqun/ get_group_userinfo_auth?openid=F2BDF9088asdasdaAB9D902&openkey=5C8C87FC9C42C75asdasdD97D4C0&pf=qqqun&appid=101234834&format=json&userip=10.0.0.1&group_openid=22BDE4sdasd1BE01F3BAB6ECA171A& user_openid=F2BDF90887FFdssda53D25AB9D902 &sig=3E7xBczQUquAyINs5%2FNZIgRRg14%3D
2.3.2 返回数据实例:
{
  "ret":0,
  "is_lost":0,
  "msg":"",
  "nickname":"Peter",
  "figureurl_qq_1":"//q.qlogo.cn/qqapp/100312990/DE1931D5330620DBD07FB4A5422917B6/40",
  "figureurl_qq_2":"//q.qlogo.cn/qqapp/100312990/DE1931D5330620DBD07FB4A5422917B6/100",
  "gender":"男",
  "country":"中国",
  "province": "广东",
  "city":"深圳",
  "qq_level":10,
  "vip":1,
  "vip_level":7
}
2.3.3 错误返回实例:
{
  "ret":1002,
  "msg":"请先登录"
}
3. 群资料读取
3.1 功能说明
获取某个群的公开资料,该群必须至少有一个群成员已授权给本应用,否则返回错误。
3.2 接口说明
3.2.1 调用url
https://graph.qq.com/v3/qqqun/get_group_info_auth
3.2.2 参数说明
1) 共用参数
//wiki.open.qq.com/wiki/API3.0%E6%96%87%E6%A1%A3#.E5.85.AC.E5.85.B1.E5.8F.82.E6.95.B0.E8.AF.B4.E6.98.8E
2) 私有参数
参数名称 必须 类型 描述
group_openid String 分享指定群的key
3) 返回参数:
参数名称 类型 描述
ret number 返回码, 0为成功. 其他返回码含义参考msg.
msg string 如果错误,返回错误信息
finger_memo string 群简介
g_name string 群名称
group_class_ext string 群分类类别,一级分类二级分类用竖线分割: 如|行业交流|IT互联网|
group_face string 群头像URL
is_lost number 判断是否有数据丢失。如果应用不使用cache,不需要关心此参数。
0:或者不返回:没有数据丢失,可以缓存。
1:有部分数据丢失或错误,不要缓存。
member_num uint 群内成员数
member_max_num uint 群内最大成员数
owner_openid string 群主的openid
poi_name string 群的地理信息
4) 群拓展分类
一级分类 二级分类
置业安家 未知
装修
业主
游戏 未知
学习.考试 高考
未知
考研
GRE
中考
托福
CET
职业认证
MBA
公务员
雅思
GMAT
其他
同事.朋友 同学
亲友
同事
办公
兴趣爱好 星座
音乐
读书
动漫
其他
运动
影视
未知
摄影
生活休闲 旅游
同城
健康
美容
美食
其他
购物
母婴
同乡
未知
宠物
人物 未知
其他 联通UP新势力
其他
腾讯服务
未知
品牌.产品 未知
家校师生 未知
行业交流 公务员
IT/互联网
咨询
投资
建筑工程
其他
律师
未知
营销与广告
服务
教师
传媒
银行
3.3 调用实例
3.3.1 请求实例
https://graph.qq.com/v3/qqqun/get_group_info_auth?_=1442487179448&appid=101234888&format=json&group_openid=9211DA8666E442C752CD5EF4xxxxx&openid=DF137C58407A63C9F487891230xxxxx&openkey=9ac6bc9c35e52a2389e8f08dxxxxxxx&pf=qqqun&user_openid=DF137C58407A63C9F4878xxxxxxxx&userip=0.0.0.0&sig=y5jhmVUpPiYSlH%2BrDxxxxxtQgNc%3D
3.3.2 返回数据实例:
{
  "finger_memo":"知你多项目您实习项目弄剋心知你多项目您实习项目弄剋心知你多项目您实习项目弄剋心知",
  "g_name":"溜溜球爱好群",
  "group_class_ext":"|行业交流|IT\/互联网|",
  "group_face":"http:\/\/113.108.77.71\/gh_open\/hrfFGsTwDLeG6OXRkquQH4FeTsK146vh\/100",
  "is_lost":0,
  "member_num":7,
  "msg":"",
  "owner_openid":"DF137C58407A63C9F487891230xxxxx",
  "poi_name":"深圳市海雅缤纷城",
  "ret":0
}
3.3.3 错误返回实例:
{
  "ret":1002,
  "msg":"请先登录"
}
4. 应用发送OBJ系统消息接口 (慎用)
4.1 功能说明
通过该接口,以应用消息的身份往群里发送消息,如日历往群里推送的自动提醒消息
注:为避免应用过多往群内消息推送造成打扰,该接口有频率限制,应用每天在每个群内仅可发送一条消息(测试环境无此限制)。更多条数的消息建议使用分享组件,引导用户发送。

4.2 接口说明
4.2.1 调用url
https://graph.qq.com/v3/qqqun/send_sys_objmsg_auth
4.2.2 测试环境
//119.147.19.43/v3/qqqun/send_sys_objmsg_auth
4.2.3 参数说明
1) 共用参数
//wiki.open.qq.com/wiki/API3.0%E6%96%87%E6%A1%A3#.E5.85.AC.E5.85.B1.E5.8F.82.E6.95.B0.E8.AF.B4.E6.98.8E
2) 私有参数
参数名称 必须 类型 描述
group_openid String 分享指定群的key
title String 消息标题,最长45字节
desc String 消息摘要,最长60字节
image_url String 消息左侧缩略图URL
redirect_url String 回调地址 (第三方应用在上架时配置的回调地址,不得填写其它域名地址)
param String redirect_url的输入参数,第三方可根据此参数来跳转到不同详情页
调用此接口后,会先鉴权,通过则会跳转redirect_url?param=xxx 的网址上。
(测试环境暂不鉴权也不校验回调地址 直接跳转到回调地址上)
3) 返回参数:
参数名称 类型 描述
ret number 返回码
msg string 如果错误,返回错误信息
4.3 调用实例
4.3.1 请求实例
// graph.qq.com /v3/qqqun/ send_sys_objmsg_auth?openid=3A785asdasd9D2C89DF82B1D15DB2C12D2&openkey=A0B87E4asdasA0BDE324E0FACA&appid=1101519816&sig=xx&pf=qqqun-A404455C2asdasd7C9FB0453181ACBD&format=json&group_openid=A404455asdasd53181ACBD&title=titlxxe&desc=dex22sc&redirect_url=http%3a%2f%2fwww.baidu.com&image_url=http%3a%2f%2fp.qlogo.cn%2fgh%2f31asdasd0%2f312248990%2f100¶m=bss%3d2323%26dcd%3d2323
4.3.2 返回数据实例:
{
  "ret":0,
  "msg":""
}
4.3.3 错误返回实例:
{
  "ret":1001,
  "msg":"srv busy"
}
5. 分享组件
5.1 功能说明
分享组件,供前端调用,使前端具备分享的能力。由应用调用,引导用户分享消息到群内,分享内容可由应用来填写。

5.2 接口说明
在需要使用的页面上嵌入js
<script src="//s.url.cn/qqweb/m/qunopen/component/sdk/opengroup.js"></script>
然后在需要的地方如下调用即可
<script>
window.openGroup.share({
  appid: 101234179, // 选填,若不填则使用url参数appid(必须有)
  // 当前用户的openid
  openid: 'C4004C007B298B3B03A8AB76E485F50E', // 选填,若不填则使用url参数openid(必须有)
  // 要分享的群的openid
  group_openid: 'F431CD4D369A1B50B77B10ACD0E1FBD2', // 选填,若不填则使用url参数group_openid(必须有)
  // 分享消息的title
  title: '新开局,群友大作战,专治各种不服,快加入我们一起玩吧',
  // 分享消息的更具体信息
  desc: '潜水、冒泡、能聊的都来玩!',
  // 分享出去打开的链接
  share_url: '//qqweb.qq.com/m/qunopen/demo/index.html',
   // 分享消息展示的图片
  image_url: '//qplus1.idqqimg.com/qqun/qun/css/imgs/open/01.jpg',
  debug: 1, // 可选,测试环境才需要,上线前请一定删掉
  // 分享成功的回调函数
  onSuccess: function() {
      console.log('success', arguments);
  },
  // 点取消的回调函数
   onCancel: function() {
      console.log('cancel', arguments);
  },
   // 出错的回调函数,包括分享失败
  onError: function() {
      console.log('error', arguments);
  }
});
</script>
5.3 注意事项
分享组件弹窗使用绝对定位方式固定在页面正中间,z-index为9999,为了避免出现分享弹窗被遮挡的情况,请勿将页面上其他可见元素的z-index设置成超过9999。
需保证页面url上有有效参数appid、openid、group_openid
6. 右上角分享功能
6.1 功能说明
为第三方页面增加默认分享入口,体现在页面右上角分享button。
平台标配功能,用于用户自主分享该应用至其他群,内容由平台指定,应用配置js后即可在页面右上角显示button。
弹框内容为:
a.图标(应用图标)
b.应用名称(填写在图标下方)
c.标题wording(”给大家推荐一个好应用”)
d.内容wording(“应用名称”+“:”+“应用简要描述”)
e.选项(“取消”和“发送”)


6.2 接口说明
在应用主页面嵌入以下js即可
<script src="//s.url.cn/qqweb/m/qunopen/component/sdk/opengroup.js?_bid=2173"></script>
6.3 注意事项
需保证页面url上有有效参数appid、openid
7. 发公告组件
7.1 功能说明
应用内可以直接通过调组件方法跳转到发公告页面,进行发公告

7.2 接口说明
在需要使用的页面上嵌入js
<script src="//s.url.cn/qqweb/m/qunopen/component/sdk/opengroup.js?_bid=2173"></script>
然后在需要的地方如下调用即可
<script>
window.openGroup.postAnnouncement({
  appid: 101234888, // 选填,若不填则使用url参数appid(必须有)
  // // 本群openid
  group_openid: 'F431CD4D369A1B50B77B10ACD0E1FBD2', // 选填,若不填则使用url参数group_openid(必须有)
  // 公告标题
  title: '这里是公告标题', // 可选,若传参,则字符串长度必须在4-40之间
  // 公告内容
  desc: '这里是公告内容这里是公告内容这里是公告内容' // 可选,若传参,则字符串长度必须在15-500之间
});
</script>
7.3 注意事项
需保证页面url上有有效参数appid、group_openid
只有群主和管理员才有权限发布公告,调用接口前请先判断用户身份
8. 设置提醒组件
8.1 功能说明
应用可以调用该组件设置日历提醒
8.2 组件说明
组件使用365日历提供的日历服务
在需要使用的页面上嵌入js
<script src="//s.url.cn/qqweb/m/qunopen/component/sdk/opengroup.js?_bid=2173"></script>
然后在需要的地方如下调用即可
<script>
window.openGroup.setReminder({
  appid: 101234888, // 选填,若不填则使用url参数appid(必须有)
  // 当前用户的openid
  openid: 'C4004C007B298B3B03A8AB76E485F50E', // 选填,若不填则使用url参数openid(必须有)
  // 本群openid
  group_openid: 'F431CD4D369A1B50B77B10ACD0E1FBD2', // 选填,若不填则使用url参数group_openid(必须有)
  // 提醒标题(内容)
  title: '这里是提醒标题', // 必填
  // 日历提供一个链接位,此参数是调用API https://graph.qq.com/v3/qqqun/prepare_param_sign返回的
  url: '//app.qun.qq.com/cgi-bin/open_group/check_app_auth?_wv=1027&src=8&encry=jAd2QHOXVAyXedjByGvmtx0AYLUQqlwqyixs9gd_Uy4jZ06t623_C-Rak59CHuiqa9Pi96DNRMlIcG4RHO2TgI_YpaBmwbWP9Se00000008@',
  // 是否是全天提醒
  all_day_event: false,
  // 提醒开始时间,时间戳
  start_time: 1446197640544,
  // 提醒结束时间,时间戳
  end_time: 1446284056337,
  // 开始时间前几分钟提醒
  before_minutes: 5,
  // 签名,此参数是调用API https://graph.qq.com/v3/qqqun/prepare_param_sign返回的
  sign: '3494CF5D49DB7266DECB86BD65100000',
  // 签名参数,此参数是调用API https://graph.qq.com/v3/qqqun/prepare_param_sign返回的
  sign_time: 1446197706,
  // 签名时间,此参数是调用API https://graph.qq.com/v3/qqqun/prepare_param_sign返回的
  key_list: 'all_day_event,before_minutes,end_time,sign_time,start_time,title,url'
});
</script>
拉取调用参数的签名的url:
https://graph.qq.com/v3/qqqun/prepare_param_sign
参数说明:
平台公共入参请参考
//wiki.open.qq.com/wiki/API3.0%E6%96%87%E6%A1%A3#.E5.85.AC.E5.85.B1.E5.8F.82.E6.95.B0.E8.AF.B4.E6.98.8E
非平台公共字段及返回字段说明:
字段名称 输入或输出 必填 数值类型 字段说明
group_openid in string 群openid
url in string(32) 需要跳转的url,如果没有为应用主页
ret out int 0 表示成功 非0一般为参数错误或系统问题
sign out string(16) 对参数的签名
sign_time out int 签名时间
key_list out string 签名的参数列表
8.3 注意事项
需保证页面url上有有效参数appid、openid、group_openid
配套API https://graph.qq.com/v3/qqqun/prepare_param_sign