微信公众号分为订阅号、服务号、企业号。
订阅号一般偏向于媒体资讯,订阅号的文件夹中,不会收到微信提醒,不能进行微信支付。
服务号一般用于企业宣传、服务交互,消息出现在微信聊天列表中,会像收到消息一样有微信提醒。
企业号一般用于企业内部管理,可以有多个应用
1.获取access_token
access_token是企业后台去企业微信的后台获取信息时的重要票据,由corpid和secret产生。所有接口在通信时都需要携带此信息用于验证接口的访问权限。
需要在企业微信后台已知的企业ID:corpid 和 钥匙:secret。
secret是企业应用里面用于保障数据安全的“钥匙”,每一个应用都有一个独立的访问密钥。
请求方式:GET(HTTPS)
请求URL:https://qyapi.weixin.qq.com/cgi-bin/gettoken?corpid=ID&corpsecret=SECRECT
注:此处标注大写的单词ID和SECRET,为需要替换的变量,根据实际获取值更新。其它接口也采用相同的标注,不再说明。
缓存access_token
- access_token的有效期通过返回的expires_in来传达,正常情况下为7200秒(2小时),有效期内重复获取返回相同结果,过期后获取会返回新的access_token。
- 由于企业微信每个应用的access_token是彼此独立的,所以进行缓存时需要区分应用来进行存储。
2.JS-SDK使用权限签名算法
获取企业的jsapi_ticket
生成签名之前必须先了解一下jsapi_ticket,jsapi_ticket是H5应用调用企业微信JS接口的临时票据。正常情况下,jsapi_ticket的有效期为7200秒,通过access_token来获取。由于获取jsapi_ticket的api调用次数非常有限(一小时内,一个企业最多可获取400次,且单个应用不能超过100次),频繁刷新jsapi_ticket会导致api调用受限,影响自身业务,开发者必须在自己的服务全局缓存jsapi_ticket。
请求方式:GET(HTTPS)
请求URL:https://qyapi.weixin.qq.com/cgi-bin/get_jsapi_ticket?access_token=ACCESS_TOKEN
签名算法
签名生成规则如下:
参与签名的参数有四个: noncestr(随机字符串), jsapi_ticket, timestamp(时间戳), url(当前网页的URL, 不包含#及其后面部分)
将这些参数使用URL键值对的格式 (即 key1=value1&key2=value2…)拼接成字符串string1。然后对string1作sha1加密即可。
注意事项
- 签名用的noncestr和timestamp必须与wx.config中的nonceStr和timestamp相同。
- 签名用的url必须是调用JS接口页面的完整URL。
- 出于安全考虑,开发者必须在服务器端实现签名的逻辑。
如出现invalid signature 等错误详见附录4常见错误及解决办法。
加密示例 :
假如有如下参数:
noncestr=Wm3WZYTPz0wzccnW
jsapi_ticket=sM4AOVdWfPE4DxkXGEs8VMCPGGVi4C3VM0P37wVUCFvkVAy_90u5h9nbSlYy3-Sl-HhTdfl2fzFy1AOcHKP7qg
timestamp=1414587457
url=http://mp.weixin.qq.com?params=value
步骤1. 将这些参数拼接成字符串string1:
jsapi_ticket=sM4AOVdWfPE4DxkXGEs8VMCPGGVi4C3VM0P37wVUCFvkVAy_90u5h9nbSlYy3-Sl-HhTdfl2fzFy1AOcHKP7qg&noncestr=Wm3WZYTPz0wzccnW×tamp=1414587457&url=http://mp.weixin.qq.com?params=value
步骤2. 对string1进行sha1签名,得到signature:
0f9de62fce790f9a083d5c99e95740ceb90c27ed
3.权限列表
接口名称 | 未认证订阅号 | 微信认证订阅号 | 未认证服务号 | 微信认证服务号 |
---|---|---|---|---|
基础支持-获取access_token | 有 | 有 | 有 | 有 |
基础支持-获取微信服务器IP地址 | 有 | 有 | 有 | 有 |
接收消息-验证消息真实性、接收普通消息、接收事件推送、接收语音识别结果 | 有 | 有 | 有 | 有 |
发送消息-被动回复消息 | 有 | 有 | 有 | 有 |
发送消息-客服接口 | 有 | 有 | ||
发送消息-群发接口 | 有 | 有 | ||
发送消息-模板消息接口(发送业务通知) | 有 | |||
发送消息-一次性订阅消息接口 | 有 | 有 | ||
用户管理-用户分组管理 | 有 | 有 | ||
用户管理-设置用户备注名 | 有 | 有 | ||
用户管理-获取用户基本信息 | 有 | 有 | ||
用户管理-获取用户列表 | 有 | 有 | ||
用户管理-获取用户地理位置 | 有 | |||
用户管理-网页授权获取用户openid/用户基本信息 | 有 | |||
推广支持-生成带参数二维码 | 有 | |||
推广支持-长链接转短链接口 | 有 | |||
界面丰富-自定义菜单 | 有 | 有 | 有 | |
素材管理-素材管理接口 | 有 | 有 | ||
智能接口-语义理解接口 | 有 | |||
多客服-获取多客服消息记录、客服管理 | 有 | |||
微信支付接口 | 需申请 | |||
微信小店接口 | 需申请 | |||
微信卡券接口 | 需申请 | 需申请 | ||
微信设备功能接口 | 需申请 | |||
微信发票接口 | 有 | 有 | ||
微信JS-SDK-基础接口 | 有 | 有 | 有 | 有 |
微信JS-SDK-分享接口 | 有 | 有 | ||
微信JS-SDK-图像接口 | 有 | 有 | 有 | 有 |
微信JS-SDK-音频接口 | 有 | 有 | 有 | 有 |
微信JS-SDK-智能接口(网页语音识别) | 有 | 有 | 有 | 有 |
微信JS-SDK-设备信息 | 有 | 有 | 有 | 有 |
微信JS-SDK-地理位置 | 有 | 有 | 有 | 有 |
微信JS-SDK-界面操作 | 有 | 有 | 有 | 有 |
微信JS-SDK-微信扫一扫 | 有 | 有 | 有 | 有 |
微信JS-SDK-微信小店 | 有 | |||
微信JS-SDK-微信卡券 | 有 | 有 | ||
微信JS-SDK-微信支付 | 有 |
4.全局返回码说明
公众号每次调用接口时,可能获得正确或错误的返回码,开发者可以根据返回码信息调试接口,排查错误。
5.消息管理
接受文本消息
粉丝给公众号发送文本消息:“欢迎开启公众号开发者模式”,在开发者后台,收到公众平台发送的xml 如下:(下文均隐藏了ToUserName 及 FromUserName 信息)
<xml>
<ToUserName><![CDATA[公众号]]></ToUserName>
<FromUserName><![CDATA[粉丝号]]></FromUserName>
<CreateTime>1460537339</CreateTime>
<MsgType><![CDATA[text]]></MsgType>
<Content><![CDATA[欢迎开启公众号开发者模式]]></Content>
<MsgId>6272960105994287618</MsgId>
</xml>
解释:
createTime 是微信公众平台记录粉丝发送该消息的具体时间
text: 用于标记该xml 是文本消息,一般用于区别判断
MsgId: 是公众平台为记录识别该消息的一个标记数值, 微信后台系统自动产生
它其实并不是一种接口,而是对微信服务器发过来消息的一次回复,收到粉丝消息后不想或者不能5秒内回复时,需回复“success”字符串(下文详细介绍),客服接口在满足一定条件下随时调用。
若发送的是图片
<xml>
<ToUserName><![CDATA[公众号]]></ToUserName>
<FromUserName><![CDATA[粉丝号]]></FromUserName>
<CreateTime>1460536575</CreateTime>
<MsgType><![CDATA[image]]></MsgType>
<PicUrl><![CDATA[http://mmbiz.qpic.cn/xxxxxx /0]]></PicUrl>
<MsgId>6272956824639273066</MsgId>
<MediaId><![CDATA[gyci5a-xxxxx-OL]]></MediaId>
</xml>
PicUrl: 这个参数是微信系统把“粉丝“发送的图片消息自动转化成url。 这个url可用浏览器打开查看到图片。
MediaId: 是微信系统产生的id 用于标记该图片
被动回复文本消息
公众号想回复给粉丝一条文本消息,内容为“test”, 那么开发者发送给公众平台后台的xml 内容如下:
<xml>
<ToUserName><![CDATA[粉丝号]]></ToUserName>
<FromUserName><![CDATA[公众号]]></FromUserName>
<CreateTime>1460541339</CreateTime>
<MsgType><![CDATA[text]]></MsgType>
<Content><![CDATA[test]]></Content>
</xml>
特别备注:
createtime 只用于标记开发者回复消息的时间,微信后台发送此消息都是不受这个字段约束。
text : 用于标记 此次行为是发送文本消息 (当然可以是image/voice等类型)。
假如服务器无法保证在五秒内处理回复,则必须回复“success”或者“”(空串),否则微信后台会发起三次重试。发起重试是微信后台为了尽可以保证粉丝发送的内容开发者均可以收到。
客服消息
当用户和公众号产生特定动作的交互时(具体动作列表请见下方说明),微信将会把消息数据推送给开发者,开发者可以在一段时间内(目前修改为48小时)调用客服接口, 通过POST一个JSON数据包来发送消息给普通用户。此接口主要用于客服等有人工消息处理环节的功能,方便开发者为用户提供更加优质的服务。1、用户发送信息
2、点击自定义菜单(仅有点击推事件、扫码推事件、扫码推事件且弹出“消息接收中”提示框这3种菜单类型是会触发客服接口的)
3、关注公众号
4、扫描二维码
5、支付成功
6、用户维权
例如发送语音信息
{
"touser":"OPENID",
"msgtype":"voice",
"voice":
{
"media_id":"MEDIA_ID"
}
}
发送图文消息(点击跳转到外链) 图文消息条数限制在1条以内,注意,如果图文数超过1,则将会返回错误码45008。
{
"touser":"OPENID",
"msgtype":"news",
"news":{
"articles": [
{
"title":"Happy Day",
"description":"Is Really A Happy Day",
"url":"URL",
"picurl":"PIC_URL"
}
]
}
}
群发接口和原创校验
在公众平台网站上,为订阅号提供了每天一条的群发权限,为服务号提供每月(自然月)4条的群发权限。而对于某些具备开发能力的公众号运营者,可以通过高级群发接口,实现更灵活的群发能力。
群发图文消息的过程如下:
1、首先,预先将图文消息中需要用到的图片,使用上传图文消息内图片接口,上传成功并获得图片 URL;
2、上传图文消息素材,需要用到图片时,请使用上一步获取的图片 URL;
3、使用对用户标签的群发,或对 OpenID 列表的群发,将图文消息群发出去,群发时微信会进行原创校验,并返回群发操作结果;
4、在上述过程中,如果需要,还可以预览图文消息、查询群发状态,或删除已群发的消息等。
6.素材(多媒体文件)
素材分为临时素材和永久素材。对多媒体文件、多媒体消息的获取和调用等操作,是通过MediaID来进行。永久素材保存在微信公众平台后台数量有限,而临时素材不能长期存储,在公众平台官网的素材管理中查询不到,但是可以通过接口对其操作。获取临时素材MediaID
临时素材的MediaID 没有提供特定的接口进行统一查询,因此有俩种方式
1) 通过接口上次的临时素材,在调用成功的情况下,从返回JSON数据中提取MediaID,可临时使用
2) 粉丝互动中的临时素材,可从xml 数据提取MediaID,可临时使用
7.自定义菜单
1、自定义菜单最多包括3个一级菜单,每个一级菜单最多包含5个二级菜单。
2、一级菜单最多4个汉字,二级菜单最多7个汉字,多出来的部分将会以“...”代替。
写在后台例如:
并列 开发指引、公众平台、旅行三个一级菜单,公众平台一级菜单下 更新公告、接口权限说明、返回码说明三个二级菜单。
postJson = """ { "button": [ { "type": "click", "name": "开发指引", "key": "mpGuide" }, { "name": "公众平台", "sub_button": [ { "type": "view", "name": "更新公告", "url": "http://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1418702138&token=&lang=zh_CN" }, { "type": "view", "name": "接口权限说明", "url": "http://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1418702138&token=&lang=zh_CN" }, { "type": "view", "name": "返回码说明", "url": "http://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1433747234&token=&lang=zh_CN" } ] }, { "type": "media_id", "name": "旅行", "media_id": "z2zOokJvlzCXXNhSjF46gdx6rSghwX2xOD5GUV9nbX4" } ] }
自定义菜单按钮类型
1、click:点击推事件用户点击click类型按钮后,微信服务器会通过消息接口推送消息类型为event的结构给开发者(参考消息接口指南),并且带上按钮中开发者填写的key值,开发者可以通过自定义的key值与用户进行交互;
2、view:跳转URL用户点击view类型按钮后,微信客户端将会打开开发者在按钮中填写的网页URL,可与网页授权获取用户基本信息接口结合,获得用户基本信息。
3、scancode_push:扫码推事件用户点击按钮后,微信客户端将调起扫一扫工具,完成扫码操作后显示扫描结果(如果是URL,将进入URL),且会将扫码的结果传给开发者,开发者可以下发消息。
4、scancode_waitmsg:扫码推事件且弹出“消息接收中”提示框用户点击按钮后,微信客户端将调起扫一扫工具,完成扫码操作后,将扫码的结果传给开发者,同时收起扫一扫工具,然后弹出“消息接收中”提示框,随后可能会收到开发者下发的消息。
5、pic_sysphoto:弹出系统拍照发图用户点击按钮后,微信客户端将调起系统相机,完成拍照操作后,会将拍摄的相片发送给开发者,并推送事件给开发者,同时收起系统相机,随后可能会收到开发者下发的消息。
6、pic_photo_or_album:弹出拍照或者相册发图用户点击按钮后,微信客户端将弹出选择器供用户选择“拍照”或者“从手机相册选择”。用户选择后即走其他两种流程。
7、pic_weixin:弹出微信相册发图器用户点击按钮后,微信客户端将调起微信相册,完成选择操作后,将选择的相片发送给开发者的服务器,并推送事件给开发者,同时收起相册,随后可能会收到开发者下发的消息。
8、location_select:弹出地理位置选择器用户点击按钮后,微信客户端将调起地理位置选择工具,完成选择操作后,将选择的地理位置发送给开发者的服务器,同时收起位置选择工具,随后可能会收到开发者下发的消息。
9、media_id:下发消息(除文本消息)用户点击media_id类型按钮后,微信服务器会将开发者填写的永久素材id对应的素材下发给用户,永久素材类型可以是图片、音频、视频、图文消息。请注意:永久素材id必须是在“素材管理/新增永久素材”接口上传后获得的合法id。
10、view_limited:跳转图文消息URL用户点击view_limited类型按钮后,微信客户端将打开开发者在按钮中填写的永久素材id对应的图文消息URL,永久素材类型只支持图文消息。请注意:永久素材id必须是在“素材管理/新增永久素材”接口上传后获得的合法id。
也可凭借自己的喜好创建个性化菜单