客服消息使用指南

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

功能介紹

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

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

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

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

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

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

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

下發(fā)條件說明

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

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

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

調用客服消息接口發(fā)送客服消息

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

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

填寫消息推送配置

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

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

接口調用

小程序客服消息API文檔

網(wǎng)頁端客服工具與移動端小程序客服工具

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

客服小助手小程序碼

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

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

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

綁定客服人員

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

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

登錄并接入

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

切換客服狀態(tài)

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

接收與發(fā)送消息

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

網(wǎng)頁端微信小程序客服工具使用說明

登錄并接入

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

切換客服狀態(tài)

點擊在線狀態(tài)，可以選擇在線狀態(tài)、離線狀態(tài)

接收消息

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

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

發(fā)送消息

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

使用規(guī)范

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

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

客服消息開發(fā)文檔

客服消息

在頁面使用客服消息

需要將 button 組件 open-type 的值設置為 contact，當用戶點擊后就會進入客服會話，如果用戶在會話中點擊了小程序消息，則會返回到小程序，開發(fā)者可以通過 bindcontact 事件回調獲取到用戶所點消息的頁面路徑 path 和對應的參數(shù) query，此外，開發(fā)者可以通過設置 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)
    }
})

返回參數(shù)說明

后臺接入消息服務

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

后臺接入消息報錯自查

報錯表現(xiàn)

用戶發(fā)送消息出現(xiàn)系統(tǒng)文案 “該小程序提供的服務出現(xiàn)故障，請稍后再試”。

報錯原因

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

自查方式

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

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

*特殊情況

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

將消息轉發(fā)到客服

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

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

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

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

調用說明

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

請求參數(shù)說明

客服管理

獲取客服基本信息

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

調用說明

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

返回說明

返回數(shù)據(jù)示例（正確時的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"
         }
      ]
}

返回參數(shù)說明

獲取在線客服列表

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

調用說明

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

返回說明

返回參數(shù)示例

{
"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"
    }
]
}

返回參數(shù)說明

添加客服賬號

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

調用說明

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

請求參數(shù)示例

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

請求參數(shù)說明

返回說明

返回參數(shù)示例

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

刪除客服賬號

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

調用說明

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

請求參數(shù)說明

返回參數(shù)示例

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

設置客服管理員

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

調用說明

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

請求參數(shù)說明

返回說明

返回參數(shù)示例

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

取消客服管理員

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

調用說明

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

請求參數(shù)說明

返回說明

返回參數(shù)示例

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

主要返回碼

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

功能介紹

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

開放范圍

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

開發(fā)文檔

創(chuàng)建商戶

接口調用請求說明

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

JSON數(shù)據(jù)包如下

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

返回報文示例

{ "business_id": 1 }

參數(shù)說明

返回碼說明

更新商戶信息

接口調用請求說明

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

JSON數(shù)據(jù)包如下

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

返回報文示例

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

說明

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

參數(shù)說明

返回碼說明

拉取單個商戶信息

接口調用請求說明

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

JSON數(shù)據(jù)包如下

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

返回報文示例

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

參數(shù)說明

返回碼說明

拉取多個商戶信息

接口調用請求說明

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

JSON數(shù)據(jù)包如下

{
    "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"
        }
    ]
}

說明: 某一次請求的返回的數(shù)據(jù)量小于count數(shù)，說明請求的數(shù)據(jù)已經(jīng)到了末端

參數(shù)說明

接收消息推送

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

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>

發(fā)送客服消息

接口調用請求說明

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

JSON數(shù)據(jù)包

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

送文本消息為例:

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

客服輸入狀態(tài)

接口調用請求說明

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

JSON數(shù)據(jù)包

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

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

小程序組件發(fā)起子商戶客服會話

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