接收消息和事件 · 企微客服開發

# 接收消息和事件 [TOC] ## 概述微信客服服務器會將事件的回調數據包發送到企業指定URL；企業收到請求后，再通過獲取消息接口主動獲取具體的消息內容。整體交互示意圖如下圖所示。 ![](https://wework.qpic.cn/wwpic/638423_eiQfriAYRAyYzRY_1625631158/0) ## 回調事件接收并解析事件的方法見：[回調配置](http://www.hmoore.net/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，用于校驗請求的合法性 | ## 獲取消息客戶主動發給微信客服的消息、[發送消息](http://www.hmoore.net/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 | 客戶點擊[菜單消息](http://www.hmoore.net/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 | 進入會話的場景值，[獲取客服帳號鏈接](http://www.hmoore.net/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-用戶拒收 |