# 接收消息和事件
[TOC]
## 概述
微信客服服务器会将事件的回调数据包发送到企业指定URL；企业收到请求后，再通过获取消息接口主动获取具体的消息内容。
整体交互示意图如下图所示。
## 回调事件
接收并解析事件的方法见：[回调配置](https://www.kancloud.cn/dabashan/qiwei/2376066#_55)。
**示例**
~~~
<xml> <ToUserName><![CDATA[ww12345678910]]></ToUserName> <CreateTime>1348831860</CreateTime> <MsgType><![CDATA[event]]></MsgType> <Event><![CDATA[kf_msg_or_event]]></Event> <Token><![CDATA[ENCApHxnGDNAVNY4AaSJKj4Tb5mwsEMzxhFmHVGcra996NR]]></Token></xml>
~~~
**说明**
| 参数 | 说明 |
| --- | --- |
| ToUserName | 微信客服组件ID |
| CreateTime | 消息创建时间，unix时间戳 |
| MsgType | 消息的类型，此时固定为 event |
| Event | 事件的类型，此时固定为 kf\_msg\_or\_event |
| Token | 调用拉取消息接口时，需要传此token，用于校验请求的合法性 |
## 获取消息
客户主动发给微信客服的消息、[发送消息](https://www.kancloud.cn/dabashan/qiwei/2376075)接口发送失败事件（如被用户拒收）、客户点击菜单消息的回复消息，可以通过该接口获取具体的消息内容和事件。**不支持获取通过接口发送的消息**。
**支持的消息类型：**文本、图片、语音、视频、文件、位置、事件。
### 接口定义
**请求方式**: POST(**HTTPS**)
**请求地址:**https://qyapi.weixin.qq.com/cgi-bin/kf/sync\_msg?access\_token=ACCESS\_TOKEN
**请求示例**
~~~
{ "cursor": "4gw7MepFLfgF2VC5npN", "token": "ENCApHxnGDNAVNY4AaSJKj4Tb5mwsEMzxhFmHVGcra996NR", "limit": 1000}
~~~
**参数说明**:
| 参数 | 必须 | 类型 | 说明 |
| --- | --- | --- | --- |
| access\_token | 是 | string | 调用接口凭证 |
| cursor | 否 | string | 上一次调用时返回的next\_cursor，第一次拉取可以不填。
不多于64字节 |
| token | 否 | string | 回调事件返回的`token`字段，10分钟内有效；可不填，如果不填接口有严格的频率限制。
不多于128字节 |
| limit | 否 | uint32 | 期望请求的数据量，默认值和最大值都为1000。
**注意：可能会出现返回条数少于limit的情况，需结合返回的`has_more`字段判断是否继续请求。** |
**权限说明**:
仅允许微信客服组件的Secret所获取的access\_token调用。
**返回结果**:
~~~
{ "errcode": 0, "errmsg": "ok", "next_cursor": "4gw7MepFLfgF2VC5npN", "has_more": 1, "msg_list": [ { "msgid": "from_msgid_4622416642169452483", "open_kfid": "wkAJ2GCAAASSm4_FhToWMFea0xAFfd3Q", "external_userid": "wmAJ2GCAAAme1XQRC-NI-q0_ZM9ukoAw", "send_time": 1615478585, "origin": 3, "msgtype": "MSG_TYPE" } ]}
~~~
**参数说明**:
| 参数 | 类型 | 说明 |
| --- | --- | --- |
| errcode | int32 | 返回码 |
| errmsg | string | 错误码描述 |
| next\_cursor | string | 下次调用带上该值则从该key值往后拉，用于增量拉取 |
| has\_more | uint32 | 是否还有更多数据。0-否；1-是。
**不能通过判断msg\_list是否空来停止拉取**，可能会出现has\_more为1，而msg\_list为空的情况 |
| msg\_list | obj\[\] | 消息列表 |
| msg\_list.msgid | string | 消息ID |
| msg\_list.open\_kfid | string | 客服帐号ID |
| msg\_list.external\_userid | string | 客户UserID |
| msg\_list.send\_time | uint64 | 消息发送时间 |
| msg\_list.origin | uint32 | 消息来源。3-客户回复的消息 4-系统推送的消息 |
| msg\_list.msgtype | string | 对不同的msgtype，有相应的结构描述，下面进一步说明 |
### 消息类型
#### 文本消息
**返回示例：**
~~~
{ "msgtype" : "text", "text" : { "content" : "hello world", "menu_id" : "MENU_ID" }}
~~~
**参数说明：**
| 参数 | 类型 | 说明 |
| --- | --- | --- |
| msgtype | string | 消息类型，此时固定为：text |
| text | obj | 文本消息 |
| text.content | string | 文本内容 |
| text.menu\_id | string | 客户点击[菜单消息](https://www.kancloud.cn/dabashan/qiwei/2376075#_193)，触发的回复消息中附带的菜单ID |
#### 图片消息
**返回示例：**
~~~
{ "msgtype" : "image", "image" : { "media_id" : "2iSLeVyqzk4eX0IB5kTi9Ljfa2rt9dwfq5WKRQ4Nvvgw" }}
~~~
**参数说明：**
| 参数 | 类型 | 说明 |
| --- | --- | --- |
| msgtype | string | 消息类型，此时固定为：image |
| image | obj | 图片消息 |
| image.media\_id | string | 图片文件id |
#### 语音消息
**返回示例：**
~~~
{ "msgtype" : "voice", "voice" : { "media_id" : "2iSLeVyqzk4eX0IB5kTi9Ljfa2rt9dwfq5WKRQ4Nvvgw" }}
~~~
**参数说明：**
| 参数 | 类型 | 说明 |
| --- | --- | --- |
| msgtype | string | 消息类型，此时固定为：voice |
| voice | obj | 语音消息 |
| voice.media\_id | string | 语音文件ID |
#### 视频消息
**返回示例：**
~~~
{ "msgtype" : "video", "video" : { "media_id" : "2iSLeVyqzk4eX0IB5kTi9Ljfa2rt9dwfq5WKRQ4Nvvgw" }}
~~~
**参数说明：**
| 参数 | 类型 | 说明 |
| --- | --- | --- |
| msgtype | string | 消息类型，此时固定为：video |
| video | obj | 视频消息 |
| video.media\_id | string | 文件id |
#### 文件消息
**返回示例：**
~~~
{ "msgtype" : "file", "file" : { "media_id" : "2iSLeVyqzk4eX0IB5kTi9Ljfa2rt9dwfq5WKRQ4Nvvgw" }}
~~~
**参数说明：**
| 参数 | 类型 | 说明 |
| --- | --- | --- |
| msgtype | string | 消息类型，此时固定为：file |
| file | obj | 文件消息 |
| file.media\_id | string | 文件id |
#### 位置消息
**返回示例：**
~~~
{ "msgtype" : "location", "location" : { "latitude": 23.106021881103501, "longitude": 113.320503234863, "name": "广州国际媒体港(广州市海珠区)", "address": "广东省广州市海珠区滨江东路" }}
~~~
**参数说明：**
| 参数 | 类型 | 说明 |
| --- | --- | --- |
| msgtype | string | 消息类型，此时固定为：location |
| location | obj | 地理位置消息 |
| location.latitude | float | 纬度 |
| location.longitude | float | 经度 |
| location.name | string | 位置名 |
| location.address | string | 地址详情说明 |
#### 事件消息
##### 用户进入会话事件
**返回示例：**
~~~
{ "msgtype" : "event", "event" : { "event_type": "enter_session", "open_kfid": "wkAJ2GCAAASSm4_FhToWMFea0xAFfd3Q", "external_userid": "wmAJ2GCAAAme1XQRC-NI-q0_ZM9ukoAw", "scene": "123" }}
~~~
**参数说明：**
| 参数 | 类型 | 说明 |
| --- | --- | --- |
| msgtype | string | 消息类型，此时固定为：event |
| event | obj | 事件消息 |
| event.event\_type | string | 事件类型。此处固定为：enter\_session |
| event.open\_kfid | string | 客服账号ID |
| event.external\_userid | string | 客户UserID |
| event.scene | string | 进入会话的场景值，[获取客服帐号链接](https://www.kancloud.cn/dabashan/qiwei/2376072)开发者自定义的场景值 |
##### 消息发送失败事件
**返回示例：**
~~~
{ "msgtype" : "event", "event" : { "event_type": "msg_send_fail", "open_kfid": "wkAJ2GCAAASSm4_FhToWMFea0xAFfd3Q", "external_userid": "wmAJ2GCAAAme1XQRC-NI-q0_ZM9ukoAw", "fail_msgid": "FAIL_MSGID", "fail_type": 4 }}
~~~
**参数说明：**
| 参数 | 类型 | 说明 |
| --- | --- | --- |
| msgtype | string | 消息类型，此时固定为：event |
| event | obj | 事件消息 |
| event.event\_type | string | 事件类型。此处固定为：msg\_send\_fail |
| event.open\_kfid | string | 客服帐号ID |
| event.external\_userid | string | 客户UserID |
| event.fail\_msgid | string | 发送失败的消息msgid |
| event.fail\_type | uint32 | 失败类型。0-未知原因 10-用户拒收 |
