QQ公众号API文档

目录

接口使用要求 2

获取接口调用凭据 2

获取Access_token 2

接收消息 4

接收普通消息 4

接收事件推送 5

发送消息 10

被动回复消息 10

群发接口 12

模版消息接口 17

根据OpenID单发多图文消息 23

素材管理 25

新增临时素材 25

获取临时素材 27

新增永久素材 28

获取永久素材 30

删除永久素材 33

获取永久素材总数 34

用户管理 35

用户分组管理 35

获取用户列表 41

获取用户基本信息 43

网页授权获取用户基本信息 44

自定义菜单管理 51

自定义菜单创建接口 51

自定义菜单查询接口 52

自定义菜单删除接口 54

帐号管理 55

生成带参数的二维码 55

长链接转短链接接口 57

全局错误码 58

修订记录 60

接口使用要求

获取接口调用凭据

获取Access_token

接口描述

access_token是公众号的全局唯一票据，公众号调用各接口时都需使用access_token。开发者需要进行妥善保存。access_token的存储至少要保留512个字符空间。access_token的有效期目前为2个小时，需定时刷新，重复获取将导致上次获取的access_token失效。

公众平台的API调用所需的access_token的使用及生成方式说明:

1、为了保密appsecrect，第三方需要一个access_token获取和刷新的中控服务器。而其他业务逻辑服务器所使用的 access_token均来自于该中控服务器，不应该各自去刷新，否则会造成access_token覆盖而影响业务；

2、目前access_token的有效期通过返回的expire_in来传达，目前是7200秒之内的值。中控服务器需要根据这个有效时间提前去刷新access_token。在刷新过程中，中控服务器对外输出的依然是老access_token，此时公众平台后台会保证在刷新短时间内，新老access_token都可用，这保证了第三方业务的平滑过渡；

3、access_token的有效时间可能会在未来有调整，所以中控服务器不仅需要内部定时主动刷新，还需要提供被动刷新access_token的接口，这样便于业务服务器在API调用获知access_token已超时的情况下，可以触发access_token的刷新流程。

如果第三方不使用中控服务器，而是选择各个业务逻辑点各自去刷新access_token，那么就可能会产生冲突，导致服务不稳定。

公众号可以使用AppID和AppSecret调用本接口来获取access_token。AppID和AppSecret可在QQ生活服务公众平台-开发者中心页中获得（需要已经成为开发者，且帐号没有异常状态）。注意调用所有公众号接口时均需使用https协议。

请求方式

GET（请使用https协议）

请求地址

https://api.mp.qq.com/cgi-bin/token?appid=APPID&secret=APPSECRET

参数列表

调用举例

curl “https://api.mp.qq.com/cgi-bin/token?appid=APPID&secret=APPSECRET”

回执说明

　在调用接口后，会返回JSON格式数据包。

回执参数列表

正常回执示例

{"access_token":"e31cdc92f40907447c49ea903ab8dc45","expire":8624}

错误回执示例

{"errcode":40003, "errmsg":"invalid appid"}

接收消息

接收普通消息

接口描述

当普通手Q用户向生活服务号号发消息时，生活服务号服务器将POST消息的XML数据包到开发者填写的URL上。各消息类型的推送XML数据包结构如下：

注意：生活服务号服务器在五秒内收不到响应会断掉连接，并且重新发起请求，总共重试三次

关于重试的消息排重，推荐使用msgid排重。

假如用户服务器无法保证在五秒内处理并回复，可以直接回复空串或success，生活服务号服务器不会对此作任何处理，并且不会发起重试。

接口使用说明

1.接收文本消息

推送XML数据包示例：

1348831860

1234567890123456

参数说明：

2.接收地理位置消息

推送XML数据包示例：

1351776360

23.134521

113.358803

20

1234567890123456

参数说明：

接收事件推送

接口描述

当普通手Q用户向公众账号发消息时，生活服务号服务器将POST消息的XML数据包到开发者填写的URL上。各消息类型的推送XML数据包结构如下：

注意：生活服务号服务器在五秒内收不到响应会断掉连接，并且重新发起请求，总共重试三次，关于重试的消息排重，推荐使用msgid排重，假如用户服务器无法保证在五秒内处理并回复，可以直接回复空串或”success”字串，生活服务号服务器不会对此作任何处理，并且不会发起重试。

接口使用说明

1.关注/取消关注事件

用户在关注与取消关注公众号时，生活服务号把这个事件推送到开发者填写的URL。方便开发者给用户下发欢迎消息或者做帐号的解绑。

推送XML数据包示例：

123456789

参数说明：

2.扫描带参数二维码事件

用户扫描带场景值二维码时，可能推送以下两种事件：

a).如果用户还未关注公众号，则用户可以关注公众号，关注后生活服务号会将带场景值关注事件推送给开发者。

b).如果用户已经关注公众号，则生活服务号会将带场景值扫描事件推送给开发者。

a).用户未关注时，进行关注后的事件推送

推送XML数据包示例：

123456789

参数说明：

b).用户已关注时的事件推送

推送XML数据包示例：

123456789

参数说明：

3.上报地理位置事件

用户同意上报地理位置后，每次进入公众号会话时，都会在进入时上报地理位置，或在进入会话后每5秒上报一次地理位置，公众号可以在公众平台网站中修改以上设置。上报地理位置时，生活服务号会将上报地理位置事件推送到开发者填写的URL。

推送XML数据包示例：

123456789

23.137466

113.352425

119.385040

参数说明：

4.自定义菜单事件

用户点击自定义菜单后，生活服务号会把点击事件推送给开发者，请注意，点击菜单弹出子菜单，不会产生上报。

a).点击菜单拉取消息时的事件推送

推送XML数据包示例：

123456789

参数说明：

5.点击事件按钮类型推送

在场景消息尾部支持增加按钮（最少0个，最多3个）。点击按钮可实现点击（CLICK事件），并将此事件（含openid msgid等信息）上报至调用方（开发者），开发者可通过回包给点击用户下发消息。

