消息概述 · 微擎

[TOC] ####消息概述用户发送给公众号的信息，包括文本、语音、视频、位置、图片等等，统称为消息。系统在接收到这些消息时，会转化为消息的数据结构，然后进行相应的解析、分发、响应。 #### 消息结构 ``` <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值对应 ) ```