消息概述 · 微擎

[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.hmoore.net/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值對應 ) ```