推送XML数据包示例：

123456789

参数说明：

发送消息

被动回复消息

接口描述

对于每一个POST请求，开发者在响应包中返回特定XML结构，对该消息进行响应（现支持回复文本、图文）。

生活服务号服务器在五秒内收不到响应会断掉连接，并且重新发起请求，总共重试三次，如果在调试中，发现用户无法收到响应的消息，可以检查是否消息处理超时。

关于重试的消息排重，有msgid的消息推荐使用msgid排重。事件类型消息推荐使用FromUserName + CreateTime 排重。

发送被动响应消息其实并不是一种接口，而是对生活服务号服务器发过来消息的一次回复，假如服务器无法保证在五秒内处理并回复，必须做下述回复，生活服务号服务器不会对此作任何处理，并且不会发起重试（这种情况下，可以使用客服消息接口进行异步回复）：

1、直接回复空串（指字节长度为0的空字符串，而不是XML结构体中content字段的内容为空）

2、直接回复success

请开发者注意，一旦遇到以下情况，生活服务号都会在公众号会话中，向用户下发系统提示“该公众号暂时无法提供服务，请稍后再试”：

1、开发者在5秒内未回复任何内容

2、开发者回复了异常数据，比如JSON数据等

接口使用说明

1.回复文本消息

12345678

2.回复图文消息

12345678

2

3.回复图片消息

12345678

群发接口

目录

1 根据OpenID列表群发

2 删除群发

3 查询群发消息发送状态

4 群发结果推送

1根据OpenID列表群发

接口描述

用户调用该接口，完成群发消息的能力。消息内容可以是文本消息和图文素材消息

请求方式

POST（请使用https协议）

请求地址

https://api.mp.qq.com/cgi-bin/message/mass/send?access_token=ACCESS_TOKEN

参数列表

调用举例

文本消息

{

"touser" : [ "OPENID1" , "OPENID2" ],

"msgtype": "text",

"text":

{

"content": "hello from boxer."

}

}

图片消息

{

"touser" : [ "OPENID1" , "OPENID2" ],

"msgtype":"image",

"image":

{

"media_id":"123dsdajkasd231jhksad"

}

}

图文消息

{

"touser" : [ "OPENID1" , "OPENID2" ],

"msgtype":"mpnews",

"mpnews":

{

"media_id":"123dsdajkasd231jhksad"

}

}

回执说明

在调用模板消息接口后，会返回JSON格式数据包。

回执参数列表

正常回执示例

{

"errcode":0,

"errmsg":" send job submission success ",

"msgid":34182

}

2删除群发

接口描述

用户调用该接口，删除图文素材消息的群发详情内容。使用户无法正常打开图文消息。

请求方式

POST（请使用https协议）

请求地址

https://api.mp.qq.com/cgi-bin/message/mass/delete?access_token=ACCESS_TOKEN

参数列表

调用举例

{

"msg_id": 30124

}

回执说明

在调用模板消息接口后，会返回JSON格式数据包。

回执参数列表

正常回执示例

{"errcode":0,"errmsg":"ok",}

3查询群发消息发送状态

接口描述

获取群发发送之后的状态。

请求方式

POST（请使用https协议）

请求地址

https://api.mp.qq.com/cgi-bin/message/mass/get?access_token=ACCESS_TOKEN

参数列表

调用举例

{"msg_id": 30124}

回执说明

在调用模板消息接口后，会返回JSON格式数据包。

回执参数列表

群发消息状态列表

正常回执示例

{"msg_id":201053012,"msg_status":"SEND_SUCCESS"}

错误回执示例

{"errcode": 70008, "errmsg":"模板ID和互动号不匹配"}

4群发结果推送

由于群发任务提交后，群发任务可能在一定时间后才完成，因此，群发接口调用时，仅会给出群发任务是否提交成功的提示，若群发任务提交成功，则在群发任务结束时，会向开发者在公众平台填写的开发者URL（callback URL）推送事件。

推送XML数据包示例：

1394524295

1988

100

80

75

5

参数说明：

模版消息接口

目录

1 发送模版消息

2 消息送达事件推送

3 阅读回执事件推送

4 修订记录

发送模版消息

接口描述

模版消息（场景消息）仅用于公众号向用户发送重要的服务通知，只能用于符合其要求的服务场景中，如信用卡刷卡通知，商品购买成功通知等。不支持广告等营销类消息以及其它所有可能对用户造成骚扰的消息。

关于接口文档，请注意：

模板消息调用时主要需要模板ID和模板中各参数的赋值内容。

请求方式

POST（请使用https协议）

请求地址

根据OpenID 发送消息:

https://api.mp.qq.com/cgi-bin/message/template/send?access_token=ACCESS_TOKEN

参数列表

调用举例

根据OpenID发送纯文本消息

https://api.mp.qq.com/cgi-bin/message/template/send?access_token=ACCESS_TOKEN

{

"tousername": " xxxxxxxxxxxxxxx ",

"templateid": " xxxxxxxxxx ",

"msgtype": "txt",

"data": {

"first": {

"value": "377222777"

},

"keynote1": {

"value": "4005963215384"

},

"keynote2": {

"value": "3333333"

},

"keynote4": {

"value": "4444444"

}

}

}

根据OpenID发送点击跳转网页消息（一个按钮跳转的类型）

https://api.mp.qq.com/cgi-bin/message/template/send?access_token=ACCESS_TOKEN

{

"tousername": "xxxxxxxxxxxxxxx",

"templateid": "xxxxxxxxxx",

"msgtype": "txt",

"type": "view",

"url": "http://www.qq.com",

"name": "确认签收",

"data": {

"first": {

"value": "377222777"

},

"keynote1": {

"value": "4005963215384"

},

"keynote2": {

"value": "3333333"

},

"keynote4": {

"value": "4444444"

}

}

}

