2024年4月10日发(作者：)
微信公众平台开发者文档
tacyeh收集整理
文档内容截至日期：2013-12-25
1
目 录
零、首页 ..................................................................................... - 1 -
一、公众平台开发接口介绍 ....................................................... - 1 -
二、典型案例介绍 ....................................................................... - 1 -
壹、新手接入 .............................................................................. - 4 -
一、接入指南 ............................................................................... - 4 -
二、典型案例介绍 ....................................................................... - 6 -
三、开发者规范 ........................................................................... - 9 -
贰、基础支持 ............................................................................ - 10 -
一、获取access_token ............................................................. - 10 -
二、全局返回码说明 ................................................................. - 11 -
三、接口频率限制说明 ............................................................. - 14 -
四、上传下载多媒体文件 ......................................................... - 15 -
叁、接收消息 ............................................................................ - 18 -
一、验证消息真实性 ................................................................. - 18 -
二、接收普通消息 ..................................................................... - 19 -
三、接收事件推送 ..................................................................... - 23 -
四、接收语音识别结果 ............................................................. - 27 -
肆、发送消息 ............................................................................ - 28 -
一、发送被动响应消息 ............................................................. - 28 -
二、发送客服消息 ..................................................................... - 31 -
伍、用户管理 ............................................................................ - 35 -
2
一、分组管理接口 ..................................................................... - 35 -
二、获取用户基本信息 ............................................................. - 39 -
三、获取关注者列表 ................................................................. - 40 -
四、获取用户地理位置 ............................................................. - 43 -
五、网页授权获取用户基本信息 ............................................. - 43 -
六、网页获取用户网络状态（JS接口） ................................. - 50 -
陆、自定义菜单 ........................................................................ - 50 -
一、自定义菜单创建接口 ......................................................... - 50 -
二、自定义菜单查询接口 ......................................................... - 53 -
三、自定义菜单删除接口 ......................................................... - 54 -
四、自定义菜单事件推送 ......................................................... - 54 -
柒、推广支持 ............................................................................ - 55 -
一、生成带参数的二维码 ......................................................... - 55 -
二、创建二维码ticket ............................................................... - 55 -
三、通过ticket换取二维码 ...................................................... - 56 -
捌、Winxin JS接口 .................................................................. - 57 -
一、隐藏微信中网页右上角按钮 ............................................. - 57 -
二、隐藏微信中网页底部导航栏 ............................................. - 58 -
三、网页获取用户网络状态 ..................................................... - 59 -
3
零、首页
一、公众平台开发接口介绍
公众平台是为微信用户提供服务的平台，而公众平台开发接口则是提供服务
的基础，开发者在公众平台网站中创建公众号、获取接口权限后，可以通过阅读
本接口文档来帮助开发。
公众平台开发接口提供与用户进行消息交互、自定义菜单交互的能力。对于
成功接入公众平台开发接口的公众账号，当用户发消息给公众号，微信公众平台
服务器会使用http请求对接入的网址进行消息推送，第三方服务器可通过响应
包回复特定结构，从而达到回复消息的目的。
二、典型案例介绍
值得借鉴的公众帐号主要是服务号，试列举并介绍如下：
招商银行信用卡中心
- 1 -
如果你是持卡人，可快捷查询信用卡账单、额度及积分；快速还款、申请账
单分期；微信转接人工服务；信用卡消费，微信免费笔笔提醒。如果不是持卡人，
可以微信办卡！
招商银行公众号通过提示消息引导用户将自己的微信号和信用卡号安全绑定。
用户可以通过该公众号查询账单、收取刷卡通知等功能，这是由招行开发人员
通过公众号接口实现的功能。
中国南方航空
- 2 -
你可以办理值机手续，挑选座位，查询航班信息，查询目的地城市天气，并
为明珠会员提供专业的服务。
南方航空公众号可以让用户将明珠会员服务和微信号绑定起来。
用户可以通过该公众号预订机票、查询订单，甚至办理登机牌。
广东联通
- 3 -
你可以在微信里绑定手机号、积分流量，套餐余量、手机上网流量，微信专
属流量查询，客服咨询。
广东联通公众号可以绑定手机号，来查询流量、套餐等等功能。
广东联通更与微信深度合作，购买微信沃卡可以获得微信五大特权。
壹、新手接入
一、接入指南
第一步：申请消息接口
- 4 -
在公众平台网站的高级功能–开发模式页，点击“成为开发者”按钮，填写
URL和Token，其中URL是开发者用来接收微信服务器数据的接口URL。Token
可由开发者可以任意填写，用作生成签名（该Token会和接口URL中包含的
Token进行比对，从而验证安全性）。
第二步：验证URL有效性
开发者提交信息后，微信服务器将发送GET请求到填写的URL上，GET请
求携带四个参数：
参数
signature
timestamp
nonce
echostr
描述
微信加密签名，signature结合了开发者填写的token参数和请求中
的timestamp参数、nonce参数。
时间戳
随机数
随机字符串
开发者通过检验signature对请求进行校验（下面有校验方式）。若确认此
次GET请求来自微信服务器，请原样返回echostr参数内容，则接入生效，成为
开发者成功，否则接入失败。
加密/校验流程如下：
1. 将token、timestamp、nonce三个参数进行字典序排序；
2. 将三个参数字符串拼接成一个字符串进行sha1加密；
3. 开发者获得加密后的字符串可与signature对比，标识该请求来源于微信。
检验signature的PHP示例代码：
1.
2.
3.
4.
5.
6.
private function checkSignature()
{
$signature = $_GET["signature"];
$timestamp = $_GET["timestamp"];
$nonce = $_GET["nonce"];
$token = TOKEN;
- 5 -
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.
$tmpArr = array($token, $timestamp, $nonce);
sort($tmpArr);
$tmpStr = implode( $tmpArr );
$tmpStr = sha1( $tmpStr );
if( $tmpStr == $signature ){
return true;
}else{
return false;
}
}
PHP示例代码下载：/mpres/htmledition/res/wx_
第三步：成为开发者
验证URL有效性成功后即接入生效，成为开发者。如果公众号类型为服务
号（订阅号只能使用普通消息接口），可以在公众平台网站中申请认证，认证成
功的服务号将获得众多接口权限，以满足开发者需求。
此后用户每次向公众号发送消息、或者产生自定义菜单点击事件时，响应
URL将得到推送。
公众号调用各接口时，一般会获得正确的结果，具体结果可见对应接口的说
明。返回错误时，可根据返回码来查询错误原因。全局返回码说明
用户向公众号发送消息时，公众号方收到的消息发送者是一个OpenID，是
使用用户微信号加密后的结果，每个用户对每个公众号有一个唯一的OpenID。
此外请注意，微信公众号接口只支持80接口。
二、典型案例介绍
值得借鉴的公众帐号主要是服务号，试列举并介绍如下：
招商银行信用卡中心
- 6 -
如果你是持卡人，可快捷查询信用卡账单、额度及积分；快速还款、申请账
单分期；微信转接人工服务；信用卡消费，微信免费笔笔提醒。如果不是持卡人，
可以微信办卡！
招商银行公众号通过提示消息引导用户将自己的微信号和信用卡号安全绑定。
用户可以通过该公众号查询账单、收取刷卡通知等功能，这是由招行开发人员
通过公众号接口实现的功能。
中国南方航空
- 7 -
你可以办理值机手续，挑选座位，查询航班信息，查询目的地城市天气，并
为明珠会员提供专业的服务。
南方航空公众号可以让用户将明珠会员服务和微信号绑定起来。
用户可以通过该公众号预订机票、查询订单，甚至办理登机牌。
广东联通
- 8 -
你可以在微信里绑定手机号、积分流量，套餐余量、手机上网流量，微信专
属流量查询，客服咨询。
广东联通公众号可以绑定手机号，来查询流量、套餐等等功能。
广东联通更与微信深度合作，购买微信沃卡可以获得微信五大特权。
三、开发者规范
开发者进行公众号开发时，除了需要满足每个接口的规范限制、调用频率限
制外，还需特别注意模版消息、用户数据等敏感信息的使用规范。
涉及用户数据时：
您的服务需要收集用户任何数据的，必须事先获得用户的明确同意，且
仅应当收集为运营及功能实现目的而必要的用户数据， 同时应当告知
用户相关数据收集的目的、范围及使用方式等，保障用户知情权。
您收集用户的数据后，必须采取必要的保护措施，防止用户数据被盗、
泄漏等。
- 9 -
您在特定微信公众号中收集的用户数据仅可以在该特定微信公众号中
使用，不得将其使用在该特定微信公众号之外或为其他任何目的进行使
用，也不得以任何方式将其提供给他人。
如果腾讯认为您收集、使用用户数据的方式，可能损害用户体验，腾讯
有权要求您删除相关数据并不得再以该方式收集、使用用户数据。
一旦您停止使用本服务，或腾讯基于任何原因终止您使用本服务，您必
须立即删除全部因使用本服务而获得的数据（包括各种备份）， 且不
得再以任何方式进行使用。
其他规范：
请勿为任何用户自动登录到微信公众平台提供代理身份验证凭据。
请勿提供跟踪功能，包括但不限于识别其他用户在个人主页上查看、点
击等操作行为。
请勿自动将浏览器窗口定向到其他网页。
请勿设置或发布任何违反相关法规、公序良俗、社会公德等的玩法、内
容等。
请勿公开表达或暗示，您与腾讯之间存在合作关系，包括但不限于相互
持股、商业往来或合作关系等，或声称腾讯对您的认可。
完整的开发者规范和接口限制，请详见开发者接口文档，以及腾讯微信公众
平台开发者协议。
贰、基础支持
一、获取access_token
access_token是公众号的全局唯一票据，公众号调用各接口时都需使用
access_token。正常情况下access_token有效期为7200秒，重复获取将导致上
次获取的access_token失效。
- 10 -
公众号可以使用AppID和AppSecret调用本接口来获取access_token。AppID
和AppSecret可在开发模式中获得（需要已经成为开发者，且帐号没有异常
状态）。注意调用所有微信接口时均需使用https协议。
接口调用请求说明
http请求方式: GET
/cgi-bin/token?grant_type=client_credential&appid
=APPID&secret=APPSECRET
参数说明
参数
grant_type
appid
secret
是
是
是
是否必须
返回说明
正常情况下，微信会返回下述JSON数据包给公众号：
{"access_token":"ACCESS_TOKEN","expires_in":7200}
参数
access_token
expires_in
获取到的凭证
凭证有效时间，单位：秒
说明
错误时微信会返回错误码等信息，JSON数据包示例如下（该示例为AppID
无效错误）:
{"errcode":40013,"errmsg":"invalid appid"}
二、全局返回码说明
公众号每次调用接口时，可能获得正确或错误的返回码，开发者可以根据返
- 11 -
回码信息调试接口，排查错误。
全局返回码说明如下：
返回码
-1
0
40001
40002
40003
40004
40005
40006
40007
40008
40009
40010
40011
40012
40013
40014
40015
40016
40017
40018
40019
40020
40021
40022
40023
40024
40025
40026
40027
40028
40029
40030
40031
40032
40033
40035
说明
系统繁忙
请求成功
获取access_token时AppSecret错误，或者access_token无效
不合法的凭证类型
不合法的OpenID
不合法的媒体文件类型
不合法的文件类型
不合法的文件大小
不合法的媒体文件id
不合法的消息类型
不合法的图片文件大小
不合法的语音文件大小
不合法的视频文件大小
不合法的缩略图文件大小
不合法的APPID
不合法的access_token
不合法的菜单类型
不合法的按钮个数
不合法的按钮个数
不合法的按钮名字长度
不合法的按钮KEY长度
不合法的按钮URL长度
不合法的菜单版本号
不合法的子菜单级数
不合法的子菜单按钮个数
不合法的子菜单按钮类型
不合法的子菜单按钮名字长度
不合法的子菜单按钮KEY长度
不合法的子菜单按钮URL长度
不合法的自定义菜单使用用户
不合法的oauth_code
不合法的refresh_token
不合法的openid列表
不合法的openid列表长度
不合法的请求字符，不能包含uxxxx格式的字符
不合法的参数
- 12 -
40038
40039
40050
40051
41001
41002
41003
41004
41005
41006
41007
41008
41009
42001
42002
42003
43001
43002
43003
43004
43005
44001
44002
44003
44004
45001
45002
45003
45004
45005
45006
45007
45008
45009
45010
45015
45016
45017
45018
不合法的请求格式
不合法的URL长度
不合法的分组id
分组名字不合法
缺少access_token参数
缺少appid参数
缺少refresh_token参数
缺少secret参数
缺少多媒体文件数据
缺少media_id参数
缺少子菜单数据
缺少oauth code
缺少openid
access_token超时
refresh_token超时
oauth_code超时
需要GET请求
需要POST请求
需要HTTPS请求
需要接收者关注
需要好友关系
多媒体文件为空
POST的数据包为空
图文消息内容为空
文本消息内容为空
多媒体文件大小超过限制
消息内容超过限制
标题字段超过限制
描述字段超过限制
链接字段超过限制
图片链接字段超过限制
语音播放时间超过限制
图文消息超过限制
接口调用超过限制
创建菜单个数超过限制
回复时间超过限制
系统分组，不允许修改
分组名字过长
分组数量超过上限
- 13 -
46001
46002
46003
46004
47001
48001
50001
不存在媒体数据
不存在的菜单版本
不存在的菜单数据
不存在的用户
解析JSON/XML内容错误
api功能未授权
用户未授权该api
三、接口频率限制说明
公众号调用接口并不是无限制的。为了防止公众号的程序错误而引发微信服
务器负载异常，默认情况下，每个公众号调用接口都不能超过一定限制，当超过
一定限制时，调用对应接口会收到如下错误返回码：
{"errcode":45009,"errmsg":"api freq out of limit"}
各接口调用频率限制如下：
接口
获取access_token
自定义菜单创建
自定义菜单查询
自定义菜单删除
创建分组
获取分组
修改分组名
移动用户分组
上传多媒体文件
下载多媒体文件
发送客服消息
获取带参数的二维码
获取关注者列表
获取用户基本信息
获取网页授权access_token
刷新网页授权access_token
网页授权获取用户信息
2000
1000
10000
1000
1000
1000
1000
100000
5000
10000
500000
100000
500
5000000
2000000
2000000
2000000
每日限额
请注意，在测试号申请页中申请的测试号，接口调用频率限制如下：
接口
获取access_token
自定义菜单创建
每日限额
200
100
- 14 -
自定义菜单查询
自定义菜单删除
创建分组
获取分组
修改分组名
移动用户分组
上传多媒体文件
下载多媒体文件
发送客服消息
获取带参数的二维码
获取关注者列表
获取用户基本信息
获取网页授权access_token
刷新网页授权access_token
网页授权获取用户信息
1000
100
100
100
100
1000
500
1000
50000
10000
100
500000
200000
200000
200000
四、上传下载多媒体文件
公众号在使用接口时，对多媒体文件、多媒体消息的获取和调用等操作，是
通过media_id来进行的。通过本接口，公众号可以上传或下载多媒体文件。但
请注意，每个多媒体文件（media_id）会在上传、用户发送到微信服务器3天后
自动删除，以节省服务器资源。
上传多媒体文件
公众号可调用本接口来上传图片、语音、视频等文件到微信服务器，上传后
服务器会返回对应的media_id，公众号此后可根据该media_id来获取多媒体。
请注意，media_id是可复用的，调用该接口需http协议。
接口调用请求说明
http请求方式: POST/FORM
/cgi-bin/media/upload?access_token=ACCESS_T
OKEN&type=TYPE
调用示例（使用curl命令，用FORM表单方式上传一个多媒体文件）：
- 15 -
curl -F media=@
"/cgi-bin/media/upload?access_token=ACCESS_T
OKEN&type=TYPE"
参数说明
参数
access_token
type
media
是否必须
是
是
是
调用接口凭证
媒体文件类型，分别有图片（image）、语音（voice）、视
频（video）和缩略图（thumb）
form-data中媒体文件标识，有filename、filelength、
content-type等信息
说明
返回说明
正确情况下的返回JSON数据包结果如下：
{"type":"TYPE","media_id":"MEDIA_ID","created_at":123456789}
参数
type
media_id
描述
媒体文件类型，分别有图片（image）、语音（voice）、视频（video）和缩略
图（thumb，主要用于视频与音乐格式的缩略图）
媒体文件上传后，获取时的唯一标识
created_at
媒体文件上传时间戳
错误情况下的返回JSON数据包示例如下（示例为无效媒体类型错误）：
{"errcode":40004,"errmsg":"invalid media type"}
注意事项
上传的多媒体文件有格式和大小限制，如下：
图片（image）: 128K，支持JPG格式
语音（voice）：256K，播放长度不超过60s，支持AMRMP3格式
视频（video）：1MB，支持MP4格式
缩略图（thumb）：64KB，支持JPG格式
媒体文件在后台保存时间为3天，即3天后media_id失效。
- 16 -
下载多媒体文件
公众号可调用本接口来获取多媒体文件。请注意，视频文件不支持下载，调
用该接口需http协议。
接口调用请求说明
http请求方式: GET
/cgi-bin/media/get?access_token=ACCESS_TOKE
N&media_id=MEDIA_ID
请求示例（示例为通过curl命令获取多媒体文件）
curl -I -G
"/cgi-bin/media/get?access_token=ACCESS_TOK
EN&media_id=MEDIA_ID"
参数说明
参数
access_token
media_id
是
是
是否必须
调用接口凭证
媒体文件ID
说明
返回说明
正确情况下的返回HTTP头如下：
HTTP/1.1 200 OK
Connection: close
Content-Type: image/jpeg
Content-disposition: attachment; filename="MEDIA_"
Date: Sun, 06 Jan 2013 10:20:18 GMT
Cache-Control: no-cache, must-revalidate
Content-Length: 339721
- 17 -
curl -G
"/cgi-bin/media/get?access_token=ACCESS_TOK
EN&media_id=MEDIA_ID"
错误情况下的返回JSON数据包示例如下（示例为无效媒体ID错误）：:
{"errcode":40007,"errmsg":"invalid media_id"}
叁、接收消息
一、验证消息真实性
在开发者首次提交验证申请时，微信服务器将发送GET请求到填写的URL
上，并且带上四个参数（signature、timestamp、nonce、echostr），开发者通
过对签名（即signature）的效验，来判断此条消息的真实性。
此后，每次开发者接收用户消息的时候，微信也都会带上前面三个参数
（signature、timestamp、nonce）访问开发者设置的URL，开发者依然通过对
签名的效验判断此条消息的真实性。效验方式与首次提交验证申请一致。
参数
signature
描述
微信加密签名，signature结合了开发者填写的token参数和请求中的
timestamp参数、nonce参数。
随机数
随机字符串
timestamp
时间戳
nonce
echostr
开发者通过检验signature对请求进行校验（下面有校验方式）。若确认此
次GET请求来自微信服务器，请原样返回echostr参数内容，则接入生效，成为
开发者成功，否则接入失败。
加密/校验流程如下：
1. 将token、timestamp、nonce三个参数进行字典序排序
- 18 -
2. 将三个参数字符串拼接成一个字符串进行sha1加密
3. 开发者获得加密后的字符串可与signature对比，标识该请求来源于微信
检验signature的PHP示例代码：
17.
18.
19.
20.
21.
22.
23.
24.
25.
26.
27.
28.
29.
30.
31.
32.
private function checkSignature()
{
$signature = $_GET["signature"];
$timestamp = $_GET["timestamp"];
$nonce = $_GET["nonce"];
$token = TOKEN;
$tmpArr = array($token, $timestamp, $nonce);
sort($tmpArr);
$tmpStr = implode( $tmpArr );
$tmpStr = sha1( $tmpStr );
if( $tmpStr == $signature ){
return true;
}else{
return false;
}
}
二、接收普通消息
当普通微信用户向公众账号发消息时，微信服务器将POST消息的XML数
据包到开发者填写的URL上。各消息类型的推送XML数据包结构如下。
1、文本消息
XML数据包示例：
33.
34.
35.
36.
37.
38.
39.
40.
参数说明：
- 19 -
参数
ToUserName
FromUserName
CreateTime
MsgType
Content
MsgId
开发者微信号
描述
发送方帐号（一个OpenID）
消息创建时间 （整型）
text
文本消息内容
消息id，64位整型
2、图片消息
XML数据包示例：
41.
42.
43.
44.
45.
46.
47.
48.
49.
参数说明：
参数
ToUserName
FromUserName
CreateTime
MsgType
PicUrl
MediaId
MsgId
开发者微信号
发送方帐号（一个OpenID）
消息创建时间 （整型）
image
图片链接
图片消息媒体id，可以调用多媒体文件下载接口拉取数据。
消息id，64位整型
描述
3、语音消息
XML数据包示例：
50.
51.
- 20 -
52.
53.
54.
55.
56.
57.
58.
参数说明：
参数
ToUserName
FromUserName
CreateTime
MsgType
MediaId
Format
MsgID
开发者微信号
发送方帐号（一个OpenID）
消息创建时间 （整型）
语音为voice
语音消息媒体id，可以调用多媒体文件下载接口拉取数据。
语音格式，如amr，speex等
消息id，64位整型
描述
4、视频消息
XML数据包示例：
59.
60.
61.
62.
63.
64.
65.
66.
67.
参数说明：
参数
ToUserName
FromUserName
CreateTime
MsgType
开发者微信号
发送方帐号（一个OpenID）
消息创建时间 （整型）
视频为video
- 21 -
描述
MediaId
ThumbMediaId
MsgId
视频消息媒体id，可以调用多媒体文件下载接口拉取数据。
视频消息缩略图的媒体id，可以调用多媒体文件下载接口拉取数
据。
消息id，64位整型
5、地理位置消息
XML数据包示例：
68.
69.
70.
71.
72.
73.
74.
75.
76.
77.
78.
参数说明：
参数
ToUserName
FromUserName
CreateTime
MsgType
Location_X
Location_Y
Scale
Label
MsgId
开发者微信号
发送方帐号（一个OpenID）
消息创建时间 （整型）
location
地理位置维度
地理位置精度
地图缩放大小
地理位置信息
消息id，64位整型
描述
6、链接消息
XML数据包示例：
79.
- 22 -
80.
81.
82.
83.
84.
85.
86.
87.
88.
参数说明：
参数
ToUserName
FromUserName
CreateTime
MsgType
Title
Description
Url
MsgId
接收方微信号
发送方微信号，若为普通用户，则是一个OpenID
消息创建时间
消息类型，link
消息标题
消息描述
消息链接
消息id，64位整型
描述
三、接收事件推送
1、关注/取消关注事件
用户在关注与取消关注公众号事，微信会把这个事件推送到开发者填写的
URL。方便开发者给用户下发欢迎消息或者做帐号的解绑。
推送XML数据包示例：
89.
90.
91.
92.
93.
94.
95.
- 23 -
参数说明：
参数
ToUserName
FromUserName
CreateTime
MsgType
Event
开发者微信号
发送方帐号（一个OpenID）
消息创建时间 （整型）
消息类型，event
事件类型，subscribe(订阅)、unsubscribe(取消订阅)
描述
2、扫描带参数二维码事件
用户扫描带场景值二维码时，可能推送以下两种事件：
2.1如果用户还未关注公众号，则用户可以关注公众号，关注后微信会将带
场景值关注事件推送给开发者。
2.2、如果用户已经关注公众号，则微信会将带场景值扫描事件推送给开发
者。
2.1、 用户未关注时，进行关注后的事件推送
推送XML数据包示例：
96.
97.
98.
99.
100.
101.
102.
103.
参数说明：
参数
ToUserName
FromUserName
CreateTime
MsgType
Event
描述
开发者微信号
发送方帐号（一个OpenID）
消息创建时间 （整型）
消息类型，event
事件类型，subscribe
- 24 -
EventKey
Ticket
事件KEY值，qrscene_为前缀，后面为二维码的参数值
二维码的ticket，可用来换取二维码图片
2.2、 用户已关注时的事件推送
推送XML数据包示例：
104.
105.
106.
107.
108.
109.
110.
111.
112.
参数说明：
参数
ToUserName
FromUserName
CreateTime
MsgType
Event
EventKey
Ticket
开发者微信号
发送方帐号（一个OpenID）
消息创建时间 （整型）
消息类型，event
事件类型，scan
事件KEY值，是一个32位无符号整数
二维码的ticket，可用来换取二维码图片
描述
3、上报地理位置事件
用户同意上报地理位置后，每次进入公众号会话时，都会在进入时上报地理
位置，或在进入会话后每5秒上报一次地理位置，公众号可以在公众平台网站中
修改以上设置。上报地理位置时，微信会将上报地理位置事件推送到开发者填写
的URL。
推送XML数据包示例：
113.
114.
- 25 -
115.
116.
117.
118.
119.
120.
121.
122.
参数说明：
参数
ToUserName
FromUserName
CreateTime
MsgType
Event
Latitude
Longitude
Precision
开发者微信号
发送方帐号（一个OpenID）
消息创建时间 （整型）
消息类型，event
事件类型，LOCATION
地理位置纬度
地理位置经度
地理位置精度
描述
4、自定义菜单事件
用户点击自定义菜单后，如果菜单按钮设置为click类型，则微信会把此次
点击事件推送给开发者，注意view类型（跳转到URL）的菜单点击不会上报。
推送XML数据包示例：
123.
124.
125.
126.
127.
128.
129.
130.
参数说明：
参数 描述
- 26 -
ToUserName
FromUserName
CreateTime
MsgType
Event
EventKey
开发者微信号
发送方帐号（一个OpenID）
消息创建时间 （整型）
消息类型，event
事件类型，CLICK
事件KEY值，与自定义菜单接口中KEY值对应
四、接收语音识别结果
开通语音识别功能，用户每次发送语音给公众号时，微信会在推送的语音消
息XML数据包中，增加一个Recongnition字段。
注：由于客户端缓存，开发者开启或者关闭语音识别功能，对新关注者立刻
生效，对已关注用户需要24小时生效。开发者可以重新关注此帐号进行测试。
开启语音识别后的语音XML数据包如下：
131.
132.
133.
134.
135.
136.
137.
138.
139.
140.
参数说明：
参数
ToUserName
FromUserName
CreateTime
MsgType
MediaID
Format
描述
开发者微信号
发送方帐号（一个OpenID）
消息创建时间 （整型）
语音为voice
语音消息媒体id，可以调用多媒体文件下载接口拉取该媒体
语音格式：amr
- 27 -
Recognition
MsgID
语音识别结果，UTF8编码
消息id，64位整型
肆、发送消息
一、发送被动响应消息
对于每一个POST请求，开发者在响应包（Get）中返回特定XML结构，对
该消息进行响应（现支持回复文本、图片、图文、语音、视频、音乐）。请注意，
回复图片等多媒体消息时需要预先上传多媒体文件到微信服务器，只支持认证服
务号。
微信服务器在五秒内收不到响应会断掉连接，如果在调试中，发现用户无法
收到响应的消息，可以检查是否消息处理超时。 各消息类型需要的XML数据包
结构如下。
1、回复文本消息
141.
142.
143.
144.
145.
146.
147.
参数
ToUserName
CreateTime
MsgType
Content
是否必须
是
是
是
是
开发者微信号
消息创建时间 （整型）
text
回复的消息内容（换行：在content中能够换行，微信客户
端就支持换行显示）
描述
接收方帐号（收到的OpenID）
FromUserName
是
2、回复图片消息
148.
149.
150.
151.
- 28 -
152.
153.
154.
155.
156.
参数
ToUserName
CreateTime
MsgType
MediaId
是否必须
是
是
是
是
开发者微信号
消息创建时间 （整型）
image
通过上传多媒体文件，得到的id。
说明
接收方帐号（收到的OpenID）
FromUserName
是
3、回复语音消息
157.
158.
159.
160.
161.
162.
163.
164.
165.
参数
ToUserName
FromUserName
CreateTime
MsgType
MediaId
是否必须
是
是
是
是
是
开发者微信号
消息创建时间戳 （整型）
语音，voice
通过上传多媒体文件，得到的id
说明
接收方帐号（收到的OpenID）
4、回复视频消息
166.
<
xml>
167.
168.
169.
170.
171.
172.
173.
174.
175.
176.
- 29 -
参数
ToUserName
FromUserName
CreateTime
MsgType
MediaId
Title
Description
是否必须
是
是
是
是
是
否
否
开发者微信号
说明
接收方帐号（收到的OpenID）
消息创建时间 （整型）
video
通过上传多媒体文件，得到的id
视频消息的标题
视频消息的描述
5、回复音乐消息
177.
178.
179.
180.
181.
182.
183.
184.
185.
186.
187.
188.
189.
参数
ToUserName
FromUserName
CreateTime
MsgType
Title
Description
MusicURL
HQMusicUrl
ThumbMediaId
是否必须
是
是
是
是
否
否
否
否
是
开发者微信号
消息创建时间 （整型）
music
音乐标题
音乐描述
音乐链接
说明
接收方帐号（收到的OpenID）
高质量音乐链接，WIFI环境优先使用该链接播放音乐
缩略图的媒体id，通过上传多媒体文件，得到的id
6、回复图文消息
190.
191.
192.
193.
194.
195.
196.
- 30 -
197.
198.
199.
200.
201.
202.
203.
204.
205.
206.
207.
208.
209.
210.
参数
ToUserName
CreateTime
MsgType
ArticleCount
Articles
Title
Description
PicUrl
Url
是否必须
是
是
是
是
是
否
否
否
否
开发者微信号
消息创建时间 （整型）
news
说明
接收方帐号（收到的OpenID）
FromUserName
是
图文消息个数，限制为10条以内
多条图文消息信息，默认第一个item为大图,注意，如果图文
数超过10，则将会无响应
图文消息标题
图文消息描述
图片链接，支持JPG、PNG格式，较好的效果为大图360*200，
小图200*200
点击图文消息跳转链接
二、发送客服消息
当用户主动发消息给公众号的时候（包括发送信息、点击自定义菜单clike
事件、订阅事件、扫描二维码事件、支付成功事件、用户维权），微信将会
把消息数据推送给开发者，开发者在一段时间内（目前为24小时）可以调用
客服消息接口，通过POST一个JSON数据包来发送消息给普通用户，在24
小时内不限制发送次数。此接口主要用于客服等有人工消息处理环节的功能，
方便开发者为用户提供更加优质的服务。
接口调用请求说明
- 31 -
http请求方式: POST
/cgi-bin/message/custom/send?access_token=ACC
ESS_TOKEN
各消息类型所需的JSON数据包如下：
1、发送文本消息
211. {
212. "touser":"OPENID",
213. "msgtype":"text",
214. "text":
215. {
216. "content":"Hello World"
217. }
218. }
参数
access_token
touser
msgtype
content
是
是
是
是
是否必须
调用接口凭证
说明
普通用户openid
消息类型，text
文本消息内容
2、发送图片消息
219. {
220. "touser":"OPENID",
221. "msgtype":"image",
222. "image":
223. {
224. "media_id":"MEDIA_ID"
225. }
226. }
参数
access_token
touser
msgtype
media_id
是
是
是
是
是否必须
调用接口凭证
普通用户openid
说明
消息类型，image
发送的图片的媒体ID
3、发送语音消息
- 32 -
227. {
228. "touser":"OPENID",
229. "msgtype":"voice",
230. "voice":
231. {
232. "media_id":"MEDIA_ID"
233. }
234. }
参数
access_token
touser
msgtype
media_id
是
是
是
是
是否必须
调用接口凭证
普通用户openid
消息类型，voice
说明
发送的语音的媒体ID
4、发送视频消息
235. {
236. "touser":"OPENID",
237. "msgtype":"video",
238. "video":
239. {
240. "media_id":"MEDIA_ID",
241. "title":"TITLE",
242. "description":"DESCRIPTION"
243. }
244. }
参数
access_token
touser
msgtype
media_id
title
description
是
是
是
是
否
否
是否必须
调用接口凭证
普通用户openid
消息类型，video
说明
发送的视频的媒体ID
视频消息的标题
视频消息的描述
5、发送音乐消息
245. {
246. "touser":"OPENID",
247. "msgtype":"music",
248. "music":
249. {
250. "title":"MUSIC_TITLE",
251. "description":"MUSIC_DESCRIPTION",
252. "musicurl":"MUSIC_URL",
- 33 -
253. "hqmusicurl":"HQ_MUSIC_URL",
254. "thumb_media_id":"THUMB_MEDIA_ID"
255. }
256. }
参数
access_token
touser
msgtype
title
description
musicurl
hqmusicurl
thumb_media_id
是否必须
是
是
是
否
否
是
是
是
调用接口凭证
普通用户openid
消息类型，music
音乐标题
音乐描述
音乐链接
说明
高品质音乐链接，wifi环境优先使用该链接播放音乐
缩略图的媒体ID
6、发送图文消息
图文消息条数限制在10条以内，注意，如果图文数超过10，则将会无
响应。
257. {
258. "touser":"OPENID",
259. "msgtype":"news",
260. "news":{
261. "articles": [
262. {
263. "title":"Happy Day",
264. "description":"Is Really A Happy Day",
265. "url":"URL",
266. "picurl":"PIC_URL"
267. },
268. {
269. "title":"Happy Day",
270. "description":"Is Really A Happy Day",
271. "url":"URL",
272. "picurl":"PIC_URL"
273. }
274. ]
275. }
276. }
参数 是否必须
调用接口凭证
- 34 -
说明
access_token
是
touser
msgtype
title
description
url
picurl
是
是
否
否
否
否
普通用户openid
消息类型，news
标题
描述
点击后跳转的链接
图文消息的图片链接，支持JPG、PNG格式，较好的效果为大
图640*320，小图80*80
伍、用户管理
一、分组管理接口
开发者可以使用接口，对公众平台的分组进行查询、创建、修改操作，也可
以使用接口在需要时移动用户到某个分组。
1、创建分组
一个公众账号，最多支持创建500个分组。
接口调用请求说明
http请求方式: POST（请使用https协议）
/cgi-bin/groups/create?access_token=ACCESS_TOKEN
POST数据格式：json
POST数据例子：{"group":{"name":"test"}}
参数说明
参数
access_token
name
调用接口凭证
分组名字（30个字符以内）
说明
返回说明
正常时的返回JSON数据包示例：
277. {
278. "group": {
279. "id": 107,
280. "name": "test"
281. }
282. }
参数说明
- 35 -
参数
id
name
分组id，由微信分配
分组名字，UTF8编码
说明
错误时的JSON数据包示例（该示例为AppID无效错误）：
{"errcode":40013,"errmsg":"invalid appid"}
2、查询所有分组
接口调用请求说明
http请求方式: GET（请使用https协议）
/cgi-bin/groups/get?access_token=ACCESS_TOKEN
参数说明
参数
access_token
调用接口凭证
说明
返回说明
正常时的返回JSON数据包示例：
283. {
284. "groups": [
285. {
286. "id": 0,
287. "name": "未分组",
288. "count": 72596
289. },
290. {
291. "id": 1,
292. "name": "黑名单",
293. "count": 36
294. },
295. {
296. "id": 2,
297. "name": "星标组",
298. "count": 8
299. },
300. {
301. "id": 104,
302. "name": "华东媒",
303. "count": 4
304. },
- 36 -
305. {
306. "id": 106,
307. "name": "★不测试组★",
308. "count": 1
309. }
310. ]
311. }
参数说明
参数
groups
id
name
count
公众平台分组信息列表
分组id，由微信分配
分组名字，UTF8编码
分组内用户数量
说明
错误时的JSON数据包示例（该示例为AppID无效错误）：
{"errcode":40013,"errmsg":"invalid appid"}
3、查询用户所在分组
通过用户的OpenID查询其所在的GroupID。
接口调用请求说明
http请求方式: POST（请使用https协议）
/cgi-bin/groups/getid?access_token=ACCESS_TOKEN
POST数据格式：json
POST数据例子：{"openid":"od8XIjsmk6QdVTETa9jLtGWA6KBc"}
参数说明
参数
access_token
openid
调用接口凭证
用户的OpenID
说明
返回说明
正常时的返回JSON数据包示例：
312. {
313. "groupid": 102
314. }
参数说明
- 37 -
参数
groupid
用户所属的groupid
说明
错误时的JSON数据包示例（该示例为OpenID无效错误）：
{"errcode":40003,"errmsg":"invalid openid"}
4、修改分组名
接口调用请求说明
http请求方式: POST（请使用https协议）
/cgi-bin/groups/update?access_token=ACCESS_TOKEN
POST数据格式：json
POST数据例子：{"group":{"id":108,"name":"test2_modify2"}}
参数说明
参数
access_token
id
name
调用接口凭证
分组id，由微信分配
分组名字（30个字符以内）
说明
返回说明
正常时的返回JSON数据包示例：
{"errcode": 0, "errmsg": "ok"}
错误时的JSON数据包示例（该示例为AppID无效错误）：
{"errcode":40013,"errmsg":"invalid appid"}
5、移动用户分组
接口调用请求说明
http请求方式: POST（请使用https协议）
/cgi-bin/groups/members/update?access_token=ACCESS_TOK
EN
POST数据格式：json
POST数据例子：{"openid":"oDF3iYx0ro3_7jD4HFRDfrjdCM58","to_groupid":108}
- 38 -
参数说明
参数
access_token
openid
to_groupid
调用接口凭证
用户唯一标识符
分组id
说明
返回说明
正常时的返回JSON数据包示例：
{"errcode": 0, "errmsg": "ok"}
错误时的JSON数据包示例（该示例为AppID无效错误）：
{"errcode":40013,"errmsg":"invalid appid"}
二、获取用户基本信息
在关注者与公众号产生消息交互后，公众号可获得关注者的OpenID（加密
后的微信号，每个用户对每个公众号的OpenID是唯一的。对于不同公众号，同
一用户的openid不同）。公众号可通过本接口来根据OpenID获取用户基本信
息，包括昵称、头像、性别、所在城市、语言和关注时间。
获取用户基本信息
开发者可通过OpenID来获取用户基本信息。请使用https协议。
接口调用请求说明
http请求方式: GET
/cgi-bin/user/info?access_token=ACCESS_TOKEN&openid=OP
ENID
参数说明
参数
access_token
openid
是否必须
是
是
调用接口凭证
普通用户的标识，对当前公众号唯一
说明
返回说明
正常情况下，微信会返回下述JSON数据包给公众号：
- 39 -
315. {
316. "subscribe": 1,
317. "openid": "o6_bmjrPTlm6_2sgVt7hMZOPfL2M",
318. "nickname": "Band",
319. "sex": 1,
320. "language": "zh_CN",
321. "city": "广州",
322. "province": "广东",
323. "country": "中国",
324. "headimgurl":
"/mmopen/g3MonUZtNHkdmzicIlibx6iaFqAc56vxLSUfpb6n5WKSYVY0ChQKkia
JSgQ1dZuTOgvLLrhJbERQQ4eMsv84eavHiaiceqxibJxCfHe/0",
325. "subscribe_time": 1382694957
326. }
参数说明
参数
subscribe
openid
nickname
sex
city
country
province
language
headimgurl
说明
用户是否订阅该公众号标识，值为0时，代表此用户没有关注该公众号，
拉取不到其余信息。
用户的标识，对当前公众号唯一
用户的昵称
用户的性别，值为1时是男性，值为2时是女性，值为0时是未知
用户所在城市
用户所在国家
用户所在省份
用户的语言，简体中文为zh_CN
用户头像，最后一个数值代表正方形头像大小（有0、46、64、96、132
数值可选，0代表640*640正方形头像），用户没有头像时该项为空
subscribe_time
用户关注时间，为时间戳。如果用户曾多次关注，则取最后关注时间
错误时微信会返回错误码等信息，JSON数据包示例如下（该示例为AppID
无效错误）:
{"errcode":40013,"errmsg":"invalid appid"}
三、获取关注者列表
公众号可通过本接口来获取帐号的关注者列表，关注者列表由一串OpenID
（加密后的微信号，每个用户对每个公众号的OpenID是唯一的）组成。一次拉
取调用最多拉取10000个关注者的OpenID，可以通过多次拉取的方式来满足需
- 40 -
求。
接口调用请求说明
http请求方式: GET（请使用https协议）
/cgi-bin/user/get?access_token=ACCESS_TOKEN&next_openid
=NEXT_OPENID
参数
access_token
next_openid
是否必须
是
是
调用接口凭证
第一个拉取的OPENID，不填默认从头开始拉取
说明
正确时返回JSON数据包：
{"total":2,"count":2,"data":{"openid":["","OPENID1","OPENID2"]},"next_openid":"NEXT_OP
ENID"}
参数
total
count
data
next_openid
关注该公众账号的总用户数
拉取的OPENID个数，最大值为10000
列表数据，OPENID的列表
拉取列表的后一个用户的OPENID
说明
错误时返回JSON数据包（示例为无效AppID错误）：
{"errcode":40013,"errmsg":"invalid appid"}
附：关注者数量超过10000时
当公众号关注者数量超过10000时，可通过填写next_openid的值，从而多
次拉取列表的方式来满足需求。
具体而言，就是在调用接口时，将上一次调用得到的返回中的next_openid
值，作为下一次调用中的next_openid值。
示例如下：
327. 公众账号A拥有23000个关注的人，想通过拉取关注接口获取所有关注的人，那么分别请求url如
下：
328. /cgi-bin/user/get?access_token=ACCESS_TOKEN
329. 返回结果:
330. {
331. "total":23000,
- 41 -
332. "count":10000,
333. "data":{"
334. openid":[
335. "OPENID1",
336. "OPENID2",
337. ...,
338. "OPENID10000"
339. ]
340. },
341. "next_openid":"NEXT_OPENID1"
342. }
343. /cgi-bin/user/get?access_token=ACCESS_TOKEN&next_openid=NEXT_O
PENID1
344. 返回结果:
345. {
346. "total":23000,
347. "count":10000,
348. "data":{
349. "openid":[
350. "OPENID10001",
351. "OPENID10002",
352. ...,
353. "OPENID20000"
354. ]
355. },
356. "next_openid":"NEXT_OPENID2"
357. }
358. /cgi-bin/user/get?access_token=ACCESS_TOKEN&next_openid=NEXT_O
PENID2
359. 返回结果（关注者列表已返回完时，返回next_openid为空）:
360. {
361. "total":23000,
362. "count":3000,
363. "data":{"
364. "openid":[
365. "OPENID20001",
366. "OPENID20002",
367. ...,
368. "OPENID23000"
369. ]
370. },
371. "next_openid":" "
372. }
- 42 -
四、获取用户地理位置
开通了上报地理位置接口的公众号，用户在关注后进入公众号会话时，会弹
框让用户确认是否允许公众号使用其地理位置。弹框只在关注后出现一次，用户
以后可以在公众号详情页面进行操作。
获取用户地理位置
获取用户地理位置的方式有两种，一种是仅在进入会话时上报一次，一种是
进入会话后每隔5秒上报一次。公众号可以在公众平台网站中设置。
用户同意上报地理位置后，每次进入公众号会话时，都会在进入时上报地理
位置，或在进入会话后每5秒上报一次地理位置，上报地理位置以推送XML数
据包到开发者填写的URL来实现。
推送XML数据包示例：
373.
374.
375.
376.
377.
378.
379.
380.
381.
382.
参数说明：
参数
ToUserName
FromUserName
CreateTime
MsgType
Event
Latitude
Longitude
Precision
开发者微信号
发送方帐号（一个OpenID）
消息创建时间 （整型）
消息类型，event
事件类型，LOCATION
地理位置纬度
地理位置经度
地理位置精度
描述
五、网页授权获取用户基本信息
- 43 -
如果用户在微信中（Web微信除外）访问公众号的第三方网页，公众号开
发者可以通过此接口获取当前用户基本信息（包括昵称、性别、城市、国家）。
利用用户信息，可以实现体验优化、用户来源统计、帐号绑定、用户身份鉴权等
功能。请注意，“获取用户基本信息接口是在用户和公众号产生消息交互时，
才能根据用户OpenID获取用户基本信息，而网页授权的方式获取用户基本信
息，则无需消息交互，只是用户进入到公众号的网页，就可弹出请求用户授权
的界面，用户授权后，就可获得其基本信息（此过程甚至不需要用户已经关注
公众号。）”
本接口是通过OAuth2.0来完成网页授权的，是安全可靠的，关于OAuth2.0
的详细介绍，可以参考OAuth2.0协议标准。在微信公众号请求用户网页授权之
前，开发者需要先到公众平台网站的我的服务页中配置授权回调域名。请注意，
这里填写的域名不要加
关于配置授权回调域名的说明：
授权回调域名配置规范为全域名，比如需要网页授权的域名为：，配置以后
此域名下面的页面/ 、 / 都
可以进行OAuth2.0鉴权。但 、 、
无法进行OAuth2.0鉴权。
具体而言，网页授权流程分为三步：
A. 引导用户进入授权页面同意授权，获取code
B. 通过code换取网页授权access_token（与基础支持中的access_token不
同）
C. 如果需要，开发者可以刷新网页授权access_token，避免过期
D. 通过网页授权access_token和openid获取用户基本信息
第一步：用户同意授权，获取code
- 44 -
在确保微信公众账号拥有授权作用域（scope参数）的权限的前提下（服
务号获得高级接口后，默认带有scope参数中的snsapi_base和
snsapi_userinfo），引导关注者打开如下页面：
/connect/oauth2/authorize?appid=APPID&redirect_uri=REDI
RECT_URI&response_type=code&scope=SCOPE&state=STATE#wechat_redirect
若提示“该链接无法访问”，请检查参数是否填写错误，是否拥有scope参数对应的授权作
用域权限。
参考链接(请在微信客户端中打开此链接体验)
Scope为snsapi_base
/connect/oauth2/authorize?appid=wx520c15f417810387&re
direct_uri=http%3A%2F%%2Fphp%%3Fd%3D%26c%3Dwx
Adapter%26m%3DmobileDeal%26showwxpaytitle%3D1%26vb2ctag%3D4_2030_5_1194
_60&response_type=code&scope=snsapi_base&state=123#wechat_redirect
Scope为snsapi_userinfo
/connect/oauth2/authorize?appid=wxf0e81c3bee622d60&re
direct_uri=http%3A%2F%%2Foauth_&response_t
ype=code&scope=snsapi_userinfo&state=STATE#wechat_redirect
参数说明
参数
appid
redirect_uri
response_type
是否必须
是
是
是
公众号的唯一标识
授权后重定向的回调链接地址
返回类型，请填写code
应用授权作用域，snsapi_base （不弹出授权页面，直接
跳转，只能获取用户openid），snsapi_userinfo （弹出
授权页面，可通过openid拿到昵称、性别、所在地。并
且，即使在未关注的情况下，只要用户授权，也能获取其
信息）
重定向后会带上state参数，开发者可以填写任意参数值
直接在微信打开链接，可以不填此参数。做页面302重定
向时候，必须带此参数
说明
scope
是
state
否
#wechat_redirect
否
下图为scope等于snsapi_userinfo时的授权页面：
- 45 -
用户同意授权后
如果用户同意授权，页面将跳转至
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。
如果网页授权的作用域为snsapi_base，则本步骤中获取到网页授权
- 46 -
access_token的同时，也获取到了openid，snsapi_base式的网页授权流程即
到此为止。
请求方法
获取code后，请求以下链接获取access_token：
/sns/oauth2/access_token?appid=APPID&secret=SECRET&cod
e=CODE&grant_type=authorization_code
参数说明
参数
appid
secret
code
grant_type
是
是
是
是
是否必须
公众号的唯一标识
公众号的appsecret
填写第一步获取的code参数
填写为authorization_code
说明
返回说明
正确时返回的JSON数据包如下：
383. {
384. "access_token":"ACCESS_TOKEN",
385. "expires_in":7200,
386. "refresh_token":"REFRESH_TOKEN",
387. "openid":"OPENID",
388. "scope":"SCOPE"
389. }
参数
access_token
expires_in
描述
网页授权接口调用凭证,注意：此access_token与基础支持的access_token
不同
access_token接口调用凭证超时时间，单位（秒）
用户唯一标识，请注意，在未关注公众号时，用户访问公众号的网页，也会
产生一个用户和公众号唯一的OpenID
用户授权的作用域，使用逗号（,）分隔
refresh_token
用户刷新access_token
openid
scope
错误时微信会返回JSON数据包如下（示例为Code无效错误）:
{"errcode":40029,"errmsg":"invalid code"}
第三步：刷新access_token（如果需要）
- 47 -
由于access_token拥有较短的有效期，当access_token超时后，可以使
用refresh_token进行刷新，refresh_token拥有较长的有效期（7天、30天、
60天、90天），当refresh_token失效的后，需要用户重新授权。
请求方法
获取第二步的refresh_token后，请求以下链接获取access_token：
/sns/oauth2/refresh_token?appid=APPID&grant_type=refresh_
token&refresh_token=REFRESH_TOKEN
参数
appid
grant_type
refresh_token
是否必须
是
是
是
公众号的唯一标识
填写为refresh_token
填写通过access_token获取到的refresh_token参数
说明
返回说明
正确时返回的JSON数据包如下：
390. {
391. "access_token":"ACCESS_TOKEN",
392. "expires_in":7200,
393. "refresh_token":"REFRESH_TOKEN",
394. "openid":"OPENID",
395. "scope":"SCOPE"
396. }
参数
access_token
expires_in
openid
scope
描述
网页授权接口调用凭证,注意：此access_token与基础支持的access_token
不同
access_token接口调用凭证超时时间，单位（秒）
用户唯一标识
用户授权的作用域，使用逗号（,）分隔
refresh_token
用户刷新access_token
错误时微信会返回JSON数据包如下（示例为Code无效错误）:
{"errcode":40029,"errmsg":"invalid code"}
第四步：拉取用户信息(需scope为 snsapi_userinfo)
- 48 -
如果网页授权作用域为snsapi_userinfo，则此时开发者可以通过
access_token和openid拉取用户信息了。
请求方法
http：GET（请使用https协议）
/sns/userinfo?access_token=ACCESS_TOKEN&openid=OPENID
参数说明
参数
access_token
openid
描述
网页授权接口调用凭证,注意：此access_token与基础支持的access_token
不同
用户的唯一标识
返回说明
正确时返回的JSON数据包如下：
397. {
398. "openid":" OPENID",
399. " nickname": NICKNAME,
400. "sex":"1",
401. "province":"PROVINCE"
402. "city":"CITY",
403. "country":"COUNTRY",
404. "headimgurl":
"/mmopen/g3MonUZtNHkdmzicIlibx6iaFqAc56vxLSUfpb6n5WKSYVY0ChQKkia
JSgQ1dZuTOgvLLrhJbERQQ4eMsv84eavHiaiceqxibJxCfHe/46",
405.
406.
407.
409. }
"privilege":[
"PRIVILEGE1"
"PRIVILEGE2"
408. ]
参数
openid
nickname
sex
province
city
country
headimgurl
用户的唯一标识
用户昵称
描述
用户的性别，值为1时是男性，值为2时是女性，值为0时是未知
用户个人资料填写的省份
普通用户个人资料填写的城市
国家，如中国为CN
用户头像，最后一个数值代表正方形头像大小（有0、46、64、96、132
数值可选，0代表640*640正方形头像），用户没有头像时该项为空
- 49 -
privilege
用户特权信息，json 数组，如微信沃卡用户为（chinaunicom）
错误时微信会返回JSON数据包如下（示例为openid无效）:
{"errcode":40003,"errmsg":" invalid openid "}
六、网页获取用户网络状态（JS接口）
为了方便开发者根据用户的网络状态来提供不同质量的服务，公众号可
以在公众号内部的网页中使用JavaScript代码调用来获取网络状态。
接口调用代码（JavaScript）
410. ('getNetworkType',{},
411.
412.
413.
});
function(e){
(_msg);
返回说明
获取用户网络状态的返回值如下：
network_type:wifi wifi网络
network_type:edge 非wifi,包含3G/2G
network_type:fail 网络断开连接
陆、自定义菜单
一、自定义菜单创建接口
自定义菜单能够帮助公众号丰富界面，让用户更好更快地理解公众号的
功能。开启自定义菜单后，公众号界面如图所示：
- 50 -
目前自定义菜单最多包括3个一级菜单，每个一级菜单最多包含5个二
级菜单。一级菜单最多4个汉字，二级菜单最多7个汉字，多出来的部分将
会以“...”代替。请注意，创建自定义菜单后，由于微信客户端缓存，需要
24小时微信客户端才会展现出来。建议测试时可以尝试取消关注公众账号后
再次关注，则可以看到创建后的效果。
目前自定义菜单接口可实现两种类型按钮，如下：
click：
用户点击click类型按钮后，微信服务器会通过消息接口推送消息类型为event 的结构给
开发者（参考消息接口指南），并且带上按钮中开发者填写的key值，开发者可以通过自
定义的key值与用户进行交互；
view：
- 51 -
用户点击view类型按钮后，微信客户端将会打开开发者在按钮中填写的url值 （即网页
链接），达到打开网页的目的，建议与网页授权获取用户基本信息接口结合，获得用户的
登入个人信息。
接口调用请求说明
http请求方式：POST（请使用https协议）
/cgi-bin/menu/create?access_token=ACCESS_TOK
EN
请求示例
414. {
415. "button":[
416. {
417. "type":"click",
418. "name":"今日歌曲",
419. "key":"V1001_TODAY_MUSIC"
420. },
421. {
422. "type":"click",
423. "name":"歌手简介",
424. "key":"V1001_TODAY_SINGER"
425. },
426. {
427. "name":"菜单",
428. "sub_button":[
429. {
430. "type":"view",
431. "name":"搜索",
432. "url":"/"
433. },
434. {
435. "type":"view",
436. "name":"视频",
437. "url":"/"
438. },
439. {
440. "type":"click",
441. "name":"赞一下我们",
442. "key":"V1001_GOOD"
443. }]
- 52 -
444. }]
445. }
参数说明
参数
button
type
name
key
url
是否必须
是
是
是
click类型必须
view类型必须
说明
一级菜单数组，个数应为1~3个
二级菜单数组，个数应为1~5个
菜单的响应动作类型，目前有click、view两种类型
菜单标题，不超过16个字节，子菜单不超过40个字节
菜单KEY值，用于消息接口推送，不超过128字节
网页链接，用户点击菜单可打开链接，不超过256字节
sub_button
否
返回结果
正确时的返回JSON数据包如下：
{"errcode":0,"errmsg":"ok"}
错误时的返回JSON数据包如下（示例为无效菜单名长度）：
{"errcode":40018,"errmsg":"invalid button name size"}
二、自定义菜单查询接口
使用接口创建自定义菜单后，开发者还可使用接口查询自定义菜单的结
构。
请求说明
http请求方式：GET
/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":"/","sub_button":[]},{"type":"view","name":"视频
- 53 -
","url":"/","sub_button":[]},{"type":"click","name":"赞一下我们
","key":"V1001_GOOD","sub_button":[]}]}]}}
三、自定义菜单删除接口
使用接口创建自定义菜单后，开发者还可使用接口删除当前使用的自定
义菜单。
请求说明
http请求方式：GET
/cgi-bin/menu/delete?access_token=ACCESS_TOKEN
返回说明
对应创建接口，正确的Json返回结果:
{"errcode":0,"errmsg":"ok"}
四、自定义菜单事件推送
用户点击自定义菜单后，如果菜单按钮设置为click类型，则微信会把此
次点击事件推送给开发者，注意view类型（跳转到URL）的菜单点击不会上
报。
推送XML数据包示例：
446.
447.
448.
449.
450.
451.
452.
453.
参数说明：
参数
ToUserName
FromUserName
CreateTime
MsgType
描述
开发者微信号
发送方帐号（一个OpenID）
消息创建时间 （整型）
消息类型，event
- 54 -
Event
EventKey
事件类型，CLICK
事件KEY值，与自定义菜单接口中KEY值对应
柒、推广支持
一、生成带参数的二维码
为了满足用户渠道推广分析的需要，公众平台提供了生成带参数二维码
的接口。使用该接口可以获得多个带不同场景值的二维码，用户扫描后，公
众号可以接收到事件推送。
目前有2种类型的二维码，分别是临时二维码和永久二维码，前者有过
期时间，最大为1800秒，但能够生成较多数量，后者无过期时间，数量较少
（目前参数只支持1--1000）。两种二维码分别适用于帐号绑定、用户来源统
计等场景。
用户扫描带场景值二维码时，可能推送以下两种事件：
A. 如果用户还未关注公众号，则用户可以关注公众号，关注后微信会
将带场景值关注事件推送给开发者。
B. 如果用户已经关注公众号，在用户扫描后会自动进入会话，微信也
会将带场景值扫描事件推送给开发者。
获取带参数的二维码的过程包括两步，首先创建二维码ticket，然后凭
借ticket到指定URL换取二维码。
二、创建二维码ticket
每次创建二维码ticket需要提供一个开发者自行设定的参数（scene_id），
分别介绍临时二维码和永久二维码的创建二维码ticket过程。
临时二维码请求说明
http请求方式: POST
URL: /cgi-bin/qrcode/create?access_token=TOKEN
POST数据格式：json
- 55 -
POST数据例子：{"expire_seconds": 1800, "action_name": "QR_SCENE", "action_info":
{"scene": {"scene_id": 123}}}
永久二维码请求说明
http请求方式: POST
URL: /cgi-bin/qrcode/create?access_token=TOKEN
POST数据格式：json
POST数据例子：{"action_name": "QR_LIMIT_SCENE", "action_info": {"scene": {"scene_id":
123}}}
参数说明
参数
action_name
action_info
scene_id
说明
二维码类型，QR_SCENE为临时,QR_LIMIT_SCENE为永久
二维码详细信息
场景值ID，临时二维码时为32位非0整型，永久二维码时最大值为1000
（目前参数只支持1--1000）
expire_seconds
该二维码有效时间，以秒为单位。 最大不超过1800。
返回说明
正确的Json返回结果:
{"ticket":"gQG28DoAAAAAAAAAASxodHRwOi8vd2VpeGluLnFxLmNvbS9xL0FuWC1DNm
ZuVEhvMVp4NDNMRnNRAAIEesLvUQMECAcAAA==","expire_seconds":1800}
参数
ticket
说明
获取的二维码ticket，凭借此ticket可以在有效时间内换取二维码。
expire_seconds
二维码的有效时间，以秒为单位。最大不超过1800。
错误的Json返回示例:
{"errcode":40013,"errmsg":"invalid appid"}
三、通过ticket换取二维码
获取二维码ticket后，开发者可用ticket换取二维码图片。请注意，本接
口无须登录态即可调用。
请求说明
HTTP GET请求（请使用https协议）
- 56 -
/cgi-bin/showqrcode?ticket=TICKET
提醒：TICKET记得进行UrlEncode
返回说明
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。
捌、Winxin JS接口
一、隐藏微信中网页右上角按钮
公众号在有需要时（如不需要用户分享某个页面），可在网页中通过
JavaScript代码隐藏网页右上角按钮。
- 57 -
接口调用代码（JavaScript）
454. ntListener('WeixinJSBridgeReady', function onBridgeReady() {
455. ('hideOptionMenu');
456. });
返回说明
隐藏底部导航栏没有返回值。（需要显示请把hideOptionMenu换成
showOptionMenu）
二、隐藏微信中网页底部导航栏
公众号在有需要时（如认为用户在该页面不会用到浏览器前进后退功能），
可在网页中通过JavaScript代码隐藏网页底部导航栏。
- 58 -
接口调用代码（JavaScript）
457. ntListener('WeixinJSBridgeReady', function onBridgeReady() {
458. ('hideToolbar');
459. });
返回说明
隐藏底部导航栏没有返回值。（需要显示顶部导航栏，请把hideToolbar
换成showToolbar）
三、网页获取用户网络状态
为了方便开发者根据用户的网络状态来提供不同质量的服务，公众号可以
在公众号内部的网页中使用JavaScript代码调用来获取网络状态。
接口调用代码（JavaScript）
- 59 -
460. ('getNetworkType',{},
461. function(e){
462. (_msg);
463. });
返回说明
获取用户网络状态的返回值如下：
network_type:wifi wifi网络
network_type:edge 非wifi,包含3G/2G
network_type:fail 网络断开连接
network_type:wwan（2g或者3g）
- 60 -
发布评论