客服消息使用指南

為豐富小程序的服務能力，提高服務質量，微信為小程序提供客服消息能力，以便小程序用戶可以方便快捷地與小程序服務提供方進行溝通。

功能介紹

用戶可使用小程序客服消息功能，與小程序的客服人員進行溝通。

客服消息會話入口有兩個：

1、小程序內：開發者在小程序內添加客服消息按鈕組件，用戶可在小程序內喚起客服會話頁面，給小程序發消息；

2、已使用過的小程序客服消息會聚合顯示在微信會話「小程序客服消息」盒子內，用戶可以在小程序外查看歷史客服消息，并給小程序發送消息。

客服消息下發條件：小程序用戶在小程序內喚起客服會話或用戶給小程序客服發送消息，具體下發時間有效期及消息條數限制見客服消息下發條件說明

客服消息類型：目前支持文本、圖片、小程序卡片類型消息。

為盡量滿足小程序開發者的需求，小程序可通過以下3種方式下發客服消息：1. 調用發送客服消息接口；2. 使用網頁端客服工具；3. 使用移動端「客服小助手」小程序。

下發條件說明

當用戶和小程序客服產生特定動作的交互時（具體動作列表請見下方說明），小程序可向用戶下發客服消息。

目前允許的動作列表如下，不同動作觸發后，允許下發消息條數和下發時限不同。下發條數達到上限后，會返回錯誤碼。

可發送客服消息條數不累加，上述用戶動作會觸發可下發條數及可下發時限的更新，可下發消息條數更新為當前可下發條數限制的最大值，有效下發時間限制也更新為最長有效時間。

調用客服消息接口發送客服消息

當用戶給小程序客服發消息，微信服務器會將消息（或事件）的數據包（JSON或者XML格式）POST到開發者填寫的URL。開發者收到請求后可以調用接口進行異步回復。

如小程序的客服消息權限集已授權給第三方平臺，則所有的客服消息將推送到第三方平臺的服務器，不再推送到開發者的服務器或推送到網頁版客服工具

填寫消息推送配置

登錄小程序，在“設置-開發設置-消息推送”啟用消息推送功能并完成相關信息配置（包括服務器地址、Token、及加密方式等）。

啟用并設置服務器配置后，用戶發送的消息以及開發者需要的事件推送，都將被微信轉發至開發者URL中。

接口調用

小程序客服消息API文檔

網頁端客服工具與移動端小程序客服工具

小程序也可以直接使用網頁端微信小程序客服或者移動端「客服小助手」小程序進行客服消息回復。

客服小助手小程序碼

若小程序沒有啟用消息推送，則用戶發送的消息將會被轉發至網頁端微信小程序客服和移動端「客服小助手」，客服人員可在網頁端微信小程序客服和移動端「客服小助手」中接入并回復用戶。

如小程序的客服消息權限集已授權給第三方平臺，則所有的客服消息將推送到第三方平臺的服務器，不再推送到開發者的服務器或推送到網頁版客服工具。

注意：“用戶通過客服消息按鈕進入會話”事件將不會轉發至網頁端客服工具。

綁定客服人員

使用網頁端與移動端小程序客服工具前，小程序管理員需在小程序后臺完成客服人員的綁定。目前小程序支持綁定不多于100個客服人員。

移動端「客服小助手」小程序使用說明

登錄并接入

已被綁定的小程序客服人員可微信搜索「客服小助手」或掃碼登錄「客服小助手」小程序，并選擇對應的小程序賬號，登錄后即可看到與小程序對話的用戶，可選擇接入對話。

切換客服狀態

點擊在線狀態，可以選擇客服在線狀態、客服離線狀態： 選擇客服在線狀態后，即使退出客服小程序，仍可在“服務通知”中接收到用戶咨詢的消息提醒； 選擇客服離線狀態后，將無法收到客服消息與消息提醒。

接收與發送消息

打開「客服小助手」小程序后，進入“待接入列表”可選擇用戶會話進行接入； 已經接入的會話，客服人員可以在48小時內和用戶進行對話，目前支持發送文本、圖片、小程序卡片類型的消息。

網頁端微信小程序客服工具使用說明

登錄并接入

已被綁定的小程序客服人員可掃碼登錄網頁端微信小程序客服，并選擇對應的小程序賬號，登錄后即可看到與小程序對話的用戶，可選擇接入對話。

