微信公众平台开发者文档

1 微信公众平台开发者文档 文档内容 截至日期： 2013 目 录 零、首页 . - 1 - 一、公众平台开发接口介绍 . - 1 - 二、典型案例介绍 . - 1 - 壹、新手接入 . - 4 - 一、接入指南 . - 4 - 二、典型案例介绍 . - 6 - 三、开发者规范 . - 9 - 贰、基础支持 . - 10 - 一、获取 . - 10 - 二、全局返回码说明 . - 11 - 三、接口频率限制说明 . - 14 - 四、上传下载多媒体文件 . - 15 - 叁、接收消息 . - 18 - 一、验证消息真实性 . - 18 - 二、接收普通消息 . - 19 - 三、接收事件推送 . - 23 - 四、接收语音识别结果 . - 27 - 肆、发送消息 . - 28 - 一、发送被动响应消息 . - 28 - 二、发送客服消息 . - 31 - 伍、用户管理 . - 35 - 3 一、分组管理接口 . - 35 - 二、获取用户基本信息 . - 39 - 三、获取关注者列表 . - 40 - 四、获取用户地理位置 . - 43 - 五、网页授权获取用户基本信息 . - 43 - 六、网页获取用户网络状态（ . - 50 - 陆、自定义菜单 . - 50 - 一、自定义菜单创建接口 . - 50 - 二、自定义菜单查询接口 . - 53 - 三、自定义菜单删除接口 . - 54 - 四、自定义菜单事件推送 . - 54 - 柒、推广支持 . - 55 - 一、生成带参数的二维码 . - 55 - 二、创建二维码 . - 55 - 三、通过 . - 56 - 捌、 . - 57 - 一、隐藏微信中网页右上角按钮 . - 57 - 二、隐藏微信中网页底部导航栏 . - 58 - 三、网页获取用户网络状态 . - 59 - - 1 - 零、 首页 一、 公众平台开发接口介绍 公众平台是为微信用户提供服务的平台，而公众平台开发接口则是提供服务的基础，开发者在公众平台网站中创建公众号、获取接口权限后，可以通过阅读本接口文档来帮助开发。 公众平台开发接口提供与用户进行消息交互、自定义菜单交互的能力。对于成功接入公众平台开发接口的公众账号，当用户发消息给公众号，微信公众平台服务器会使用 求对接入的网址进行消息推送，第三方服务器可通过响应包回复特定结构，从而达到回复消息的目的。 二、 典型案例介绍 值得借鉴的公众帐号主要是服务号，试列举并介绍如下： 招商银行信用卡中心 - 2 - 如果你是持卡人，可快捷查询信用卡账单、额度及积分；快速还款、申请账单分期；微信转接人工服务；信用卡消费，微信免费笔笔提醒。如果不是持卡人，可以微信办卡！ 招商银行公众号通过提示消息引导用户将自己的微信号和信用卡号安全绑定。 用户可以通过该公众号查询账单、收取刷卡通知等功能，这是由招行开发人员通过公众号接口实现的功能。 中国南方航空 - 3 - 你可以办理值机手续，挑选座位，查询航班信息，查询目的地城市天气，并为明珠会员提供专业的服务。 南方航空公众号可以让用户将明珠会员服务和微信号绑定起来。 用户可以通过该公众号预订机票、查询订单，甚至办理登机牌。 广东联通 - 4 - 你可以在微信里绑定手机号、积分流量，套餐余量、手机上网流量，微信专属流量查询，客服咨询。 广东联通公众号可以绑定手机号，来查询流量、套餐等等功能。 广东联通更与微信深度合作，购买微信沃卡可以获得微信五大特权。 壹、新手接入 一、接入指南 第一步：申请消息接口 - 5 - 在公众平台网站的高级功能 开发模式页，点击“成为开发者”按钮，填写中 作生成签名（该 和接口 包含的而验证安全性）。 第二步：验证 开发者提交信息后，微信服务器将发送 求到填写的 ， 求携带四个参数： 参数 描述 信加密签名， 合了开发者填写的 数和请求中的 间戳 机数 机字符串 开发者通过检验 面有校验方式）。若确认此次 原样返回 接入生效，成为开发者成功，否则接入失败。 加密 /校验流程如下： 1. 将 2. 将三个参数字符串拼接成一个字符串进行 3. 开发者获得加密后的字符串可与 识该请求来源于微信 。 检验 1. 2. 3. $ $_; 4. $ $_; 5. $ $_; 6. $ - 6 - 7. $ $ 8. 9. $ $; 10. $ $; 11. $= $ 12. 13. 14. 15. 16. ：成为开发者 验证 效性成功后即接入生效，成为开发者。如果公众号类型为服务号（订阅号只能使用普通消息接口），可以在公众平台网站中申请认证，认证成功的服务号将获得众多接口权限，以满足开发者需求。 此后用户每次向公众号发送消息、或者产生自定义菜单点击事件时，响应 公众号调用各接口时，一般会获得正确的结果，具体结果可见对应接口的说明。返回错误时，可根据返回码来查询错误原因。全局返回码说明 用户向公众号发送消息时，公众号方收到的消息发送者是一个 使用用户微信号加密后的结果，每个用户对每个公众号有一个唯 一的 此外请注意， 微信公众号接口只支持 80接口 。 二、典型案例介绍 值得借鉴的公众帐号主要是服务号，试列举并介绍如下： 招商银行信用卡中心 - 7 - 如果你是持卡人，可快捷查询信用卡账单、额度及积分；快速还款、申请账单分期；微信转接人工服务；信用卡消费，微信免费笔笔提醒。如果不是持卡人，可以微信办卡！ 招商银行公众号通过提示消息引导用户将自己的微信号和信用卡号安全绑定。 用户可以通过该公众号查询账单、收取刷卡通知等功能，这是由招行开发人员通过公众号接口实现的功能。 中国南方航空 - 8 - 你可以办理值机手续，挑选座位，查询航班信息，查询目的地城市天气，并为明珠会员提供专业的服务。 南方航空公众号可以让用户将明珠会员服务和微信号绑定起来。 用户可以通过该公众号预订机票、查询订单，甚至办理登机牌。 广东联通 - 9 - 你可以在微信里绑定手机号、积分流量，套餐余量、手机上网流量，微信专属流量查询，客服咨询。 广东联通公众号可以绑定手机号，来查询流量、套餐等等功能。 广东联通更与微信深度合作，购买微信沃卡可以获得微信五大特权。 三、开发者规范 开发者进行公众号开发时，除了需要满足每个接口的规范限制、调用频率限制外，还需特别注意模版消息、用户数据等敏感信息的使用规范。 涉及用户数据时： 您的服务需要收集用户任何数据的，必须事先获得用户的明确同意，且仅应当收集为运营及功能实现目的而必要的用户数据， 同时应当告知用户相关数据收集的目的、范围及使用方式等，保障用户知情权。 您收集用户的数据后，必须采取必要的保护措施，防止用户数据被盗、泄漏等。 - 10 - 您在特定微信公众号中收集的用户数据仅可以在该特定微信公众号中使用，不得将其使用在该特定微信公众号之外或为其他任何 目的进行使用，也不得以任何方式将其提供给他人。 如果腾讯认为您收集、使用用户数据的方式，可能损害用户体验，腾讯有权要求您删除相关数据并不得再以该方式收集、使用用户数据。 一旦您停止使用本服务，或腾讯基于任何原因终止您使用本服务，您必须立即删除全部因使用本服务而获得的数据（包括各种备份）， 且不得再以任何方式进行使用。 其他规范： 请勿为任何用户自动登录到微信公众平台提供代理身份验证凭据。 请勿提供跟踪功能，包括但不限于识别其他用户在个人主页上查看、点击等操作行为。 请勿自动将浏览器窗口定向到其他网页。 请勿设置或发布任何违反相关法规、公序良俗、社会公德等的玩法、内容等。 请勿公开表达或暗示，您与腾讯之间存在合作关系，包括但不限于相互持股、商业往来或合作关系等，或声称腾讯对您的认可。 完整的开发者规范和接口限制，请详见开发者接口文档，以及腾讯微信公众平台开发者协议。 贰、基础支持 一、获取 公众号的全局唯一票据，公众号调用各接口时都需使用常情况下 200秒，重复获取将导致上次获取的 - 11 - 公众号可以使用 要已经成为开发者，且帐号没有异常状态）。注意 调用所有微信接口时均需使用 接口调用请求说明 ，微信会返回下述 """7200 参数 说明 取到的凭证 证有效时间，单位：秒 错误时微信会返回错误码等信息， 示例为 : "40013,"" 二、全局返回码说明 公众号每次调用接口时，可能获得正确或错误的返回码，开发者可以根据返- 12 - 回码信息调试接口，排查错误。 全局返回码说明如下： 返回码 说明 统繁忙 0 请求成功 40001 获取 者 40002 不合法的凭证类型 40003 不合法的 0004 不合法的媒体文件类型 40005 不合法的文件类型 40006 不合法的文件大小 40007 不合法的媒体文件 0008 不合法的消息类型 40009 不合法的图片文件大小 40010 不合法的语音文件大小 40011 不合法的视频文件大小 40012 不合法的缩略图文件大小 40013 不合法的 0014 不合法的 0015 不合法的菜单类型 40016 不合法的按钮个数 40017 不合法的按钮个数 40018 不合法的按钮名字长度 40019 不合法的按钮 40020 不合法的按钮 40021 不合法的菜单版本号 40022 不合法的子菜单级数 40023 不合法的子菜单按钮个数 40024 不合法的子菜单按钮类型 40025 不合法的子菜单按钮名字长度 40026 不合法的子菜单按钮 40027 不合法的子菜单按钮 40028 不合法的自定义菜单使用用户 40029 不合法的 0030 不合法的 0031 不合法的 40032 不合法的 40033 不合法的请求字符，不能包含 40035 不合法的参数 - 13 - 40038 不合法的请求格式 40039 不合法的 40050 不合法的分组 0051 分组名字不合法 41001 缺少 41002 缺少 41003 缺少 41004 缺少 41005 缺少多媒体文件数据 41006 缺少 41007 缺少子菜单数据 41008 缺少 1009 缺少 2001 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 分组数量超过上限 - 14 - 46001 不存在媒体数据 46002 不存在的菜单版本 46003 不存在的菜单数据 46004 不存在的用户 47001 解析 48001 50001 用户未授权该 、接口频率限制说明 公众号调用接口并不是无限制的。为了防止公众号的程序错误而引发微信服务器负载异常，默认情况下，每个公众号调用接口都不能超过一定限制，当超过一定限制时，调用对应接口会收到如下错误返回码： "45009,""of 各接口调用频率限制如下： 接口 每日限额 获取 000 自定义菜单创建 1000 自定义菜单查询 10000 自定义菜单删除 1000 创建分组 1000 获取分组 1000 修改分组名 1000 移动用户分组 100000 上传多媒体文件 5000 下载多媒体文件 10000 发送客服消息 500000 获取带参数的二维码 100000 获取关注者列表 500 获取用户基本信息 5000000 获取网页授权 000000 刷新网页授权 000000 网页授权获取用户信息 2000000 请注意，在测试号申请页中申请的测试号，接口调用频率限制如下： 接口 每日限额 获取 00 自定义菜单创建 100 - 15 - 自定义菜单查询 1000 自定义菜单删除 100 创建分组 100 获取分组 100 修改分组名 100 移动用户分组 1000 上传多媒体文件 500 下载多媒体文件 1000 发送客服消息 50000 获取带参数的二维码 10000 获取关注者列表 100 获取用户基本信息 500000 获取网页授权 00000 刷新网页授权 00000 网页授权获取用户信息 200000 四、上传下载多媒体文件 公众号在使用接口时，对多媒体文件、多媒体消息的获取和调用等操作，是通过 进行的。通过本接口，公众号可以上传或下载多媒体文件。但请注意，每个多媒体文件（ 在上传、用户发送到微信服务器 3天后自动删除，以节省服务器资源。 上传多媒体文件 公众号可调用本接口来上传图片、语音、视频等文件到微信服务器，上传后服务器会返回对应的 众号此后可根据该 获取多媒体。请注意， 用该接口需 接口调用请求说明 （使用 - 16 - F " 参数说明 参数 是否必须 说明 调用接口凭证 媒体文件类型，分别有图片（ 语音（ 视频（ 缩略图（ 媒体文件标识，有 返回说明 正确情况下的返回 """""123456789 参数 描述 体文件类型，分别有图片（ 语音（ 视频（ 缩略图（ 要用于视频与音乐格式的缩略图） 体文件上传后，获取时的唯一标识 体文件上传时间戳 错误情况下的返回 例为无效媒体类型错误）： "40004,"" 注意事项 上传的多媒体文件有格式和大小限制，如下： 图片（ : 128K，支持 语音（ 256K，播放长度不超过 60s，支持 视频（ 1持 缩略图（ 64持 媒体文件在后台保存时间为 3天，即 3天后 - 17 - 下载多媒体文件 公众号可调用本接口来获取多媒体文件。 请注意，视频文件不支持下载，调用该接口需 接口调用请求说明 （示例为通过 I " 参数说明 参数 是否必须 说明 调用接口凭证 媒体文件 回说明 正确情况下的返回 00 06 013 10:20:18 339721 - 18 - G "" 错误情况下的返回 例为无效媒体 : "40007,"" 叁、接收消息 一、 验证消息真实性 在开发者首次提交验证申请时，微信服务器将发送 求到填写的 且带上四个参数（ 开发者通过对签名（即 效验，来判断此条消息的真实性。 此后，每次开发者接收用户消息的时候，微信也都会带上前面三个参数（ 问开发者设置的 发者依然通过对签名的效验判断此条消息的真实性。效验方式与首次提交验证申请一致。 参数 描述 信加密签名， 合了开发者填写的 数和请求中的 间戳 机数 机字符串 开发者通过检验 面有校验方式）。若确认此次 原样返回 接入生效，成为开发者成功，否则接入失败。 加密 /校验流程如下： 1. 将 - 19 - 2. 将三个参数字符串拼接成一个字符串进行 3. 开发者获得加密后的字符串可与 识该请求来源于微信 检验 17. 18. 19. $ $_; 20. $ $_; 21. $ $_; 22. $ 23. $ $ 24. 25. $ $; 26. $ $; 27. $= $ 28. 29. 30. 31. 32. 二 、 接收普通消息 当普通微信用户向公众账号发消息时，微信服务器将 息的 据包到开发者填写的 消息类型的推送 1、 文本消息 33. 34. 35. 36. 1348831860 37. 38. 39. 1234567890123456 40. 参数说明： - 20 - 2、 图片消息 41. 42. 43. 44. 1348831860 45. 46. 47. 48. 1234567890123456 49. 参数说明： 3、 语音消息 50. 51. 参数 描述 发者微信号 送方帐号（一个 息创建时间 （整型） 本消息内容 息 64位整型 参数 描述 发者微信号 送方帐号（一个 息创建时间 （整型） 片链接 片消息媒体 以调用多媒体文件下载接口拉取数据。 息 64位整型 - 21 - 52. 53. 1357290913 54. 55. 56. 57. 1234567890123456 58. 参数说明： 4、 视频消息 59. 60. 61. 62. 1357290913 63. 64. 65. 66. 1234567890123456 67. 参数说明： 参数 描述 发者微信号 送方帐号（一个 息创建时间 （整型） 音为 音消息媒体 以调用多媒体文件下载接口拉取数据。 音格式，如 息 64位整型 参数 描述 发者微信号 送方帐号（一个 息创建时间 （整型） 频为 22 - 5、 地理位置消息 68. 69. 70. 71. 1351776360 72. 73. 4. 5. 20 76. 77. 1234567890123456 78. 参数说明： 6、 链接消息 79. 频消息媒体 以调用多媒体文件下载接口拉取数据。 频消息缩略图的媒体 以调用多媒体文件下载接口拉取数据。 息 64位整型 参数 描述 发者微信号 送方帐号（一个 息创建时间 （整型） 理位置维度 理位置精度 图缩放大小 理位置信息 息 64位整型 - 23 - 80. 81. 82. 1351776360 83. 84. 85. 86. 87. 1234567890123456 88. 参数说明： 三 、接收事件推送 1、关注 /取消关注事件 用户在关注与取消关注公众号事，微信会把这个事件推送到开发者填写的便开发者给用户下发欢迎消息或者做帐号的解绑。 推送 89. 90. 91. 92. 123456789 93. 94. 95. 参数 描述 收方微信号 送方微信号，若为普通用户，则是一个 息创建时间 息类型， 息标题 息描述 息链接 息 64位整型 - 24 - 参数说明： 2、扫描带参数二维码事件 用户扫描带场景值二维码时，可能推送以下两种事件： 果用户还未关注公众号，则用户可以关注公众号，关注后微信会将带场景值关注事件推送给开发者。 果用户已经关注公众号，则微信