根据OpenID发送带两个按钮的模板消息（两个按钮类型）

https://api.mp.qq.com/cgi-bin/message/template/send?access_token=ACCESS_TOKEN

{

"tousername": " xxxxxxxxxxxxxxx ",

"templateid": " xxxxxxxxxx ",

"msgtype": "txt",

"data": {

"first": {

"value": "377222777"

},

"keynote1": {

"value": "4005963215384"

},

"keynote2": {

"value": "33333"

},

"keynote4": {

"value": "222222"

}

},

"button": {

"button1": {

"type": "view",

"name": "签收",

"url": "http://www.qq.com"

},

"button2": {

"type": "click",

"name": "了解详情",

"key": "231312"

}

}

}

回执说明

　在调用接口后，会返回JSON格式数据包。

回执参数列表

正常回执示例

{

"errcode":0,

"errmsg":"成功",

"msgid":1429241873512222

}

错误回执示例

{

"errcode": 70008,

"errmsg":"模板ID和互动号不匹配"

}

消息送达事件推送

在模版消息发送任务完成后，QQ服务器会将是否送达成功作为通知，发送到开发者中心中填写的服务器配置地址中。

1、送达成功

推送的XML如下：

1395658920

200163836

参数说明

2、送达由于用户拒收（用户设置拒绝接收公众号消息）而失败

推送的XML如下：

参数情况详见1，只是Status字段变成了

1395658984

200163840

参数说明

3、送达由于其他原因失败

推送的XML如下：

参数情况详见1，只是Status字段变成了

1395658984

200163840

参数说明

阅读回执事件推送

在模版消息发送任务完成后，QQ服务器会将消息是否阅读作为通知，发送到开发者中心中填写的服务器配置地址中。

1、消息阅读

推送的XML如下：

1395658920

200163836

参数说明

根据OpenID单发多图文消息

接口描述

用户调用该接口，根据OpenID单发多图文消息

请求方式

POST（请使用https协议）

请求地址

https://api.mp.qq.com/cgi-bin/message/custom/send?access_token=ACCESS_TOKEN

调用举例

{

"tousername":"OPENID",

"msgtype":"mpnews",

"mpnews":{

"articles": [{

"title": "图文消息1",

"thumb_media_id": THUMB_MEDIA_ID,

"author": AUTHOR,

"digest": DIGEST,

"show_cover_pic": SHOW_COVER_PIC(0 / 1),

"content": CONTENT,

"content_source_url": CONTENT_SOURCE_URL

},

{

"title": "图文消息2",

"thumb_media_id": THUMB_MEDIA_ID,

"author": AUTHOR,

"digest": DIGEST,

"show_cover_pic": SHOW_COVER_PIC(0 / 1),

"content": CONTENT,

"content_source_url": CONTENT_SOURCE_URL

}]

}

}

回执说明

在调用接口后，会返回JSON格式数据包。

回执参数列表

正常回执示例

{"errcode":0,"errmsg":"send job submission success","msg_id":34182}

错误回执示例

{"errcode":45008,"errmsg":"图文消息超过限制"}

边界条件说明

1. 如果发送额度不够，请返回错误码：

errcode：145011，errmsg：群发额度不够

2. 如果articles超过5个，请返回错误码：

errcode：45008，errmsg：图文消息超过限制

3. 频率预期：每秒500次调用。

4. 需要校验好友关系。如果非好友关系，返回错误码：

errcode：43005，errmsg：需要好友关系

素材管理

新增临时素材

接口描述

公众号经常有需要用到一些临时性的多媒体素材的场景，例如在使用接口特别是发送消息时，对多媒体文件、多媒体消息的获取和调用等操作，是通过media_id来进行的。素材管理接口对所有认证的订阅号和服务号开放。通过本接口，公众号可以新增临时素材（即上传临时多媒体文件）。

请注意：

1、对于临时素材，每个素材（media_id）会在开发者上传或粉丝发送到公众号服务器3天后自动删除（所以用户发送给开发者的素材，若开发者需要，应尽快下载到本地），以节省服务器资源。

2、media_id是可复用的。

3、素材的格式大小等要求与公众平台官网一致。具体是，图片大小不超过2M，支持bmp/png/jpeg/jpg/gif格式，语音大小不超过5M，长度不超过60秒，支持mp3/wma/wav/amr格式

4、需使用http调用本接口。

请求方式

POST/FORM（请使用https协议）

请求地址

https://api.mp.qq.com/cgi-bin/media/upload?access_token=ACCESS_TOKEN&type=TYPE

参数列表

调用举例

（使用curl命令，用FORM表单方式上传一个多媒体文件）

curl -F media=@test.mp3 "https://api.mp.qq.com/cgi-bin/media/upload?access_token=ACCESS_TOKEN&type=TYPE"

回执说明

在调用接口后，会返回JSON格式数据包。

回执参数列表

正常回执示例

{"errcode ":0,"type":"TYPE","media_id":"MEDIA_ID","created_at":123456789}

错误回执示例

{"errcode": 40004, "errmsg":"不合法的媒体文件类型"}

获取临时素材

接口描述

公众号可以使用本接口获取临时素材（即下载临时的多媒体文件）。请注意，视频文件不支持https下载，调用该接口需http协议。

请求方式

GET（请使用https协议）

请求地址

https://api.mp.qq.com/cgi-bin/media/get?access_token=ACCESS_TOKEN&media_id=MEDIA_ID

参数列表[编辑]

调用举例

（示例为通过curl命令获取多媒体文件）

curl -I -G "https://api.mp.qq.com/cgi-bin/media/get?access_token=ACCESS_TOKEN&media_id=MEDIA_ID"

回执说明

正确情况下的返回HTTP头如下：

HTTP/1.1 200 OK

Connection: close

Content-Type: image/jpeg

Content-disposition: attachment; filename="MEDIA_ID.jpg"

