[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, 公众平台系统用于唯一标识一条请求消息
);
~~~
微擎系统会通过这个消息结构数组，使用 **规则** 和 **模块** 的机制来处理公众平台的请求数据并返回响应的结果，具体请参看下一章“[消息响应](https://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值对应
)
~~~
#### 什么是消息响应？
1. 粉丝用用微信给公众号发送信息
2. 公众平台将粉丝用户的 **请求消息**((当前包括: 文本, 图片, 位置, 链接, 事件. 请参阅消息类型)) 传递给微擎系统（数据为XML格式）
3. 微擎系统按照 **消息类型** 和对应的公众号所设定的 规则列表 匹配到合适的 规则(请参阅消息路由),规则定义包括处理此消息所使用的模块和此模块处理消息时所需要的其他附加数据(请参阅模块定义)
4. 模块将按照请求的 **消息数据** 和 **模块附加数据** 进行相关业务处理并返回处理结果(请参阅响应类型),
5. 微擎系统将处理结果返回给公众平台
6. 公众平台将结果再次返回给粉丝用户
如下图所示：
（微擎的主处理流程实现定义于: **api.php** 中的 class **WeEngine**, 如有需要请参阅源码.）
#### 消息的路由
**消息路由** 是指粉丝用户经公众平台发送消息内容至微擎时, 微擎系统查找对应的规则记录, 并将消息分配至合适的模块处理的过程.
微擎系统按照不同的消息类型, 进行不同的处理. 处理方式如下:
##### 上下文消息路由
微擎支持上下文操作.
通过上下文支持微擎可将用户对话锁定至特定的模块, 如果当前消息是上下文对话的消息, 那么将会自动路由至上下文锁定的模块. (请参阅 上[下文处理](https://www.kancloud.cn/donknap/we7/134689))
##### 文本消息规则匹配(重要)
针对文本消息, 微擎使用文本匹配来选择合适的规则和模块, 规则是针对特定消息的处理方式. 微擎选择规则的方式包括:
* **关键字包含** 指粉丝用户发送的消息内容 **含有** 指定的关键字就指派到特定规则.
* **内容等价** 指粉丝用户发送的消息内容 **完全等于** 指定的内容才指派到特定规则.
* **正则表达式** 指粉丝用户发送的消息类型 **符合指定正则** 表达式定义的模式时指派到特定规则.(高级模式, 需要有编程经验)
##### 系统回复
**系统回复**为系统内置的两种回复类型包括 **欢迎信息回复、默认回复**。欢迎信息为用户关注时触发的消息回复，默认回复为未匹配到关键字时的消息回复。
##### 特殊消息路由
**特殊消息路由** 是指除 **文本消息** 之外的消息类型，包括 **图片消息**、**语音消息** 、**视频消息**、 **小视频消息**、 **位置消息**、 **上报地理位置**、 **链接消息**、**进入聊天窗口**、**微小店消息** 设置特殊消息接管后，用户发来此类消息优先会路由至该消息的处理模块中。评情请见【基础设置】- 【特殊回复】-【特殊消息类型处理】