切換客服狀態

點擊在線狀態，可以選擇在線狀態、離線狀態

接收消息

手動接入：客服人員上線后，可在“待接入”列表中，手動接入待回復的用戶會話。

自動接入：當待接入的用戶會話太多時，可以在設置-接入與回復中，開啟自動接入。

發送消息

已經接入的會話，客服人員可以在48小時內和用戶進行對話，目前支持發送文本、圖片、小程序卡片類型的消息。

使用規范

小程序客服消息使用除必須遵守《微信小程序平臺運營規范》外，還不能違反以下規則，包括但不限于：

1. 不允許惡意誘導用戶進行可能觸發客服消息下發的操作，以達到可向用戶下發客服消息目的
2. 不允許惡意騷擾，下發與用戶發送的消息沒有關聯的、對用戶造成騷擾的消息
3. 不允許惡意營銷，下發內容涉嫌虛假夸大、違法類營銷信息
4. 不允許使用客服消息向用戶下發虛假、色情、暴力等違反國家法律規定的信息

客服消息開發文檔

客服消息

在頁面使用客服消息

需要將 button 組件 open-type 的值設置為 contact，當用戶點擊后就會進入客服會話，如果用戶在會話中點擊了小程序消息，則會返回到小程序，開發者可以通過 bindcontact 事件回調獲取到用戶所點消息的頁面路徑 path 和對應的參數 query，此外，開發者可以通過設置 session-from 將會話來源透傳到客服。

示例代碼

<button open-type="contact" bindcontact="handleContact" session-from="sessionFrom"></button>

Page({
    handleContact (e) {
        console.log(e.detail.path)
        console.log(e.detail.query)
    }
})

返回參數說明

后臺接入消息服務

用戶向小程序客服發送消息、或者進入會話等情況時，開發者填寫的服務器 URL （如果使用的是云開發，則是配置的云函數）將得到微信服務器推送過來的消息和事件，開發者可以依據自身業務邏輯進行響應。接入和使用方式請參考消息推送。

后臺接入消息報錯自查

報錯表現

用戶發送消息出現系統文案 “該小程序提供的服務出現故障，請稍后再試”。

報錯原因

小程序配置callback后，用戶發送的消息會推送到第三方服務器，如推送失敗就會報錯。

自查方式

1.小程序開啟消息推送（小程序后臺-開發管理-開發設置-消息推送）

2.小程序把「客服權限」授權給第三方平臺（小程序后臺-設置-第三方設置-第三方平臺授權管理）

*特殊情況

對于開啟云函數且沒開啟云托管的小程序，用戶發送的消息會推送到云函數，不會走到小程序客服系統，也不會callback給第三方服務器或者小程序消息推送的服務器地址。

將消息轉發到客服

如果小程序處于開發模式，普通微信用戶向小程序客服發消息時，微信服務器會先將消息POST到開發者填寫的url上，如果希望將消息轉發到客服系統，則需要開發者在響應包中返回MsgType為transfer_customer_service的消息，微信服務器收到響應后會把當次發送的消息轉發至客服系統。

用戶被客服接入以后，客服關閉會話以前，處于會話過程中時，用戶發送的消息均會被直接轉發至客服系統。當會話超過30分鐘客服沒有關閉時，微信服務器會自動停止轉發至客服，而將消息恢復發送至開發者填寫的url上。

用戶在等待隊列中時，用戶發送的消息仍然會被推送至開發者填寫的url上。

這里特別要注意，只針對微信用戶發來的消息才進行轉發，而對于其他任何事件都不應該轉接，否則客服在客服系統上就會看到一些無意義的消息了。

調用說明

<xml> 
  <ToUserName><![CDATA[touser]]></ToUserName>  
  <FromUserName><![CDATA[fromuser]]></FromUserName>  
  <CreateTime>1399197672</CreateTime>  
  <MsgType><![CDATA[transfer_customer_service]]></MsgType>
</xml>

請求參數說明

客服管理

獲取客服基本信息

該接口提供小程序下所有客服基本信息的列表獲取。

調用說明

http請求方式: GET https://api.weixin.qq.com/cgi-bin/customservice/getkflist?access_token=ACCESS_TOKEN

返回說明

返回數據示例（正確時的JSON返回結果）

