微信消息 · 微擎说明文档

* [消息概述](http://s.w7.cc/index.php?c=wiki&do=view&id=1&list=542#消息概述) * [消息结构](http://s.w7.cc/index.php?c=wiki&do=view&id=1&list=542#消息结构) * [消息结构类型](http://s.w7.cc/index.php?c=wiki&do=view&id=1&list=542#消息结构类型) * [文本消息](http://s.w7.cc/index.php?c=wiki&do=view&id=1&list=542#文本消息) * [图片消息](http://s.w7.cc/index.php?c=wiki&do=view&id=1&list=542#图片消息) * [地理位置消息](http://s.w7.cc/index.php?c=wiki&do=view&id=1&list=542#地理位置消息) * [链接消息](http://s.w7.cc/index.php?c=wiki&do=view&id=1&list=542#链接消息) * [关注消息](http://s.w7.cc/index.php?c=wiki&do=view&id=1&list=542#关注消息) * [取消关注消息](http://s.w7.cc/index.php?c=wiki&do=view&id=1&list=542#取消关注消息) * [菜单点击消息](http://s.w7.cc/index.php?c=wiki&do=view&id=1&list=542#菜单点击消息) * [用户未关注时，进行关注后的事件推送](http://s.w7.cc/index.php?c=wiki&do=view&id=1&list=542#用户未关注时，进行关注后的事件推送) * [用户已关注时的事件推送](http://s.w7.cc/index.php?c=wiki&do=view&id=1&list=542#用户已关注时的事件推送) * [上报地理位置事件](http://s.w7.cc/index.php?c=wiki&do=view&id=1&list=542#上报地理位置事件) * [点击推事件](http://s.w7.cc/index.php?c=wiki&do=view&id=1&list=542#点击推事件) * [跳转 URL](http://s.w7.cc/index.php?c=wiki&do=view&id=1&list=542#跳转 URL) * [扫码推事件](http://s.w7.cc/index.php?c=wiki&do=view&id=1&list=542#扫码推事件) * [扫码推事件且弹出“消息接收中”提示框](http://s.w7.cc/index.php?c=wiki&do=view&id=1&list=542#扫码推事件且弹出“消息接收中”提示框) * [弹出系统拍照发图](http://s.w7.cc/index.php?c=wiki&do=view&id=1&list=542#弹出系统拍照发图) * [弹出拍照或者相册发图](http://s.w7.cc/index.php?c=wiki&do=view&id=1&list=542#弹出拍照或者相册发图) * [弹出微信相册发图器](http://s.w7.cc/index.php?c=wiki&do=view&id=1&list=542#弹出微信相册发图器) * [弹出地理位置选择器](http://s.w7.cc/index.php?c=wiki&do=view&id=1&list=542#弹出地理位置选择器) * [获取用户地理位置](http://s.w7.cc/index.php?c=wiki&do=view&id=1&list=542#获取用户地理位置) * [点击菜单拉取消息时的事件推送](http://s.w7.cc/index.php?c=wiki&do=view&id=1&list=542#点击菜单拉取消息时的事件推送) #### 消息概述用户发送给公众号的信息，包括文本、语音、视频、位置、图片等等，统称为消息。系统在接收到这些消息时，会转化为消息的数据结构，然后进行相应的解析、分发、响应。 #### 消息结构 ~~~ <xml><ToUserName><![CDATA[toUser]]></ToUserName><FromUserName><![CDATA[fromUser]]></FromUserName><CreateTime>12345678</CreateTime><MsgType><![CDATA[text]]></MsgType><Content><![CDATA[你好！]]></Content></xml> ~~~ 上方xml即为一个消息结构原型，微擎系统接收到消息后，会转化成以下的数组形式，如下： ~~~ $message => array( // 此部分数据结构为**全局共有的结构**, 其他消息类型为此结构的**补充**. 'from' => 'fromUser', //string: 发送消息方, 代表一个粉丝用户(使用OpenID表示) 'to' => 'toUser', //string: 消息接收方, 对应当前的公众号(使用OpenID表示) 'time' => '12345678', //int: 消息发送时间, 使用Unix时间戳表示 'type' => 'text', //string: 消息类型, 用于区分不同类型的消息, 请参阅下文 'content' => '你好！', //string：消息内容 'msgid' => '' //int: 消息ID, 公众平台系统用于唯一标识一条请求消息); ~~~ 微擎系统会通过这个消息结构数组，使用**规则**和**模块**的机制来处理公众平台的请求数据并返回响应的结果，具体请参看下一章“[消息响应](http://www.kancloud.cn/donknap/we7/134650)” ### 消息结构类型消息类型同公众平台官方不同之处在于将**event**类型拆分开为独立的消息类型,**避免了重复判断**. 根据消息类型不同, 消息对象结构还存在不同的附加数据,按照类型定义如下: ##### 文本消息 **粉丝**用户向**公众号**发送了一条普通**文本消息**(包括包含表情的消息, 或者纯表情消息) 处理文本消息可以实现简单的文本对话, 结合使用文本上下文(请参阅上下文处理)可以实现调查, 测试等复杂的交互. ~~~ $text_message = array( // 全局数据 'tousername' => 'toUser' 'fromusername' => 'fromUser' 'createtime' => '123456789' 'msgtype' => 'text' // string: 消息类型 'content' => // string: 文本消息内容 'redirection' => false, // bool: 是否是重定向 'source' => null // string: 消息来源, 消息二次分析(目前来源:qr,click, 将扫码等事件转换为 text 事件.)) ~~~ ##### 图片消息粉丝用户向公众号发送了一张**图片**. 处理图片消息可以实现分享用户图片的相关功能 ~~~ $image_message = array( // 全局数据 'tousername' => 'toUser' 'fromusername' => 'fromUser' 'createtime' => '123456789' 'msgtype' => 'image' // string: 消息类型 'picurl' => '' // string: 图片链接 'mediaid' => '' // long: 图片消息媒体id 'url' => ''); ~~~ ##### 地理位置消息粉丝用户向公众号发送了一条**地理位置**. 处理地理位置消息可以实现**LBS**相关功能(参阅LBS方案) ~~~ $location_message = array( // 全局数据 'tousername' => 'toUser' 'fromusername' => 'fromUser' 'createtime' => '123456789' 'msgtype' => 'location' // string: 消息类型 'location_x' => '' // float: 地理位置纬度 'location_y' => '' // float: 地理位置经度 'scale' => '' // float: 地图缩放大小 'label' => '' // string: 地理位置信息) ~~~ ##### 链接消息粉丝用户向公众号发送了一条**链接消息**. 处理链接消息可以实现好友分享等社交功能 ~~~ $link_message = array( // 全局数据 'tousername' => 'toUser' 'fromusername' => 'fromUser' 'createtime' => '123456789' 'msgtype' => 'link' // string: 消息类型 'title' => '' // string: 消息标题 'description' => '' // string: 消息描述 'url' => '' // string: 消息链接 ) ~~~ ##### 关注消息粉丝用户关注当前公众号后将会获得此消息. 处理此消息可以实现欢迎信息和粉丝增长统计 ~~~ $trace = array( // 全局数据 'tousername' => 'toUser' 'fromusername' => 'fromUser' 'createtime' => '123456789' 'msgtype' => 'event' 'eventkey' => ) ~~~ ##### 取消关注消息粉丝用户取消关注当前公众号后将会获得此消息. 处理此消息可以实现粉丝数量增长分析 ~~~ $unsubscribe_message = array( // 全局数据 'tousername' => 'toUser' 'fromusername' => 'fromUser' 'createtime' => '123456789' 'msgtype' => 'event' 'eventkey' => ) ~~~ ##### 菜单点击消息粉丝用户点击自定菜单后, 如果菜单设置为消息回复, 那么将会获得此消息. 处理此消息能实现自定义菜单的特定回复 ~~~ $click_message = array( // 全局数据 'tousername' => 'toUser' 'fromusername' => 'fromUser' 'createtime' => '123456789' 'msgtype' => 'event' 'eventkey' => 'EVENTKEY' // string: 模拟的关键字) ~~~ ##### 用户未关注时，进行关注后的事件推送 ~~~ $trace = array( 'tousername => 'toUser' 'fromusername' => 'FromUser' 'createtime' => '123456789' 'msgtype' => 'event' 'eventkey' => 'qrscene_123123' 'ticket' => 'TICKET' // string: 二维码的ticket，可用来换取二维码图片 'scene' => '123' // int : 事件KEY值,二维码的参数值,已去除'qrscene_'前缀) ~~~ ##### 用户已关注时的事件推送 ~~~ $qr_message = array( 'tousername' => 'toUser' 'fromusername' => 'FromUser' 'createtime' => '123456789' 'msgtype' => 'event' 'eventkey' => 'SCENE_VALUE' 'ticket' => 'TICKET' // string: 二维码的ticket，可用来换取二维码图片 'scene' => '123' // int: 事件KEY值，是一个32位无符号整数，即创建二维码时的二维码scene_id ) ~~~ ##### 上报地理位置事件 ~~~ $trace_message = array( 'tousername' => 'toUser' 'fromusername' => 'fromUser' 'createtime' => '123456789' 'msgtype' => 'event' 'latitude' => '' // string: 地理位置纬度 'longitude' => '' // string: 地理位置经度 'precision' => '' // string: 地理位置精度 'location_x' => ? ⇔ location_x // 原始值 'location_y' => ? ⇔ location_y // 原始值) ~~~ ##### 点击推事件 ~~~ $click_message = array( 'tousername' => 'toUser' 'fromusername' => 'fromUser' 'createtime' => '123456789' 'msgtype' => 'event' 'eventkey' => 'EVENTKEY' // string: 模拟的关键字) ~~~ ##### 跳转 URL ~~~ $view_message = array( 'tousername' => 'toUser' 'fromusername' => 'FromUser' 'createtime' => '123456789' 'msgtype' => 'event' 'eventkey' => 'www.qq.com' // string: 设置的跳转URL ) ~~~ ##### 扫码推事件 ~~~ $view_message = array( 'tousername' => 'toUser' 'fromusername' => 'fromUser' 'createtime' => '123456789' 'msgtype' => 'event' 'eventkey' => '' // 事件KEY值，由开发者在创建菜单时设定 'scancodeinfo' => array( // 扫描信息 'scanresult' => '1' // 扫描结果，即二维码对应的字符串信息 'scantype' => 'qrcode' // 扫描类型，一般是qrcode 'eventkey' => )) ~~~ ##### 扫码推事件且弹出“消息接收中”提示框参阅 \[\[dev:terms?&#scancode\_push|☞ 3. scancode\_push\]\] ~~~ $view_message = array( 'tousername' => 'toUser' 'fromusername' => 'fromUser' 'createtime' => '123456789' 'msgtype' => 'event' 'eventkey' => '' // 事件KEY值，由开发者在创建菜单时设定 'scancodeinfo' => array( // 扫描信息 'scanresult' => '2' // 扫描结果，即二维码对应的字符串信息 'scantype' => 'qrcode' // 扫描类型，一般是qrcode 'eventkey' => )) ~~~ ##### 弹出系统拍照发图 ~~~ $view_message = array( 'tousername' => 'toUser' 'fromusername' => 'fromUser' 'createtime' => '123456789' 'msgtype' => 'event' 'eventkey' => '' // 事件KEY值，由开发者在创建菜单时设定 'sendpicsinfo' => array( // 发送的图片信息 'count' => '1' // 发送的图片数量 'piclist' => array( // 图片列表 '0' => '' // 图片的MD5值，开发者若需要，可用于验证接收到图片 ) )) ~~~ ##### 弹出拍照或者相册发图 ~~~ $view_message = array( 'tousername' => 'toUser' 'fromusername' => 'fromUser' 'createtime' => '123456789' 'msgtype' => 'event' 'eventkey' => '' // 事件KEY值，由开发者在创建菜单时设定 'sendpicsinfo' => array( // 发送的图片信息 'count' => '1' // 发送的图片数量 'piclist' => array( // 图片列表 '0' => '' // 图片的MD5值，开发者若需要，可用于验证接收到图片 ) )) ~~~ ##### 弹出微信相册发图器 ~~~ $view_message = array( 'tousername' => 'toUser' 'fromusername' => 'fromUser' 'createtime' => '123456789' 'msgtype' => 'event' 'eventkey' => '' // 事件KEY值，由开发者在创建菜单时设定 'sendpicsinfo' => array( // 发送的图片信息 'count' => '1' // 发送的图片数量 'piclist' => array( // 图片列表 '0' => '' // 图片的MD5值，开发者若需要，可用于验证接收到图片 ) )) ~~~ ##### 弹出地理位置选择器 ~~~ $view_message = array( 'tousername' => 'toUser' 'fromusername' => 'fromUser' 'createtime' => '123456789' 'msgtype' => 'event' 'eventkey' => '' // 事件KEY值，由开发者在创建菜单时设定 'sendlocationinfo' => array( // 发送的位置信息 'location_x' => '' // X坐标信息 'location_y' => ''// Y坐标信息 'scale' => '' // 精度，可理解为精度或者比例尺、越精细的话 scale越高 'label' => '' // 地理位置的字符串信息 'poiname' => ''// 朋友圈POI的名字，可能为空 'eventkey' => )) ~~~ ##### 获取用户地理位置用户同意上报地理位置后，每次进入公众号会话时，都会在进入时上报地理位置，上报地理位置以推送XML数据包到开发者填写的URL来实现. ~~~ $message = array( 'tousername' => 'toUser' 'fromusername' => 'fromUser' 'createtime' => '123456789' 'msgtype' => 'event' 'latitude' => '' // 地理位置纬度 'longitude' => '' // 地理位置经度 'precision' => '' // 地理位置精度 'location_x' => '' 'location_y' => '') ~~~ ##### 点击菜单拉取消息时的事件推送 ~~~ $message = array( 'from' => 'FromUser' 'to' => 'toUser' 'time' => '123456789' 'type' => 'event' 'event' => 'CLICK' // 事件类型，CLICK 'tousername' => 'toUser' 'fromusername' => 'FromUser' 'createtime' => '' 'msgtype' => 'event' 'eventkey' => 'EVENTKEY' // 事件KEY值，与自定义菜单接口中KEY值对应) ~~~