[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值對應
)
~~~
#### 什么是消息響應？
1. 粉絲用用微信給公眾號發送信息
2. 公眾平臺將粉絲用戶的 **請求消息**((當前包括: 文本, 圖片, 位置, 鏈接, 事件. 請參閱消息類型)) 傳遞給微擎系統（數據為XML格式）
3. 微擎系統按照 **消息類型** 和對應的公眾號所設定的 規則列表 匹配到合適的 規則(請參閱消息路由),規則定義包括處理此消息所使用的模塊和此模塊處理消息時所需要的其他附加數據(請參閱模塊定義)
4. 模塊將按照請求的 **消息數據** 和 **模塊附加數據** 進行相關業務處理并返回處理結果(請參閱響應類型),
5. 微擎系統將處理結果返回給公眾平臺
6. 公眾平臺將結果再次返回給粉絲用戶
如下圖所示：
（微擎的主處理流程實現定義于: **api.php** 中的 class **WeEngine**, 如有需要請參閱源碼.）
#### 消息的路由
**消息路由** 是指粉絲用戶經公眾平臺發送消息內容至微擎時, 微擎系統查找對應的規則記錄, 并將消息分配至合適的模塊處理的過程.
微擎系統按照不同的消息類型, 進行不同的處理. 處理方式如下:
##### 上下文消息路由
微擎支持上下文操作.
通過上下文支持微擎可將用戶對話鎖定至特定的模塊, 如果當前消息是上下文對話的消息, 那么將會自動路由至上下文鎖定的模塊. (請參閱 上[下文處理](http://www.hmoore.net/donknap/we7/134689))
##### 文本消息規則匹配(重要)
針對文本消息, 微擎使用文本匹配來選擇合適的規則和模塊, 規則是針對特定消息的處理方式. 微擎選擇規則的方式包括:
* **關鍵字包含** 指粉絲用戶發送的消息內容 **含有** 指定的關鍵字就指派到特定規則.
* **內容等價** 指粉絲用戶發送的消息內容 **完全等于** 指定的內容才指派到特定規則.
* **正則表達式** 指粉絲用戶發送的消息類型 **符合指定正則** 表達式定義的模式時指派到特定規則.(高級模式, 需要有編程經驗)
##### 系統回復
**系統回復**為系統內置的兩種回復類型包括 **歡迎信息回復、默認回復**。歡迎信息為用戶關注時觸發的消息回復，默認回復為未匹配到關鍵字時的消息回復。
##### 特殊消息路由
**特殊消息路由** 是指除 **文本消息** 之外的消息類型，包括 **圖片消息**、**語音消息** 、**視頻消息**、 **小視頻消息**、 **位置消息**、 **上報地理位置**、 **鏈接消息**、**進入聊天窗口**、**微小店消息** 設置特殊消息接管后，用戶發來此類消息優先會路由至該消息的處理模塊中。評情請見【基礎設置】- 【特殊回復】-【特殊消息類型處理】