Date: Sun, 06 Jan 2013 10:20:18 GMT

Cache-Control: no-cache, must-revalidate

Content-Length: 339721

curl -G "https://api.mp.qq.com/cgi-bin/media/get?access_token=ACCESS_TOKEN&media_id=MEDIA_ID"

错误情况下的返回JSON数据包示例如下（示例为无效媒体ID错误）：

{"errcode":40007,"errmsg":"invalid media_id"}

新增永久素材

接口调用请求说明

通过POST表单来调用接口，表单id为media，包含需要上传的素材内容，有filename、filelength、content-type等信息。请注意：图片素材将进入公众平台官网素材管理模块中的默认分组。

请注意：

1、新增的永久素材也可以在公众平台官网素材管理模块中看到

2、永久素材的数量是有上限的，请谨慎新增。图片素材的上限为5000，其他类型为1000

3、素材的格式大小等要求与公众平台官网一致。具体是，图片大小不超过2M，支持bmp/png/jpeg/jpg/gif格式；语音大小不超过5M，长度不超过60秒，支持mp3/wma/wav/amr格式；视频大小不超过10M，格式仅支持MP4

4、调用该接口需https协议

请求方式

POST（请使用https协议）

请求地址

https://api.mp.qq.com/cgi-bin/material/add_material?access_token=ACCESS_TOKEN

参数列表

调用举例

（使用curl命令，用FORM表单方式新增一个其他类型的永久素材，curl命令的使用请自行查阅资料）

新增永久视频素材需特别注意

在上传视频素材时需要POST另一个表单，id为description，包含素材的描述信息，内容格式为JSON，格式如下：

{

"title":VIDEO_TITLE,

"introduction":INTRODUCTION

}

参数说明

新增永久视频素材的调用示例：

curl "https://api.mp.qq.com/cgi-bin/material/add_material?access_token=ACCESS_TOKEN" -F media=@media.file -F description='{"title":VIDEO_TITLE, "introduction":INTRODUCTION}'

回执说明

在调用接口后，会返回JSON格式数据包。

回执参数列表

正常回执示例

{"media_id":MEDIA_ID, "url":URL}

错误回执示例

{"errcode":40007,"errmsg":"invalid media_id"}

获取永久素材

接口描述

在新增了永久素材后，开发者可以根据media_id来获取永久素材，需要时也可保存到本地。

请注意：

1、获取永久素材也可以获取公众号在公众平台官网素材管理模块中新建的图文消息、语音、视频等素材（但需要先通过获取素材列表来获知素材的media_id）

2、临时素材无法通过本接口获取

3、调用该接口需https协议

请求方式

POST（请使用https协议）

请求地址

https://api.mp.qq.com/cgi-bin/material/get_material?access_token=ACCESS_TOKEN

参数列表

调用举例

curl "https://api.mp.qq.com/cgi-bin/material/get_material?access_token=ACCESS_TOKEN" -d '{"media_id":"61224425"}'

回执说明

如果请求的素材为图文消息，则响应如下：

{

"news_item":

[

{

"title":TITLE,

"thumb_media_id"::THUMB_MEDIA_ID,

"show_cover_pic":SHOW_COVER_PIC(0/1),

"author":AUTHOR,

"digest":DIGEST,

"content":CONTENT,

"url":URL,

"content_source_url":CONTENT_SOURCE_URL

},

//多图文消息有多篇文章

]

}

如果返回的是视频消息素材，则内容如下：

{

"title":TITLE,

"description":DESCRIPTION,

"down_url":DOWN_URL,

}

其他类型的素材消息，则响应的直接为素材的内容，开发者可以自行保存为文件。例如：

示例

curl "https://api.mp.qq.com/cgi-bin/material/get_material?access_token=ACCESS_TOKEN" -d '{"media_id":"61224425"}' > file

返回参数说明

错误情况下的返回JSON数据包示例如下（示例为无效媒体ID错误）：

{"errcode":40007,"errmsg":"invalid media_id"}

删除永久素材

接口描述

在新增了永久素材后，开发者可以根据本接口来删除不再需要的永久素材，节省空间。

请注意：

1、请谨慎操作本接口，因为它可以删除公众号在公众平台官网素材管理模块中新建的图文消息、语音、视频等素材（但需要先通过获取素材列表来获知素材的media_id）

2、临时素材无法通过本接口删除

3、调用该接口需https协议

请求方式

POST（请使用https协议）

请求地址

https://api.mp.qq.com/cgi-bin/material/del_material?access_token=ACCESS_TOKEN

调用示例

{

"media_id":MEDIA_ID

}

参数列表

返回说明

{

"errcode":ERRCODE,

"errmsg":ERRMSG

}

正常情况下调用成功时，errcode将为0。

获取永久素材总数

接口描述

开发者可以根据本接口来获取永久素材的列表，需要时也可保存到本地。

请注意：

1.永久素材的总数，也会计算公众平台官网素材管理中的素材

2.图片和图文消息素材（包括单图文和多图文）的总数上限为5000，其他素材的总数上限为1000

3.调用该接口需https协议

请求方式

GET（请使用https协议）

请求地址

https://api.mp.qq.com/cgi-bin/material/get_materialcount?access_token=ACCESS_TOKEN

回执说明

{

"voice_count":COUNT,

"video_count":COUNT,

"image_count":COUNT,

"news_count":COUNT

}

回执参数列表

错误情况下的返回JSON数据包示例如下（示例为无效媒体类型错误）：

{"errcode":-1,"errmsg":"system error"}

用户管理

用户分组管理

目录

1 创建分组

2 修改分组名称

3 删除分组

4 移动用户分组

5 查询用户所在分组

6 查询所有分组

7 修订记录

创建分组

接口描述

除了默认分组，公众号哈可以自定义创建用户分组，一个公众账号，最多支持创建20个分组

请求方式

POST（请使用https协议）

请求地址

