微信小程序 消息·客服消息

客服消息

在頁(yè)面使用客服消息

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

代碼示例

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

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

返回參數(shù)說(shuō)明

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

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

接收消息和事件

在頁(yè)面中使用 <button open-type="contact" /> 可以顯示進(jìn)入客服會(huì)話按鈕。

當(dāng)用戶在客服會(huì)話發(fā)送消息、或由某些特定的用戶操作引發(fā)事件推送時(shí)，微信服務(wù)器會(huì)將消息或事件的數(shù)據(jù)包發(fā)送到開(kāi)發(fā)者填寫(xiě)的 URL，如果使用的是云開(kāi)發(fā)，則可以推送到指定的云函數(shù)（詳情請(qǐng)參考消息推送）。開(kāi)發(fā)者收到請(qǐng)求后可以使用 發(fā)送客服消息 接口進(jìn)行異步回復(fù)。

各消息類型的推送JSON、XML數(shù)據(jù)包結(jié)構(gòu)如下。

文本消息

用戶在客服會(huì)話中發(fā)送文本消息時(shí)將產(chǎn)生如下數(shù)據(jù)包：

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>
</xml>

JSON 格式

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

參數(shù)說(shuō)明

圖片消息

用戶在客服會(huì)話中發(fā)送圖片消息時(shí)將產(chǎn)生如下數(shù)據(jù)包：

XML 格式

<xml>
      <ToUserName><![CDATA[toUser]]></ToUserName>
      <FromUserName><![CDATA[fromUser]]></FromUserName>
      <CreateTime>1482048670</CreateTime>
      <MsgType><![CDATA[image]]></MsgType>
      <PicUrl><![CDATA[this is a url]]></PicUrl>
      <MediaId><![CDATA[media_id]]></MediaId>
      <MsgId>1234567890123456</MsgId>
</xml>

JSON 格式

{
  "ToUserName": "toUser",
  "FromUserName": "fromUser",
  "CreateTime": 1482048670,
  "MsgType": "image",
  "PicUrl": "this is a url",
  "MediaId": "media_id",
  "MsgId": 1234567890123456
}

參數(shù)說(shuō)明

小程序卡片消息

用戶在客服會(huì)話中發(fā)送小程序卡片消息時(shí)將產(chǎn)生如下數(shù)據(jù)包：

XML 格式

<xml>
  <ToUserName><![CDATA[toUser]]></ToUserName>
  <FromUserName><![CDATA[fromUser]]></FromUserName>
  <CreateTime>1482048670</CreateTime>
  <MsgType><![CDATA[miniprogrampage]]></MsgType>
  <MsgId>1234567890123456</MsgId>
  <Title><![CDATA[Title]]></Title>
  <AppId><![CDATA[AppId]]></AppId>
  <PagePath><![CDATA[PagePath]]></PagePath>
  <ThumbUrl><![CDATA[ThumbUrl]]></ThumbUrl>
  <ThumbMediaId><![CDATA[ThumbMediaId]]></ThumbMediaId>
</xml>

JSON 格式

{
  "ToUserName": "toUser",
  "FromUserName": "fromUser",
  "CreateTime": 1482048670,
  "MsgType": "miniprogrampage",
  "MsgId": 1234567890123456,
  "Title":"title",
  "AppId":"appid",
  "PagePath":"path",
  "ThumbUrl":"",
  "ThumbMediaId":""
}

參數(shù)說(shuō)明

進(jìn)入會(huì)話事件

用戶在小程序“客服會(huì)話按鈕”進(jìn)入客服會(huì)話時(shí)將產(chǎn)生如下數(shù)據(jù)包：

XML 格式

<xml>
    <ToUserName><![CDATA[toUser]]></ToUserName>
    <FromUserName><![CDATA[fromUser]]></FromUserName>
    <CreateTime>1482048670</CreateTime>
    <MsgType><![CDATA[event]]></MsgType>
    <Event><![CDATA[user_enter_tempsession]]></Event>
    <SessionFrom><![CDATA[sessionFrom]]></SessionFrom>
</xml>

JSON 格式

{
  "ToUserName": "toUser",
  "FromUserName": "fromUser",
  "CreateTime": 1482048670,
  "MsgType": "event",
  "Event": "user_enter_tempsession",
  "SessionFrom": "sessionFrom"
}

參數(shù)說(shuō)明