{
      "kf_list" : [
         {
            "kf_account" : "",
            "kf_headimgurl" : "http://mmbiz.qpic.cn/mmbiz/4whpV1VZl2iccsvYbHvnphkyGtnvjfUS8Ym0GSaLic0FD3vN0V8PILcibEGb2fPfEOmw/0",
            "kf_id" : "1001",
            "kf_nick" : "ntest1",
            "kf_wx" : "kfwx1",
            "kf_openid": "kfopenid1"
         },
         {
            "kf_account" : "test1@test" ,
            "kf_headimgurl" : "http://mmbiz.qpic.cn/mmbiz/4whpV1VZl2iccsvYbHvnphkyGtnvjfUS8Ym0GSaLic0FD3vN0V8PILcibEGb2fPfEOmw/0",
            "kf_id" : "1002",
            "kf_nick" : "ntest2",
            "kf_wx" : "kfwx2",
            "kf_openid": "kfopenid2"
         },
         {
            "kf_headimgurl" : "http://mmbiz.qpic.cn/mmbiz/4whpV1VZl2iccsvYbHvnphkyGtnvjfUS8Ym0GSaLic0FD3vN0V8PILcibEGb2fPfEOmw/0",
            "kf_id" : "1003",
            "kf_nick" : "ntest3",
            "kf_openid": "kfopenid3"
         }
      ]
}

返回參數說明

獲取在線客服列表

該接口提供小程序下所有在線客服列表的獲取。

調用說明

http請求方式：GET https://api.weixin.qq.com/cgi-bin/customservice/getonlinekflist?access_token=ACCESS_TOKEN

返回說明

返回參數示例

{
"kf_online_list" : [
    {
        "kf_account" : "test1@test" ,
        "status" : 1,
        "kf_id" : "1001",
        "kf_openid": "kfopenid1"
    },
    {
        "kf_account" : "",
        "status" : 1,
        "kf_id" : "1002",
        "kf_openid": "kfopenid2"
    }
]
}

返回參數說明

添加客服賬號

該接口將給定的客服微信號添加為小程序客服賬號。

調用說明

http請求方式: POST https://api.weixin.qq.com/customservice/kfaccount/add?access_token=ACCESS_TOKEN

請求參數示例

{
    "kf_wx" : "test1",
    "business_id" : 1
}

請求參數說明

返回說明

返回參數示例

// 返回數據示例（正確時的JSON返回結果）：
{
    "errcode" : 0,
    "errmsg" : "ok"
}

刪除客服賬號

該接口根據給定的客服編號刪除小程序客服賬號。

調用說明

http請求方式: GET https://api.weixin.qq.com/customservice/kfaccount/del?access_token=ACCESS_TOKEN&kf_openid=KFOPENID

請求參數說明

返回參數示例

// 返回數據示例（正確時的JSON返回結果）：
{
    "errcode" : 0,
    "errmsg" : "ok"
}

設置客服管理員

該接口將小程序客服編號對應客服賬號設置為客服管理員。

調用說明

http請求方式: GET https://api.weixin.qq.com/customservice/kfaccount/setadmin?access_token=ACCESS_TOKEN&kf_openid=KFOPENID

請求參數說明

返回說明

返回參數示例

// 返回數據示例（正確時的JSON返回結果）：
{
    "errcode" : 0,
    "errmsg" : "ok"
}

取消客服管理員

該接口根據小程序客服編號，解除對應客服賬號客服管理員身份。

調用說明

http請求方式: GET https://api.weixin.qq.com/customservice/kfaccount/canceladmin?access_token=ACCESS_TOKEN&kf_openid=KFOPENID

請求參數說明

返回說明

返回參數示例

// 返回數據示例（正確時的JSON返回結果）：
{
    "errcode" : 0,
    "errmsg" : "ok"
}

主要返回碼

小程序客服子商戶能力介紹及開發文檔

功能介紹

客服子商戶能力，是微信公眾平臺為綜合服務平臺型小程序提供的客服能力支持。 一個小程序帳號可為平臺內的商戶創建多個子商戶帳號，創建后在小程序客服組件喚起子商戶單獨的會話。多個子商戶會話獨立，可為用戶提供更優質的客服體驗。

開放范圍