https://api.mp.qq.com/cgi-bin/groups/create?access_token=ACCESS_TOKEN

参数列表

调用举例

curl -d “{"group":{"name":"test"}}”

https://api.mp.qq.com/cgi-bin/groups/create?access_token=ACCESS_TOKEN

回执说明

在调用接口后，会返回JSON格式数据包。 回执参数列表

正常回执示例

{

"group": {

"id": 107,

"name": "test"

}

}

错误回执示例

{"errcode":40013,"errmsg":"invalid appid"}

修改分组名称

接口描述

除了默认分组，公众号可以修改自定义创建的分组名称

请求方式

POST（请使用https协议）

请求地址

https://api.mp.qq.com/cgi-bin/groups/update?access_token=ACCESS_TOKEN

参数列表

调用举例

curl -d '{"group":{"id":108,"name":"test2_modify2"}}'

https://api.mp.qq.com/cgi-bin/groups/update?access_token=ACCESS_TOKEN

回执说明

在调用接口后，会返回JSON格式数据包。

回执参数列表

正常回执示例

{"errcode": 0, "errmsg": "ok"}

错误回执示例

{"errcode":40013,"errmsg":"invalid appid"}

删除分组

接口描述

除了默认分组，公众号可以删除自定义创建的分组

请求方式

POST（请使用https协议）

请求地址

https://api.mp.qq.com/cgi-bin/groups/delete?access_token=ACCESS_TOKEN

参数列表

调用举例

curl -d '{"group":{"id":108}}'

https://api.mp.qq.com/cgi-bin/groups/delete?access_token=ACCESS_TOKEN

回执说明

在调用接口后，会返回JSON格式数据包。 回执参数列表

正常回执示例

{"errcode": 0, "errmsg": "ok"}

错误回执示例

{"errcode":40013,"errmsg":"invalid appid"}

移动用户分组

接口描述

公众号可以将用户从原有分组移动的新分组

请求方式

POST（请使用https协议）

请求地址

https://api.mp.qq.com/cgi-bin/groups/members/update?access_token=ACCESS_TOKEN

参数列表

调用举例

curl -d ‘{"openid":"od8XIjsmk6QdVTETa9jLtGWA6KBc"， “to_groupid”:108}’

https://api.mp.qq.com/cgi-bin/groups/members/update?access_token=ACCESS_TOKEN

回执说明

在调用接口后，会返回JSON格式数据包。 回执参数列表

正常回执示例

{"errcode": 0, "errmsg": "ok"}

错误回执示例

{"errcode":40013,"errmsg":"invalid appid"}

查询用户所在分组

接口描述

公众号可以查询用户所在的分组id

请求方式

POST（请使用https协议）

请求地址

https://api.mp.qq.com/cgi-bin/groups/getid?access_token=ACCESS_TOKEN

参数列表

调用举例

curl -d ‘{"openid":"od8XIjsmk6QdVTETa9jLtGWA6KBc"}’

https://api.mp.qq.com/cgi-bin/groups/update?access_token=ACCESS_TOKEN

回执说明

在调用接口后，会返回JSON格式数据包。 回执参数列表

正常回执示例

{"groupid": 102}

错误回执示例

{"errcode":40013,"errmsg":"invalid appid"}

查询所有分组

接口描述

公众号可以拉取所有分组列表包含系统分组

请求方式

GET（请使用https协议）

请求地址

https://api.mp.qq.com/cgi-bin/groups/get?access_token=ACCESS_TOKEN

参数列表

调用举例

curl https://api.mp.qq.com/cgi-bin/groups/get?access_token=ACCESS_TOKEN

回执说明

在调用接口后，会返回JSON格式数据包。 回执参数列表

正常回执示例

{

"groups": [

{

"id": 2,

"name": "未分组",

"count": 72596

},

{

"id": 1,

"name": "黑名单",

"count": 36

},

{

"id": 3,

"name": "星标组",

"count": 8

},

{

"id": 104,

"name": "华东媒",

"count": 4

},

{

"id": 106,

"name": "★不测试组★",

"count": 1

}

]

}

错误回执示例

{"errcode":40013,"errmsg":"invalid appid"}

获取用户列表

接口描述

公众号可通过本接口来获取帐号的关注者列表，关注者列表由一串OpenID（加密后的QQ号，每个用户对每个公众号的OpenID是唯一的）组成。一次拉取调用最多拉取10000个关注者的OpenID，可以通过多次拉取的方式来满足需求。

请求方式

GET（请使用https协议）

请求地址

https://api.mp.qq.com/cgi-bin/user/get?access_token=ACCESS_TOKEN&next_openid=NEXT_OPENID

参数列表

调用举例

curl https://api.mp.qq.com/cgi-bin/uploadnews?access_token=ACCESS_TOKEN&next_openid=NEXT_OPENID

回执说明

在调用接口后，会返回JSON格式数据包。

回执参数列表

正常回执示例

{"total":2,"count":2,"data":{"openid":["","OPENID1","OPENID2"]},"next_openid ":"NEXT_OPENID "}

错误回执示例

{"errcode": 70008, "errmsg":"模板ID和互动号不匹配"}

附：关注者数量超过10000时

当公众号关注者数量超过10000时，可通过填写next_ openid的值，从而多次拉取列表的方式来满足需求。

具体而言，就是在调用接口时，将上一次调用得到的返回中的next_ openid值，作为下一次调用中的next_ openid值。

关注者列表已返回完时，返回next_ openid为空

拉去回来的数据可能不到10000，因为存在OPENID失效的问题，next_ openid值与total，count不存在任何关系，请注意此点。

获取用户基本信息

接口描述

在关注者与公众号产生消息交互后，公众号可获得关注者的OpenID。公众号可通过本接口来根据OpenID获取用户基本信息，包括昵称、头像、性别、所在城市、语言和关注时间。

请求方式

GET（请使用https协议）

请求地址