發(fā)送客服消息

當(dāng)用戶和小程序客服產(chǎn)生特定動(dòng)作的交互時(shí)（具體動(dòng)作列表請(qǐng)見(jiàn)下方說(shuō)明），微信將會(huì)把消息數(shù)據(jù)推送給開(kāi)發(fā)者，開(kāi)發(fā)者可以在一段時(shí)間內(nèi)（目前為 48 小時(shí)）調(diào)用客服接口，通過(guò)調(diào)用 發(fā)送客服消息接口 來(lái)發(fā)送消息給普通用戶。此接口主要用于客服等有人工消息處理環(huán)節(jié)的功能，方便開(kāi)發(fā)者為用戶提供更加優(yōu)質(zhì)的服務(wù)。

目前允許的動(dòng)作列表如下，不同動(dòng)作觸發(fā)后，允許的客服接口下發(fā)消息條數(shù)和下發(fā)時(shí)限不同。

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

如果小程序設(shè)置了消息推送，普通微信用戶向小程序客服發(fā)消息時(shí)，微信服務(wù)器會(huì)先將消息 POST 到開(kāi)發(fā)者填寫(xiě)的 URL 上，如果希望將消息轉(zhuǎn)發(fā)到網(wǎng)頁(yè)版客服工具，則需要開(kāi)發(fā)者在響應(yīng)包中返回 MsgType 為 transfer_customer_service 的消息，微信服務(wù)器收到響應(yīng)后會(huì)把當(dāng)次發(fā)送的消息轉(zhuǎn)發(fā)至客服系統(tǒng)。

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

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

這里特別要注意，只針對(duì)微信用戶發(fā)來(lái)的消息才進(jìn)行轉(zhuǎn)發(fā)，而對(duì)于其他事件（比如用戶從小程序喚起客服會(huì)話）都不應(yīng)該轉(zhuǎn)發(fā)，否則客服在客服系統(tǒng)上就會(huì)看到一些無(wú)意義的消息了。

消息轉(zhuǎn)發(fā)到網(wǎng)頁(yè)版客服工具

開(kāi)發(fā)者只要在響應(yīng)包中返回 MsgType 為 transfer_customer_service 的消息，微信服務(wù)器收到響應(yīng)后就會(huì)把當(dāng)次發(fā)送的消息轉(zhuǎn)發(fā)至客服系統(tǒng)。

如果是使用自有服務(wù)器接收的消息推送，則需返回如下格式的 XML 數(shù)據(jù)：

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

參數(shù)說(shuō)明

如果是使用云函數(shù)接收的消息推送，則需在云函數(shù)被客服消息觸發(fā)后返回同樣格式的 JSON 數(shù)據(jù)：

// ...
exports.main = async (event, context) => {
  // 判斷處理客服消息 ...
  // 最后返回 JSON
  return {
    MsgType: 'transfer_customer_service',
    ToUserName: 'touser',
    FromUserName: 'fromuser',
    CreateTime: parseInt(+new Date / 1000),
  }
}

客服輸入狀態(tài)

開(kāi)發(fā)者可通過(guò)調(diào)用 客服輸入狀態(tài)接口，返回客服當(dāng)前輸入狀態(tài)給用戶。

1. 此接口需要客服消息接口權(quán)限。
2. 如果不滿足發(fā)送客服消息的觸發(fā)條件，則無(wú)法下發(fā)輸入狀態(tài)。
3. 下發(fā)輸入狀態(tài)，需要客服之前 30 秒內(nèi)跟用戶有過(guò)消息交互。
4. 在輸入狀態(tài)中（持續(xù) 15 秒），不可重復(fù)下發(fā)輸入態(tài)。
5. 在輸入狀態(tài)中，如果向用戶下發(fā)消息，會(huì)同時(shí)取消輸入狀態(tài)。

在客服消息中使用臨時(shí)素材

開(kāi)發(fā)者可在接收和發(fā)送客服消息的過(guò)程中獲取或上傳臨時(shí)素材。

獲取臨時(shí)素材

接收到用戶消息之后，可通過(guò) 獲取臨時(shí)素材接口 獲取消息中的臨時(shí)素材

上傳臨時(shí)素材

通過(guò) 上傳臨時(shí)素材接口 可以上傳臨時(shí)素材，并在 發(fā)送消息接口 中使用。