對【電商平臺】類目小程序開放。權限開通流程登錄小程序管理后臺，進入“設置-接口設置”，開通能力。子商戶賬號數量上限開通后，單個小程序賬號可申請子商戶賬號上限為500個，如需申請上調，請以《小程序客服子商戶數量上調申請_小程序名稱》為主題，發送郵件至placeofminiprogram@qq.com，郵件內注明小程序賬號appid、小程序名稱、使用背景、需要申請的賬號量、業務下已有產品(包括app/網站/公眾號)信息。審核通過后可提高子商戶數量上限。

開發文檔

創建商戶

接口調用請求說明

http請求方式: POST https://api.weixin.qq.com/cgi-bin/business/register?access_token=ACCESS_TOKEN

JSON數據包如下

{
    "account_name": "apple",
    "nickname": "蘋果",
    "icon_media_id":"media_id"
    "transfer_to_commkf": 0
}

返回報文示例

{ "business_id": 1 }

參數說明

返回碼說明

更新商戶信息

接口調用請求說明

http請求方式: POST https://api.weixin.qq.com/cgi-bin/business/update?access_token=ACCESS_TOKEN

JSON數據包如下

{
    "business_id": 1,
    "nickname": "蘋果",
    "icon_media_id":""
}

返回報文示例

{
    "errcode": 0,
    "errmsg": "ok"
}

說明

1. nickname為空則不更新昵稱
2. icon_media_id為空則不更新頭像

參數說明

返回碼說明

拉取單個商戶信息

接口調用請求說明

http請求方式: POST https://api.weixin.qq.com/cgi-bin/business/get?access_token=ACCESS_TOKEN

JSON數據包如下

{
    "business_id": 1
}
或
{
    "account_name": "apple"
}

返回報文示例

{
    "business_info":
    {
        "business_id": 1,
        "account_name": "apple",
        "nickname":"蘋果",
        "icon_url":"icon_url"
    }
}

參數說明

返回碼說明

拉取多個商戶信息

接口調用請求說明

http請求方式: POST https://api.weixin.qq.com/cgi-bin/business/list?access_token=ACCESS_TOKEN

JSON數據包如下

{
    "offset": 0,
    "count": 100
}

返回報文示例

{
    "list": [
        {
            "business_id": 1,
            "account_name": "apple",
            "nickname":"蘋果",
            "icon_url":"icon_url"
        },
        {
            "business_id": 2,
            "account_name": "apple",
            "nickname":"蘋果",
            "icon_url":"icon_url"
        }
    ]
}

說明: 某一次請求的返回的數據量小于count數，說明請求的數據已經到了末端

參數說明

接收消息推送

具體說明可以參考客服消息接收消息和事件 推送時會增加一個參數BusinessId，代表消息是從子商戶的會話中過來的。 以發送文本消息為例:

JSON格式示例

{
    "ToUserName": "toUser",
    "FromUserName": "fromUser",
    "CreateTime": 1482048670,
    "MsgType": "text",
    "Content": "this is a test",
    "MsgId": 1234567890123456,
    "BusinessId": 1
}

XML格式示例

<xml>
    <ToUserName><![CDATA[toUser]]></ToUserName>
    <FromUserName><![CDATA[fromUser]]></FromUserName>
    <CreateTime>1482048670</CreateTime>
    <MsgType><![CDATA[text]]></MsgType>
    <Content><![CDATA[this is a test]]></Content>
    <MsgId>1234567890123456</MsgId>
    <BusinessId>1</BusinessId>
</xml>

發送客服消息

接口調用請求說明

http請求方式: POST https://api.weixin.qq.com/cgi-bin/message/custom/business/send?access_token=ACCESS_TOKEN

JSON數據包

除請求url不同外，postdata可直接參考原有發送客服消息JSON數據包，并在此基礎上加上參數businessid 。以發

送文本消息為例:

{
    "touser":"OPENID",
    "businessid":1,
    "msgtype":"text",
    "text":
    {
    "content":"Hello World"
    }
}

客服輸入狀態

接口調用請求說明

http請求方式: POST https://api.weixin.qq.com/cgi-bin/message/custom/business/typing?access_token=ACCESS_TOKEN

JSON數據包

除請求url不同外，postdata可直接參考原有客服輸入狀態接口的JSON數據包，并在此基礎上增加參數 businessid，示例如下:

{
    "businessid":1,
    "touser":"OPENID",
    "command":"Typing"
}

小程序組件發起子商戶客服會話

button 增加一個屬性 business-id，表示子商戶 ID。