https://api.mp.qq.com/cgi-bin/user/info?access_token=ACCESSTOKEN&openid=OPENID&lang=zh_CN

参数列表

调用举例

curl https://api.mp.qq.com/cgi-bin/user/info?access_token=ACCESSTOKEN&openid=OPENID&lang=zh_CN

回执说明

在调用接口后，会返回JSON格式数据包。

回执参数列表

正常回执示例

{

"city":"徐汇",

"country":"中国",

"headimgurl":"http://q3.qlogo.cn/g?b=qq&k=Xjoekyy77Xjib95vxBic8stQ&s=40&t=30042",

"language":"zh_CN",

"nickname":"大风吹",

"province":"上海",

"sex":"男",

"subscribe":1,

"subscribe_time":1427363069

}

错误回执示例

{"errcode":40003,"errmsg":"\u89e3\u6790JSON\/XML\u5185\u5bb9\u9519\u8bef"}

网页授权获取用户基本信息

关于网页授权回调域名的说明

1、在QQ公众号请求用户网页授权之前，开发者需要先到公众平台官网中的开发者中心页配置授权回调域名。请注意，这里填写的是域名（是一个字符串），而不是URL，因此请勿加http://等协议头；

2、授权回调域名配置规范为全域名，比如需要网页授权的域名为：www.qq.com，配置以后此域名下面的页面http://www.qq.com/music.html 、 http://www.qq.com/login.html 都可以进行OAuth2.0鉴权。但http://pay.qq.com 、 http://music.qq.com 、 http://qq.com无法进行OAuth2.0鉴权

3、如果公众号登录授权给了第三方开发者来进行管理，则不必做任何设置，由第三方代替公众号实现网页授权即可

关于网页授权scope的说明

1、以snsapi_base为scope发起的网页授权，是用来获取进入页面的用户的openid的，并且是静默授权并自动跳转到回调页的。用户感知的就是直接进入了回调页（往往是业务页面）

2、用户管理类接口中的“获取用户基本信息接口”，是在用户和公众号产生消息交互或关注后事件推送后，才能根据用户OpenID来获取用户基本信息。这个接口，包括其他QQ公众号接口，都是需要该用户（即openid）关注了公众号后，才能调用成功的。

3、用户管理类接口中的“获取用户基本信息接口”，是在用户和公众号产生消息交互或关注后事件推送后，才能根据用户OpenID来获取用户基本信息。这个接口，包括其他QQ公众号接口，都是需要该用户（即openid）关注了公众号后，才能调用成功的。

关于网页授权access_token和普通access_token的区别

1、QQ网页授权是通过OAuth2.0机制实现的，在用户授权给公众号后，公众号可以获取到一个网页授权特有的接口调用凭证（网页授权access_token），通过网页授权access_token可以进行授权后接口调用，如获取用户基本信息；

2、其他QQ公众号接口，需要通过基础支持中的“获取access_token”接口来获取到的普通access_token调用。

关于UnionID机制

1、请注意，网页授权获取用户基本信息也遵循UnionID机制。即如果开发者有在多个公众号，或在公众号、移动应用之间统一用户帐号的需求，需要前往QQ公众号开放平台（open.mp.qq.com）绑定公众号后，才可利用UnionID机制来满足上述需求。

2、UnionID机制的作用说明：如果开发者拥有多个移动应用、网站应用和公众帐号，可通过获取用户基本信息中的unionid来区分用户的唯一性，因为同一用户，对同一个QQ公众号开放平台下的不同应用（移动应用、网站应用和公众帐号），unionid是相同的。

关于特殊场景下的静默授权

1、 上面已经提到，对于以snsapi_base为scope的网页授权，就静默授权的，用户无感知；

2、 对于已关注公众号的用户，如果用户从公众号的会话或者自定义菜单进入本公众号的网页授权页，即使是scope为snsapi_userinfo，也是静默授权，用户无感知。

具体而言，网页授权流程分为四步：

1、引导用户进入授权页面同意授权，获取code

2、通过code换取网页授权access_token（与基础支持中的access_token不同）

3、如果需要，开发者可以刷新网页授权access_token，避免过期

4、通过网页授权access_token和openid获取用户基本信息（支持UnionID机制）

第一步：用户同意授权，获取code

在确保QQ公众账号拥有授权作用域（scope参数）的权限的前提下（服务号获得高级接口后，默认拥有scope参数中的snsapi_base），引导关注者打开如下页面：

https://open.mp.qq.com/connect/oauth2/authorize?appid=APPID&redirect_uri=REDIRECT_URI&response_type=code&scope=SCOPE&state=STATE#qq_redirect

若提示“该链接无法访问”，请检查参数是否填写错误，是否拥有scope参数对应的授权作用域权限。

尤其注意：由于授权操作安全等级较高，所以在发起授权请求时，微信会对授权链接做正则强匹配校验，如果链接的参数顺序不对，授权页面将无法正常访问

参考链接(请在QQ客户端中打开此链接体验)

Scope为snsapi_base

https://open.mp.qq.com/connect/oauth2/authorize?appid=wx520c15f417810387&redirect_uri=http%3A%2F%2Fchong.qq.com%2Fphp%2Findex.php%3Fd%3D%26c%3DwxAdapter%26m%3DmobileDeal%26showwxpaytitle%3D1%26vb2ctag%3D4_2030_5_1194_60&response_type=code&scope=snsapi_base&state=123#qq_redirect

Scope为snsapi_userinfo

https://open.mp.qq.com/connect/oauth2/authorize?appid=wxf0e81c3bee622d60&redirect_uri=http%3A%2F%2Fnba.bluewebgame.com%2Foauth_response.php&response_type=code&scope=snsapi_userinfo&state=STATE#qq_redirect

参数说明

scope等于snsapi_userinfo时出现授权页面

