# 接收消息和事件 <br> [<h2>微信客服官方API文档入口</h2>](https://open.work.weixin.qq.com/kf/doc/92512/93143/93304) <br> <br> [TOC] ## 概述 微信客服服务器会将事件的回调数据包发送到企业指定URL；企业收到请求后，再通过获取消息接口主动获取具体的消息内容。 整体交互示意图如下图所示。  ## 回调事件 接收并解析事件的方法见：[回调配置](https://www.kancloud.cn/wikizhima/wechatkf-api/2376702)。 **示例** ~~~ <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/wikizhima/wechatkf-api/2376731)接口发送失败事件（如被用户拒收）、客户点击菜单消息的回复消息，可以通过该接口获取具体的消息内容和事件。**不支持获取通过接口发送的消息**。 **支持的消息类型：**文本、图片、语音、视频、文件、位置、事件。 ### 接口定义 **请求方式**: 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://open.work.weixin.qq.com/kf/doc/92512/93143/94745#25217/%E8%8F%9C%E5%8D%95%E6%B6%88%E6%81%AF)，触发的回复消息中附带的菜单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/wikizhima/wechatkf-api/2376729)开发者自定义的场景值 | ##### 消息发送失败事件 **返回示例：** ~~~ { "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-用户拒收 | <br> <br> ## 微信客服第三方服务商 - 芝麻客服接入指南 <br> 1. 登陆 [芝麻客服官网](https://xiaokefu.com.cn/index/wechatkefu)，点击 [一键接入微信客服组件](https://xiaokefu.com.cn/app/selectionWechatKf)。 </h>  </h> </h> 2. 点击 下一步 ，然后企业微信管理员扫码即可。 </h>  </h> </h>