微信公众账号高级接口使用小结
2013年6月份开始，就陆陆续续的研究了一下微信公众账号的使用，整理了一篇《关于微信公众平台的调研说明》的文档。文档从微信公众账号的注册、设置，到微信公众账号平台管理的各个部分，都进行了介绍(微信升级之后，现在微信公众账号平台的界面可能和文档中有所不同，但基本上通过这个文档，也知道怎么去使用)。2013年11月份，对微信公众账号进行认证，另外得到了9个开放的接口，现将9个接口应用过程进行小结一下，文档中的内容大部分来自于官方资料，另外加上了一些我个人应用过程中的一些理解，如有不正确的地方，欢迎大家指出。
1.语音识别
用户给您的微信公众账号发送语音消息，微信服务器会先对语音消息进行识别，然后将识别出的文本内容和语音发送给您的微信公众账号的后台服务器。
发送方不带语音识别功能的XML如下所示：
<xml> <ToUserName><![CDATA[toUser]]></ToUserName> <FromUserName><![CDATA[fromUser]]></FromUserName> <CreateTime>1357290913</CreateTime> <MsgType><![CDATA[voice]]></MsgType> <MediaId><![CDATA[media_id]]></MediaId> <Format><![CDATA[Format]]></Format> <MsgId>1234567890123456</MsgId> </xml>
发送方带语音识别功能的XML如下所示：
<xml> <ToUserName><![CDATA[toUser]]></ToUserName> <FromUserName><![CDATA[fromUser]]></FromUserName> <CreateTime>1357290913</CreateTime> <MsgType><![CDATA[voice]]></MsgType> <MediaId><![CDATA[media_id]]></MediaId> <Format><![CDATA[Format]]></Format> <Recognition><![CDATA[腾讯微信团队]]></Recognition> <MsgId>1234567890123456</MsgId> </xml>
从上面可以看出，微信服务器在推送的语音消息XML数据包中，增加了一个Recongnition字段，该字段的内容是语音识别出的文本内容。
【参数说明】：
|
【注】：语音识别功能可以在我的服务页面的高级接口栏目，通过开关来控制开启和关闭。如下图所示：
2.客服接口
当用户主动发消息给您的微信公众号的时候（包括发送信息、点击自定义菜单、关注等），微信服务器将会把消息数据推送给开发者，开发者在一段时间内（目前为24小时）可以调用客服消息接口，通过POST一个JSON数据包来发送消息（现支持文本、图片、图文、语音、视频、音乐）给普通用户，在24小时内不限制发送次数。此接口主要用于客服等有人工消息处理环节的功能，方便开发者为用户提供更加优质的服务。
与之相对应的是非认证账号的“发送被动响应消息”接口，“发送被动响应消息”接口有一个缺陷就是：微信服务器在五秒内收不到响应会断掉连接。也就是说，微信服务器只保持5秒的连接，如果五秒没有回复消息，那么发起该会话请求的用户就会收不到回复了。
3.OAuth2.0网页授权
如果用户在微信中（Web微信除外）访问公众号的第三方网页，公众号开发者可以通过此接口获取当前用户基本信息（包括昵称、性别、城市、国家）。利用用户信息，可以实现体验优化、用户来源统计、帐号绑定、用户身份鉴权等功能。【注意】：“获取用户基本信息接口(后续介绍)是在用户和公众号产生消息交互时，才能根据用户OpenID获取用户基本信息，而网页授权的方式获取用户基本信息，则无需消息交互，只是用户进入到公众号的网页，就可弹出请求用户授权的界面，用户授权后，就可获得其基本信息（此过程甚至不需要用户已经关注公众号。）”
【注意】：在微信公众号请求用户网页授权之前，开发者需要先到公众平台网站的我的服务页中配置授权回调域名。请注意，这里填写的域名不要加http://，如下所示(这里填写的是演示地址)：
具体而言，网页授权流程分为四步：
第一步：用户同意授权，获取code。参考链接形式：https://open.weixin.qq.com/connect/oauth2/authorize?appid=wx909310a8acfdc259&redirect_uri=http%3A%2F%2Fwww.baidu.com&response_type=code&scope=snsapi_userinfo&state=STATE#wechat_redirect (注意：appid应该输入您的微信公众账号的appid，该链接不可以在浏览器中打开。实际使用的时候，需要把redirect_uri修改为您要跳转的地址，目前我写的是http://www.baidu.com，修改的时候，同样要修改上面图片所示设置的授权回调页面域名)。在微信中打开这个授权链接，会进入到如下图所示页面：
单击取消或允许按钮，都会进入到上面设置的回调页面。如果用户同意授权，页面将跳转至 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： https://api.weixin.qq.com/sns/oauth2/access_token?appid=APPID&secret=SECRET&code=CODE&grant_type=authorization_code
【注意】：这里通过code换取的网页授权access_token，与基础支持中的access_token不同。如果网页授权的作用域为snsapi_base，则本步骤中获取到网页授权access_token的同时，也获取到了openid，snsapi_base式的网页授权流程即到此为止。
【参数说明】：
|
【返回说明】：
正确时返回的JSON数据包如下：
{ "access_token":"ACCESS_TOKEN", "expires_in":7200, "refresh_token":"REFRESH_TOKEN", "openid":"OPENID", "scope":"SCOPE" }
【参数说明】：
|
错误时微信会返回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.weixin.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" }
【参数说明】：
|
错误时微信会返回JSON数据包如下（示例为Code无效错误）:
{"errcode":40029,"errmsg":"invalid code"}
第四步：拉取用户信息(需scope为 snsapi_userinfo)。如果网页授权作用域为snsapi_userinfo，则此时开发者可以通过access_token和openid拉取用户信息了。
【请求方法】：
http：GET（请使用https协议）
https://api.weixin.qq.com/sns/userinfo?access_token=ACCESS_TOKEN&openid=OPENID
【参数说明】：
|
【返回说明】：
正确时返回的JSON数据包如下：
{ "openid":" OPENID", " nickname": NICKNAME, "sex":"1", "province":"PROVINCE" "city":"CITY", "country":"COUNTRY", "headimgurl": "http://wx.qlogo.cn/mmopen/g3MonUZtNHkdmzicIlibx6iaFqAc56vxLSUfpb6n5WKSYVY0ChQKkiaJSgQ1dZuTOgvLLrhJbERQQ4eMsv84eavHiaiceqxibJxCfHe/46", "privilege":[ "PRIVILEGE1" "PRIVILEGE2" ] }
【参数说明】：
|
错误时微信会返回JSON数据包如下（示例为openid无效）:
{"errcode":40003,"errmsg":" invalid openid "}
4. 生成带参数二维码
使用该接口可以获得多个带不同场景值的二维码，用户扫描后，公众号可以接收到事件推送(说的简单点，意思就是可以通过这个接口，产生一个二维码，然后用户可以通过扫描这个二维码，进入到公众账号信息页面(未关注公众账号的用户)或公众账号的会话页面(关注了公众账号的用户))。
目前有2种类型的二维码，分别是临时二维码和永久二维码，前者有过期时间，最大为1800秒，但能够生成较多数量，后者无过期时间，数量较少（目前参数只支持1--1000）。两种二维码分别适用于帐号绑定、用户来源统计等场景。
用户扫描带场景值二维码时，可能推送以下两种事件：
- 如果用户还未关注公众号，则用户可以关注公众号，关注后微信会将带场景值关注事件推送给开发者。
- 如果用户已经关注公众号，在用户扫描后会自动进入会话，微信也会将带场景值扫描事件推送给开发者。
获取带参数的二维码的过程包括两步，首先创建二维码ticket，然后凭借ticket到指定URL换取二维码。
第一步：创建二维码ticket。
【请求说明】：
http请求方式: POST URL: https://api.weixin.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}}}
【参数说明】：
|
【返回说明】：
正确的Json返回结果:
{"ticket":"gQG28DoAAAAAAAAAASxodHRwOi8vd2VpeGluLnFxLmNvbS9xL0FuWC1DNmZuVEhvMVp4NDNMRnNRAAIEesLvUQMECAcAAA==","expire_seconds":1800}
【参数说明】：
|
错误的Json返回示例:
{"errcode":40013,"errmsg":"invalid appid"}
第二步：通过ticket换取二维码。
【请求说明】： HTTP GET请求（请使用https协议） https://mp.weixin.qq.com/cgi-bin/showqrcode?ticket=TICKET
【返回说明】：
ticket正确情况下，http 返回码是200，是一张图片，可以直接展示或者下载。如下图所示：
错误情况下（如ticket非法）返回HTTP错误码404。
5. 获取用户地理位置
【注意】：要使用获取用户地理位置功能，首先要在我的服务----高级接口中，开启获取用户地理位置按钮，单击按钮，会弹出如下所示页面：
可以根据需要自行选择获取地理位置的模式。
开通了上报地理位置接口的公众号，用户在关注后进入公众号会话时，会弹框让用户确认是否允许公众号使用其地理位置(如下图左所示)。弹框只在关注后出现一次，用户以后可以在公众号详情页面进行操作(如下图右所示)。
用户同意上报地理位置后，每次进入公众号会话时，都会在进入时上报地理位置，或在进入会话后每5秒上报一次地理位置，上报地理位置以推送XML数据包到开发者填写的URL来实现。
推送XML数据包示例：
<xml> <ToUserName><![CDATA[toUser]]></ToUserName> <FromUserName><![CDATA[fromUser]]></FromUserName> <CreateTime>123456789</CreateTime> <MsgType><![CDATA[event]]></MsgType> <Event><![CDATA[LOCATION]]></Event> <Latitude>23.137466</Latitude> <Longitude>113.352425</Longitude> <Precision>119.385040</Precision> </xml>
【参数说明】：
|
6. 获取用户基本信息
在关注者与公众号产生消息交互后，公众号可获得关注者的OpenID（加密后的微信号，每个用户对每个公众号的OpenID是唯一的。对于不同公众号，同一用户的openid不同）。公众号可通过本接口来根据OpenID获取用户基本信息，包括昵称、头像、性别、所在城市、语言和关注时间。
【接口调用请求说明】：
http请求方式: GET https://api.weixin.qq.com/cgi-bin/user/info?access_token=ACCESS_TOKEN&openid=OPENID
【参数说明】：
|
【返回说明】：
正常情况下，微信会返回下述JSON数据包给公众号：
{
"subscribe": 1,
"openid": "o6_bmjrPTlm6_2sgVt7hMZOPfL2M",
"nickname": "Band",
"sex": 1,
"language": "zh_CN",
"city": "广州",
"province": "广东",
"country": "中国",
"headimgurl": "http://wx.qlogo.cn/mmopen/g3MonUZtNHkdmzicIlibx6iaFqAc56vxLSUfpb6n5WKSYVY0ChQKkiaJSgQ1dZuTOgvLLrhJbERQQ4eMsv84eavHiaiceqxibJxCfHe/0",
"subscribe_time": 1382694957
}
【参数说明】：
|
错误时微信会返回错误码等信息，JSON数据包示例如下（该示例为AppID无效错误）:
{"errcode":40013,"errmsg":"invalid appid"}
7. 获取关注者列表
公众号可通过本接口来获取帐号的关注者列表，关注者列表由一串OpenID（加密后的微信号，每个用户对每个公众号的OpenID是唯一的）组成。一次拉取调用最多拉取10000个关注者的OpenID，可以通过多次拉取的方式来满足需求。
【接口调用请求说明】：
http请求方式: GET（请使用https协议） https://api.weixin.qq.com/cgi-bin/user/get?access_token=ACCESS_TOKEN&next_openid=NEXT_OPENID
【参数说明】：
|
【返回说明】：
正确时返回JSON数据包：
{"total":2,"count":2,"data":{"openid":["","OPENID1","OPENID2"]},"next_openid":"NEXT_OPENID"}
【参数说明】：
|
错误时返回JSON数据包（示例为无效AppID错误）：
{"errcode":40013,"errmsg":"invalid appid"}
【附】：当公众号关注者数量超过10000时，可通过填写next_openid的值，从而多次拉取列表的方式来满足需求。
具体而言，就是在调用接口时，将上一次调用得到的返回中的next_openid值，作为下一次调用中的next_openid值。
8. 用户分组接口
开发者可以使用接口，对公众平台的分组进行查询、创建、修改操作，也可以使用接口在需要时移动用户到某个分组。
8.1查询分组
【接口调用请求说明】：
http请求方式: GET（请使用https协议） https://api.weixin.qq.com/cgi-bin/groups/get?access_token=ACCESS_TOKEN
【参数说明】：
|
【返回说明】：
正常时的返回JSON数据包示例：
{
"groups": [
{
"id": 0,
"name": "未分组",
"count": 72596
},
{
"id": 1,
"name": "黑名单",
"count": 36
}
]
}
【参数说明】：
|
8.2创建分组
一个公众账号，最多支持创建500个分组。
【 接口调用请求说明】：
http请求方式: POST（请使用https协议）
https://api.weixin.qq.com/cgi-bin/groups/create?access_token=ACCESS_TOKEN
POST数据格式：json
POST数据例子：{"group":{"name":"test"}}
【参数说明】：
|
【返回说明】：
正常时的返回JSON数据包示例：
{
"group": {
"id": 107,
"name": "test"
}
}
【参数说明】：
|
错误时的JSON数据包示例（该示例为AppID无效错误）：
{"errcode":40013,"errmsg":"invalid appid"}
8.3修改分组名
【接口调用请求说明】：
http请求方式: POST（请使用https协议）
https://api.weixin.qq.com/cgi-bin/groups/update?access_token=ACCESS_TOKEN
POST数据格式：json
POST数据例子：{"group":{"id":108,"name":"test2_modify2"}}
【参数说明】：
|
【返回说明】：
正常时的返回JSON数据包示例：
{"errcode": 0, "errmsg": "ok"}
错误时的JSON数据包示例（该示例为AppID无效错误）：
{"errcode":40013,"errmsg":"invalid appid"}
8.4移动用户分组
【接口调用请求说明】：
http请求方式: POST（请使用https协议）
https://api.weixin.qq.com/cgi-bin/groups/members/update?access_token=ACCESS_TOKEN
POST数据格式：json
POST数据例子：{"openid":"oDF3iYx0ro3_7jD4HFRDfrjdCM58","to_groupid":108}
【参数说明】：
|
【返回说明 】：
正常时的返回JSON数据包示例：
{"errcode": 0, "errmsg": "ok"}
错误时的JSON数据包示例（该示例为AppID无效错误）：
{"errcode":40013,"errmsg":"invalid appid"}
9. 上传下载多媒体文件
公众号在使用接口时，对多媒体文件、多媒体消息的获取和调用等操作，是通过media_id来进行的。通过本接口，公众号可以上传或下载多媒体文件。
【注意】：每个多媒体文件（media_id）会在上传、用户发送到微信服务器3天后自动删除，以节省服务器资源。
9.1上传多媒体文件
公众号可调用本接口来上传图片、语音、视频等文件到微信服务器，上传后服务器会返回对应的media_id，公众号此后可根据该media_id来获取多媒体。请注意，media_id是可复用的，调用该接口需http协议。
【接口调用请求说明】：
http请求方式: POST/FORM http://file.api.weixin.qq.com/cgi-bin/media/upload?access_token=ACCESS_TOKEN&type=TYPE 调用示例（使用curl命令，用FORM表单方式上传一个多媒体文件）： curl -F media=@test.jpg "http://file.api.weixin.qq.com/cgi-bin/media/upload?access_token=ACCESS_TOKEN&type=TYPE"
【参数说明】：
|
【返回说明】：
正确情况下的返回JSON数据包结果如下：
{"type":"TYPE","media_id":"MEDIA_ID","created_at":123456789}
【参数说明】：
|
错误情况下的返回JSON数据包示例如下（示例为无效媒体类型错误）：
{"errcode":40004,"errmsg":"invalid media type"}
【注意事项】
1).上传的多媒体文件有格式和大小限制，如下：
- 图片（image）: 128K，支持JPG格式
- 语音（voice）：256K，播放长度不超过60s，支持AMR格式
- 视频（video）：1MB，支持MP4格式
- 缩略图（thumb）：64KB，支持JPG格式
2).媒体文件在后台保存时间为3天，即3天后media_id失效。
9.2下载多媒体文件
公众号可调用本接口来获取多媒体文件。请注意，调用该接口需http协议。
【接口调用请求说明】：
http请求方式: GET http://file.api.weixin.qq.com/cgi-bin/media/get?access_token=ACCESS_TOKEN&media_id=MEDIA_ID 请求示例（示例为通过curl命令获取多媒体文件） curl -I -G "http://file.api.weixin.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 "http://file.api.weixin.qq.com/cgi-bin/media/get?access_token=ACCESS_TOKEN&media_id=MEDIA_ID"
错误情况下的返回JSON数据包示例如下（示例为无效媒体ID错误）:
{"errcode":40007,"errmsg":"invalid media_id"}