如果用户同意授权，页面将跳转至 redirect_uri/?code=CODE&state=STATE。若用户禁止授权，则重定向后不会带上code参数，仅会带上state参数redirect_uri?state=STATE

code说明 ：

code作为换取access_token的票据，每次用户授权带上的code将不一样，code只能使用一次，5分钟未被使用自动过期。

第二步：通过code换取网页授权access_token

首先请注意，这里通过code换取的是一个特殊的网页授权access_token,与基础支持中的access_token（该access_token用于调用其他接口）不同。公众号可通过下述接口来获取网页授权access_token。如果网页授权的作用域为snsapi_base，则本步骤中获取到网页授权access_token的同时，也获取到了openid，snsapi_base式的网页授权流程即到此为止。

请求方法

获取code后，请求以下链接获取access_token：

https://api.mp.qq.com/sns/oauth2/access_token?appid=APPID&secret=SECRET&code=CODE&grant_type=authorization_code

参数说明

返回说明

正确时返回的JSON数据包如下：

{

"access_token":"ACCESS_TOKEN",

"expires_in":7200,

"refresh_token":"REFRESH_TOKEN",

"openid":"OPENID",

"scope":"SCOPE",

"unionid": "o6_bmasdasdsad6_2sgVt7hMZOPfL"

}

错误时QQ公众号会返回JSON数据包如下（示例为Code无效错误）:

{"errcode":40029,"errmsg":"invalid code"}

第三步：刷新access_token（如果需要）

由于access_token拥有较短的有效期，当access_token超时后，可以使用refresh_token进行刷新，refresh_token拥有较长的有效期（7天、30天、60天、90天），当refresh_token失效的后，需要用户重新授权。

请求方法

获取第二步的refresh_token后，请求以下链接获取access_token：

https://api.mp.qq.com/sns/oauth2/refresh_token?appid=APPID&grant_type=refresh_token&refresh_token=REFRESH_TOKEN

参数说明

返回说明

正确时返回的JSON数据包如下：

{

"access_token":"ACCESS_TOKEN",

"expires_in":7200,

"refresh_token":"REFRESH_TOKEN",

"openid":"OPENID",

"scope":"SCOPE"

}

错误时QQ公众号会返回JSON数据包如下（示例为Code无效错误）:

{"errcode":40029,"errmsg":"invalid code"}

详见全局返回码说明

第四步：拉取用户信息(需scope为 snsapi_userinfo)

如果网页授权作用域为snsapi_userinfo，则此时开发者可以通过access_token和openid拉取用户信息了。

请求方法

http：GET（请使用https协议）

https://api.mp.qq.com/sns/userinfo?access_token=ACCESS_TOKEN&openid=OPENID&lang=zh_CN

参数说明

返回说明

正确时返回的JSON数据包如下：

{

"openid":" OPENID",

"nickname": NICKNAME,

"sex":"1",

"province":"PROVINCE"

"city":"CITY",

"country":"COUNTRY",

"headimgurl": "http://mp.qlogo.cn/mmopen/g3MonUZtNHkdmzicIlibx6iaFqAc56vxLSUfpb6n5WKSYVY0ChQKkiaJSgQ1dZuTOgvLLrhJbERQQ4eMsv84eavHiaiceqxibJxCfHe/46",

"privilege":[

"PRIVILEGE1"

"PRIVILEGE2"

],

"unionid": "o6_bmasdasdsad6_2sgVt7hMZOPfL"

}

错误时微信会返回JSON数据包如下（示例为openid无效）:

{"errcode":40003,"errmsg":" invalid openid "}

全局返回码说明

附：检验授权凭证（access_token）是否有效

请求方法

http：GET（请使用https协议）

https://api.mp.qq.com/sns/auth?access_token=ACCESS_TOKEN&openid=OPENID

参数说明

返回说明

正确的Json返回结果：

{"errcode":0,"errmsg":"ok"}

错误时的Json返回示例：

{"errcode":40003,"errmsg":"invalid openid"}

自定义菜单管理

自定义菜单创建接口

接口描述

自定义菜单能够帮助公众号丰富界面，让用户更好更快地理解公众号的功能。 目前自定义菜单最多包括3个一级菜单，每个一级菜单最多包含5个二级菜单。一级菜单最多4个汉字，二级菜单最多7个汉字，多出来的部分将会以“...”代替。请注意，创建自定义菜单后，由于手Q客户端缓存，需要XX小时手Q客户端才会展现出来。建议测试时可以尝试取消关注公众账号后再次关注，则可以看到创建后的效果。

请求方式

POST（请使用https协议）

请求地址

https://api.mp.qq.com/cgi-bin/menu/create?access_token=ACCESS_TOKEN

参数列表

调用举例

curl –d “https://api.mp.qq.com/cgi-bin/menu/create?access_token=ACCESS_TOKEN”

{

"button":[

{

"type":"click",

"name":"今日歌曲",

"key":"V1001_TODAY_MUSIC"

},

{

"name":"菜单",

"sub_button":[

{

"type":"view",

"name":"搜索",

"url":"http://www.soso.com/"

},

{

"type":"view",

"name":"视频",

"url":"http://v.qq.com/"

},

{

"type":"click",

"name":"赞一下我们",

"key":"V1001_GOOD"

}]

}]

}

回执说明

在调用接口后，会返回JSON格式数据包。

回执参数列表

正常回执示例

{"errcode":0,"errmsg":"ok"}

错误回执示例

{"errcode":40013,"errmsg":"invalid appid"}

自定义菜单查询接口

接口描述

使用接口创建自定义菜单后，开发者还可使用接口查询自定义菜单的结构

请求方式

GET（请使用https协议）

请求地址

https://api.mp.qq.com/cgi-bin/menu/get?access_token=ACCESS_TOKEN

参数列表

无

调用举例

curl“https://api.mp.qq.com/cgi-bin/menu/get?access_token=ACCESS_TOKEN”

回执说明

在调用接口后，会返回JSON格式数据包。

