客服消息使用指南

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

功能介紹

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

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

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

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

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

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

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

下發(fā)條件說明

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

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

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

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

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

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

填寫消息推送配置

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

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

接口調(diào)用

小程序客服消息API文檔

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

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

客服小助手小程序碼

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

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

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

綁定客服人員

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

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

登錄并接入

已被綁定的小程序客服人員可微信搜索「客服小助手」或掃碼登錄「客服小助手」小程序，并選擇對應(yīng)的小程序賬號，登錄后即可看到與小程序?qū)υ挼挠脩?，可選擇接入對話。

切換客服狀態(tài)

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

接收與發(fā)送消息

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

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

登錄并接入

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

切換客服狀態(tài)

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

接收消息

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

自動接入：當(dāng)待接入的用戶會話太多時(shí)，可以在設(shè)置-接入與回復(fù)中，開啟自動接入。

發(fā)送消息

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

使用規(guī)范

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

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

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

客服消息

在頁面使用客服消息

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

后臺接入消息服務(wù)

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

后臺接入消息報(bào)錯自查

報(bào)錯表現(xiàn)

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

報(bào)錯原因

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

自查方式

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

2.小程序把「客服權(quán)限」授權(quán)給第三方平臺（小程序后臺-設(shè)置-第三方設(shè)置-第三方平臺授權(quán)管理）

*特殊情況

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

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

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

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

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

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

調(diào)用說明

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

請求參數(shù)說明

客服管理

獲取客服基本信息

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

調(diào)用說明

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

返回說明

返回?cái)?shù)據(jù)示例（正確時(shí)的JSON返回結(jié)果）

{
      "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ù)說明

獲取在線客服列表

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

調(diào)用說明

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ù)說明

添加客服賬號

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

調(diào)用說明

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

請求參數(shù)示例

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

請求參數(shù)說明

返回說明

返回參數(shù)示例

// 返回?cái)?shù)據(jù)示例（正確時(shí)的JSON返回結(jié)果）：
{
    "errcode" : 0,
    "errmsg" : "ok"
}

刪除客服賬號

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

調(diào)用說明

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

請求參數(shù)說明

返回參數(shù)示例

// 返回?cái)?shù)據(jù)示例（正確時(shí)的JSON返回結(jié)果）：
{
    "errcode" : 0,
    "errmsg" : "ok"
}

設(shè)置客服管理員

該接口將小程序客服編號對應(yīng)客服賬號設(shè)置為客服管理員。

調(diào)用說明

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

請求參數(shù)說明

返回說明

返回參數(shù)示例

// 返回?cái)?shù)據(jù)示例（正確時(shí)的JSON返回結(jié)果）：
{
    "errcode" : 0,
    "errmsg" : "ok"
}

取消客服管理員

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

調(diào)用說明

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

請求參數(shù)說明

返回說明

返回參數(shù)示例

// 返回?cái)?shù)據(jù)示例（正確時(shí)的JSON返回結(jié)果）：
{
    "errcode" : 0,
    "errmsg" : "ok"
}

主要返回碼

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

功能介紹

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

開放范圍

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

開發(fā)文檔

創(chuàng)建商戶

接口調(diào)用請求說明

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
}

返回報(bào)文示例

{ "business_id": 1 }

參數(shù)說明

返回碼說明

更新商戶信息

接口調(diào)用請求說明

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":""
}

返回報(bào)文示例

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

說明

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

參數(shù)說明

返回碼說明

拉取單個商戶信息

接口調(diào)用請求說明

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

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

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

返回報(bào)文示例

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

參數(shù)說明

返回碼說明

拉取多個商戶信息

接口調(diào)用請求說明

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

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

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

返回報(bào)文示例

{
    "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í)會增加一個參數(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ā)送客服消息

接口調(diào)用請求說明

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ù)包，并在此基礎(chǔ)上加上參數(shù)businessid 。以發(fā)

送文本消息為例:

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

客服輸入狀態(tài)

接口調(diào)用請求說明

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ù)包，并在此基礎(chǔ)上增加參數(shù) businessid，示例如下:

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

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

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