發送消息 · 企微客服開發

[TOC] ## 概述當用戶在主動發送消息給微信客服時，企業可在48小時內調用該接口發送消息給用戶，最多可發送5條消息給客戶；若用戶繼續發送消息，企業可再次下發消息。支持發送消息類型：文本、圖片、語音、視頻、文件、圖文、小程序、菜單消息、地理位置。目前該接口允許下發消息條數和下發時限如下： | 用戶動作 | 允許下發條數限制 | 下發時限 | | --- | --- | --- | | 用戶發送消息 | 5條 | 48 小時 | ## 接口定義 **請求方式**: POST(**HTTPS**) **請求地址**: https://qyapi.weixin.qq.com/cgi-bin/kf/send\_msg?access\_token=ACCESS\_TOKEN **參數說明：** | 參數 | 是否必須 | 說明 | | --- | --- | --- | | access\_token | 是 | 調用接口憑證 | **權限說明**: 僅允許微信客服的Secret所獲取的access\_token調用。 **返回結果**: ~~~ { "errcode": 0, "errmsg": "ok", "msgid": "MSG_ID"} ~~~ **參數說明**: | 參數 | 類型 | 說明 | | --- | --- | --- | | errcode | int32 | 返回碼 | | errmsg | string | 錯誤碼描述 | | msgid | string | 消息ID。如果請求參數指定了msgid，則原樣返回，否則系統自動生成并返回。不多于32字節字符串取值范圍(正則表達式)：\[0-9a-zA-Z\_-\]\* | ## 消息類型 ### 文本消息 **請求示例：** ~~~ { "touser" : "EXTERNAL_USERID", "open_kfid": "OPEN_KFID", "msgid": "MSGID", "msgtype" : "text", "text" : { "content" : "你購買的物品已發貨，可點擊鏈接查看物流狀態http://work.weixin.qq.com/xxxxxx" }} ~~~ **參數說明：** | 參數 | 是否必須 | 類型 | 說明 | | --- | --- | --- | --- | | touser | 是 | string | 指定接收消息的客戶UserID | | open\_kfid | 是 | string | 指定發送消息的客服帳號ID | | msgid | 否 | string | 指定消息ID | | msgtype | 是 | string | 消息類型，此時固定為：text | | text | 是 | obj | 文本消息 | | text.content | 是 | string | 消息內容，最長不超過2048個字節 | ### 圖片消息 **請求示例：** ~~~ { "touser" : "EXTERNAL_USERID", "open_kfid": "OPEN_KFID", "msgid": "MSGID", "msgtype" : "image", "image" : { "media_id" : "MEDIA_ID" }} ~~~ **請求參數：** | 參數 | 是否必須 | 類型 | 說明 | | --- | --- | --- | --- | | touser | 是 | string | 指定接收消息的客戶UserID | | open\_kfid | 是 | string | 指定發送消息的客服帳號ID | | msgid | 否 | string | 指定消息ID | | msgtype | 是 | string | 消息類型，此時固定為：image | | image | 是 | obj | 圖片消息 | | image.media\_id | 是 | string | 圖片文件id，可以調用上傳臨時素材接口獲取 | ### 語音消息 **請求示例：** ~~~ { "touser" : "EXTERNAL_USERID", "open_kfid": "OPEN_KFID", "msgtype" : "voice", "voice" : { "media_id" : "MEDIA_ID" }} ~~~ **參數說明：** | 參數 | 是否必須 | 類型 | 說明 | | --- | --- | --- | --- | | touser | 是 | string | 指定接收消息的客戶UserID | | open\_kfid | 是 | string | 指定發送消息的客服帳號ID | | msgid | 否 | string | 指定消息ID | | msgtype | 是 | string | 消息類型，此時固定為：voice | | voice | 是 | obj | 語音消息 | | voice.media\_id | 是 | string | 語音文件id，可以調用[上傳臨時素材](http://www.hmoore.net/dabashan/qiwei/2376081#_7)接口獲取 | ### 視頻消息 **請求示例：** ~~~ { "touser" : "EXTERNAL_USERID", "open_kfid": "OPEN_KFID", "msgid": "MSGID", "msgtype" : "video", "video" : { "media_id" : "MEDIA_ID" }} ~~~ **參數說明：** | 參數 | 是否必須 | 類型 | 說明 | | --- | --- | --- | --- | | touser | 是 | string | 指定接收消息的客戶UserID | | open\_kfid | 是 | string | 指定發送消息的客服帳號ID | | msgid | 否 | string | 指定消息ID | | msgtype | 是 | string | 消息類型，此時固定為：video | | video | 是 | obj | 視頻消息 | | video.media\_id | 是 | string | 視頻媒體文件id，可以調用[上傳臨時素材](http://www.hmoore.net/dabashan/qiwei/2376081#_7)接口獲取 | **視頻消息展現：** ![](https://wework.qpic.cn/wwpic/37380_BQj_gw5DTTO9ZMe_1607675511/0) ### 文件消息 **請求示例：** ~~~ { "touser" : "EXTERNAL_USERID", "open_kfid": "OPEN_KFID", "msgid": "MSGID", "msgtype" : "file", "file" : { "media_id" : "1Yv-zXfHjSjU-7LH-GwtYqDGS-zz6w22KmWAT5COgP7o" }} ~~~ **參數說明：** | 參數 | 是否必須 | 類型 | 說明 | | --- | --- | --- | --- | | touser | 是 | string | 指定接收消息的客戶UserID | | open\_kfid | 是 | string | 指定發送消息的客服帳號ID | | msgid | 否 | string | 指定消息ID | | msgtype | 是 | string | 消息類型，此時固定為：file | | file | 是 | obj | 文件消息 | | file.media\_id | 是 | string | 文件id，可以調用上傳臨時素材接口獲取 | **文件消息展現：** ![](https://wework.qpic.cn/wwpic/612797_YXO-yFo_Ro2WUh9_1607675547/0) ### 圖文鏈接消息 **請求示例：** ~~~ { "touser" : "EXTERNAL_USERID", "open_kfid": "OPEN_KFID", "msgid": "MSGID", "msgtype" : "link", "link" : { "title" : "企業如何增長？企業微信給出3個答案", "desc" : "今年中秋節公司有豪禮相送", "url" : "URL", "thumb_media_id": "MEDIA_ID" }} ~~~ **參數說明：** | 參數 | 是否必須 | 類型 | 說明 | | --- | --- | --- | --- | | touser | 是 | string | 指定接收消息的客戶UserID | | open\_kfid | 是 | string | 指定發送消息的客服帳號ID | | msgid | 否 | string | 指定消息ID | | msgtype | 是 | string | 消息類型，此時固定為：link | | link | 是 | obj | 鏈接消息 | | link.title | 是 | string | 標題，不超過128個字節，超過會自動截斷 | | link.desc | 否 | string | 描述，不超過512個字節，超過會自動截斷 | | link.url | 是 | string | 點擊后跳轉的鏈接。最長2048字節，請確保包含了協議頭(http/https) | | link.thumb\_media\_id | 是 | string | 縮略圖的media\_id, 可以通過[素材管理](http://www.hmoore.net/dabashan/qiwei/2376081)接口獲得。此處thumb\_media\_id即上傳接口返回的media\_id | **圖文鏈接消息展現：** ![](https://wework.qpic.cn/wwpic/769240_nKJEoW7cQf61BJw_1607675399/0) ### 小程序消息 **請求示例：** ~~~ { "touser" : "EXTERNAL_USERID", "open_kfid": "OPEN_KFID", "msgid": "MSGID", "msgtype" : "miniprogram" "miniprogram" : { "appid": "APPID", "title": "歡迎報名夏令營", "thumb_media_id": "MEDIA_ID", "pagepath": "PAGE_PATH" }} ~~~ **參數說明：** | 參數 | 是否必須 | 類型 | 說明 | | --- | --- | --- | --- | | touser | 是 | string | 指定接收消息的客戶UserID | | open\_kfid | 是 | string | 指定發送消息的客服帳號ID | | msgid | 否 | string | 指定消息ID | | msgtype | 是 | string | 消息類型，此時固定為：miniprogram | | miniprogram | 是 | obj | 小程序消息 | | miniprogram.appid | 是 | string | 小程序appid，必須是關聯到企業的小程序應用 | | miniprogram.title | 否 | string | 小程序消息標題，最多64個字節，超過會自動截斷 | | miniprogram.thumb\_media\_id | 是 | string | 小程序消息封面的mediaid，封面圖建議尺寸為520\*416 | | miniprogram.pagepath | 是 | string | 點擊消息卡片后進入的小程序頁面路徑。注意路徑要以.html為后綴，否則在微信中打開會提示找不到頁面 | ### 菜單消息 **請求示例：** ~~~ { "touser": "EXTERNAL_USERID", "open_kfid": "OPEN_KFID", "msgid": "MSGID", "msgtype": "msgmenu", "msgmenu": { "head_content": "您對本次服務是否滿意呢? ", "list": [ { "type": "click", "click": { "id": "101", "content": "滿意" } }, { "type": "click", "click": { "id": "102", "content": "不滿意" } }, { "type": "view", "view": { "url": "https://work.weixin.qq.com", "content": "點擊跳轉到自助查詢頁面" } }, { "type": "miniprogram", "miniprogram": { "appid": "wx123123123123123", "pagepath": "pages/index?userid=zhangsan&orderid=123123123", "content": "點擊打開小程序查詢更多" } } ], "tail_content": "歡迎再次光臨" }} ~~~ **參數說明：** | 參數 | 必須 | 類型 | 說明 | | --- | --- | --- | --- | | touser | 是 | string | 指定接收消息的客戶UserID | | open\_kfid | 是 | string | 指定發送消息的客服帳號ID | | msgid | 否 | string | 指定消息ID | | msgtype | 是 | string | 消息類型，此時固定為：msgmenu | | msgmenu | 是 | obj | 菜單消息 | | msgmenu.head\_content | 否 | string | 起始文本不多于1024字節 | | msgmenu.list | 否 | obj\[\] | 菜單項配置 | | msgmenu.list.type | 是 | string | 菜單類型。 `click`\-回復菜單`view`\-超鏈接菜單`miniprogram`\-小程序菜單 | | msgmenu.list.click | 否 | obj | type為`click`的菜單項 | | msgmenu.list.click.id | 否 | string | 菜單ID。不少于1字節不多于64字節 | | msgmenu.list.click.content | 是 | string | 菜單顯示內容不少于1字節不多于128字節 | | msgmenu.list.view | 否 | obj | type為`view`的菜單項 | | msgmenu.list.view.url | 是 | string | 點擊后跳轉的鏈接。不少于1字節不多于2048字節 | | msgmenu.list.view.content | 是 | string | 菜單顯示內容。不少于1字節不多于1024字節 | | msgmenu.list.miniprogram | 否 | obj | type為`miniprogram`的菜單項 | | msgmenu.list.miniprogram.appid | 是 | string | 小程序appid。不少于1字節不多于32字節 | | msgmenu.list.miniprogram.pagepath | 是 | string | 點擊后進入的小程序頁面。不少于1字節不多于1024字節 | | msgmenu.list.miniprogram.content | 是 | string | 菜單顯示內容。不多于1024字節 | | msgmenu.tail\_content | 否 | string | 結束文本不多于1024字節 | 其中，“滿意”和“不滿意”兩個菜單當用戶點擊后，用戶會自動回復一條文本消息，同時附帶對應的菜單ID。 **菜單消息展現：** ![](https://wwcdn.weixin.qq.com/node/wework/images/msgmenu_sample.png) ### 地理位置消息 **請求示例：** ~~~ { "touser" : "EXTERNAL_USERID", "open_kfid": "OPEN_KFID", "msgid": "MSGID", "msgtype" : "location", "location": { "name": "測試小區", "address": "實例小區，不真實存在，經緯度無意義", "latitude": 0, "longitude": 0 }} ~~~ **參數說明：** | 參數 | 是否必須 | 類型 | 說明 | | --- | --- | --- | --- | | touser | 是 | string | 指定接收消息的客戶UserID | | open\_kfid | 是 | string | 指定發送消息的客服帳號ID | | msgid | 否 | string | 指定消息ID | | msgtype | 是 | string | 消息類型，此時固定為：location | | location | 是 | obj | 地理位置消息 | | location.name | 否 | string | 位置名 | | location.address | 否 | string | 地址詳情說明 | | location.latitude | 是 | float | 緯度，浮點數，范圍為90 ~ -90 | | location.longitude | 是 | float | 經度，浮點數，范圍為180 ~ -180 |