正常回执示例

{

"menu":{

"button":[

{

"type":"click",

"name":"今日歌曲",

"key":"V1001_TODAY_MUSIC",

"sub_button":[]

},

{

"type":"click",

"name":"歌手简介",

"key":"V1001_TODAY_SINGER",

"sub_button":[]

},

{

"name":"菜单",

"sub_button":[

{

"type":"view",

"name":"搜索",

"url":"http://www.soso.com/",

"sub_button":[]

},

{

"type":"view",

"name":"视频",

"url":"http://v.qq.com/",

"sub_button":[]

},

{

"type":"click",

"name":"赞一下我们",

"key":"V1001_GOOD",

"sub_button":[]

}]

}]

}

}

自定义菜单删除接口

接口描述

使用接口创建自定义菜单后，开发者还可使用接口删除当前使用的自定义菜单。

请求方式

GET（请使用https协议）

请求地址

https://api.mp.qq.com/cgi-bin/menu/delete?access_token=ACCESS_TOKEN

参数列表

无

调用举例

curl “https://api.mp.qq.com/cgi-bin/menu/delete?access_token=ACCESS_TOKEN”

回执说明

在调用接口后，会返回JSON格式数据包。

回执参数列表

正常回执示例

{"errcode":0,"errmsg":"ok"}

错误回执示例

{"errcode":40013,"errmsg":"invalid appid"}

帐号管理

生成带参数的二维码

接口描述

为了满足用户渠道推广分析的需要，公众平台提供了生成带参数二维码的接口。使用该接口可以获得多个带不同场景值的二维码，用户扫描后，公众号可以接收到事件推送。

目前有2种类型的二维码，分别是临时二维码和永久二维码，前者有过期时间，最大为1800秒，但能够生成较多数量，后者无过期时间，数量较少（目前参数只支持1--100000）。两种二维码分别适用于帐号绑定、用户来源统计等场景。

用户扫描带场景值二维码时，可能推送以下两种事件：

a）如果用户还未关注公众号，则用户可以关注公众号，关注后手Q会将带场景值关注事件推送给开发者。

b）如果用户已经关注公众号，在用户扫描后会自动进入会话，手Q也会将带场景值扫描事件推送给开发者。

获取带参数的二维码的过程包括两步，首先创建二维码ticket，然后凭借ticket到指定URL换取二维码。

创建二维码ticket

每次创建二维码ticket需要提供一个开发者自行设定的参数（scene_id），分别介绍临时二维码和永久二维码的创建二维码ticket过程。

临时二维码请求说明

http请求方式: POST

URL: https://api.mp.qq.com/cgi-bin/qrcode/create?access_token=TOKEN

POST数据格式：json

POST数据例子：{"expire_seconds": 1800, "action_name": "QR_SCENE", "action_info": {"scene": {"scene_id": 123}}}

永久二维码请求说明

http请求方式: POST

URL: https://api.mp.qq.com/cgi-bin/qrcode/create?access_token=TOKEN

POST数据格式：json

POST数据例子：{"action_name": "QR_LIMIT_SCENE", "action_info": {"scene": {"scene_id": 123}}}

或者也可以使用以下POST数据创建字符串形式的二维码参数：

{"action_name": "QR_LIMIT_STR_SCENE", "action_info": {"scene": {"scene_str": "123"}}}

参数说明

回执说明

在调用接口后，会返回JSON格式数据包。

回执参数列表

正常回执示例

{"ticket":"WmpFUm5h","url":"http:\/\/test.tcsh.qq.com\/s\/ZjERna?c2b=1","expire_seconds":1800}

{"ticket":"SnZBZlF2","url":"http:\/\/test.tcsh.qq.com\/s\/JvAfQv?c2b=1","expire_seconds":0}

错误回执示例

{"errcode":47001,"errmsg":"\u89e3\u6790JSON\/XML\u5185\u5bb9\u9519\u8bef"}

通过ticket换取二维码

获取二维码ticket后，开发者可用ticket换取二维码图片。请注意，本接口无须登录态即可调用。

请求说明

HTTP GET请求（请使用https协议）

https://api.mp.qq.com/cgi-bin/showqrcode?ticket=TICKET

回执说明

ticket正确情况下，http 返回码是200，是一张图片，可以直接展示或者下载。

HTTP头（示例）如下：

Accept-Ranges:bytes

Cache-control:max-age=604800

Connection:keep-alive

Content-Length:28026

Content-Type:image/jpg

Date:Wed, 16 Oct 2013 06:37:10 GMT

Expires:Wed, 23 Oct 2013 14:37:10 +0800

Server:nginx/1.4.1

错误情况下（如ticket非法）返回HTTP错误码404。

长链接转短链接接口

接口描述

将一条长链接转成短链接。

主要使用场景：开发者用于生成二维码的原链接（商品、支付二维码等）太长导致扫码速度和成功率下降，将原长链接通过此接口转成短链接再生成二维码将大大提升扫码速度和成功率。

请求说明

开发者可通过OpenID来获取用户基本信息。请使用https协议。

请求方式

POST（请使用https协议）

请求地址

https://api.mp.qq.com/cgi-bin/shorturl?access_token=ACCESS_TOKEN

参数列表

调用举例

curl -d "{\"action\":\"long2short\",\"long_url\":\"http://wap.koudaitong.com/v2/showcase/goods?alias=128wi9shh&spm=h56083&redirect_count=1\"}" "https://api.mp.qq.com/cgi-bin/shorturl?access_token=ACCESS_TOKEN"

返回说明

参数列表

正常情况下，微信会返回下述JSON数据包给公众号：

{"errcode":0,"errmsg":"ok","short_url":"http:\/\/w.url.cn\/s\/AvCo6Ih"}

错误时微信会返回错误码等信息，JSON数据包示例如下（该示例为AppID无效错误）:

{"errcode":40013,"errmsg":"invalid appid"}

全局错误码