舊版 Dialogflow CX Messenger

舊版 Dialogflow CX Messenger 整合服務可為您的服務專員提供可嵌入網站的自訂聊天對話方塊。聊天對話方塊是以對話方塊視窗的形式實作，可供使用者開啟和關閉。開啟後，即時通訊對話方塊會顯示在畫面右下方的內容上方。

遷移至最新的 Dialogflow CX Messenger

最新版的 Dialogflow CX Messenger 提供驗證機制，可控管服務專員查詢存取權和更多使用者介面設定選項。建議所有舊版使用者遷移至新版。

如果您在 2023 年 8 月 29 日前啟用 Dialogflow CX Messenger 整合功能，可能會使用舊版。如要判斷是否使用舊版，請檢查網站中嵌入的 Messenger HTML 程式碼。如果您看到下列指令碼，表示您使用的是舊版：

https://www.gstatic.com/dialogflow-console/fast/messenger-cx/bootstrap.js?v=1

如要遷移至新版本，請按照下列步驟操作：

  1. 從網站中刪除所有 HTML、CSS 和 JavaScript 訊息程式碼。
  2. 請按照最新的 Dialogflow CX Messenger 整合功能操作說明操作。

HTML 自訂項目

您可以自訂聊天對話方塊的顯示方式和行為。df-messenger HTML 元素的屬性如下：

屬性 輸入政策 值
agent-id 必填 與服務專員相關聯的 ID。這個欄位會預先填入您的服務專員 ID。
chat-icon 選用 用於即時通訊對話方塊開啟按鈕的圖示。預設為 Conversational Agents (Dialogflow CX) 圖示。這個欄位必須是公開網址。圖示大小應為 36 x 36 像素。
chat-title 必填 顯示在即時通訊對話方塊頂端的標題。這個欄位會預先填入服務專員的名稱。
df-cx 必填 表示與客戶體驗服務專員互動。使用「true」做為值。
expand 選用 布林值屬性，可在頁面載入時開啟即時通訊對話方塊。根據預設，聊天對話方塊會在頁面載入時關閉。
intent 選用 開啟即時通訊對話方塊時會叫用的自訂事件。您可以使用事件處理常式，這個常式會為此事件呼叫並產生第一個服務專員訊息。
language-code 必填 第一個意圖的預設語言代碼。系統會預先填入代理人的預設語言。
location 必填 服務專員的地區。
session-id 選用 工作階段 ID。如果未提供此 ID，整合作業會為每個對話方產生專屬 ID。
user-id 選用 可用於追蹤使用者在不同工作階段的活動。您可以透過偵測意圖要求中的 queryParams.payload.userId 欄位，將值傳遞至 Conversational Agents (Dialogflow CX)，而 Conversational Agents (Dialogflow CX) 會透過 WebhookRequest.payload.userId 欄位提供這個值。
wait-open 選用 布林值屬性，可延遲 intent 屬性中定義的自訂事件，直到對話方塊實際開啟為止。

CSS 自訂設定

您可以設定 CSS 變數，自訂聊天對話方塊的樣式。

您可以提供下列 CSS 變數：

CSS 變數 受影響的房源
df-messenger-bot-message 代理人訊息的氣泡背景顏色。
df-messenger-button-titlebar-color 聊天對話方塊的浮動按鈕和標題列顏色。
df-messenger-button-titlebar-font-color 標題列中標題的字型顏色。
df-messenger-chat-background-color 即時通訊對話方塊背景的顏色。
df-messenger-font-color 訊息的字型顏色。
df-messenger-input-box-color 文字輸入框的背景顏色。
df-messenger-input-font-color 文字輸入框的字型顏色。
df-messenger-input-placeholder-font-color 文字輸入框中預留位置文字的字型顏色。
df-messenger-minimized-chat-close-icon-color 關閉即時通訊視圖中的關閉圖示顏色。
df-messenger-send-icon 文字輸入框中的傳送圖示顏色。
df-messenger-user-message 使用者訊息的氣泡背景顏色。

範例程式碼：

<style>
  df-messenger {
   --df-messenger-bot-message: #878fac;
   --df-messenger-button-titlebar-color: #df9b56;
   --df-messenger-chat-background-color: #fafafa;
   --df-messenger-font-color: white;
   --df-messenger-send-icon: #878fac;
   --df-messenger-user-message: #479b3d;
  }
</style>

上述設定會導致以下結果：

Messenger 螢幕截圖

JavaScript 事件

Dialogflow Messenger 會觸發各種事件，您可以為這些事件建立事件監聽器。

這些事件的事件目標是 df-messenger 元素。

如要為 df-messenger 元素新增事件監聽器，請新增下列 JavaScript 程式碼，其中 event-type 是下列事件名稱之一：

const dfMessenger = document.querySelector('df-messenger');
dfMessenger.addEventListener('event-type', function (event) {
  // Handle event
  ...
});

支援下列事件類型：

df-accordion-clicked

使用者點選摺疊式元素時，就會觸發這項事件。事件結構如下所示：

element: {
  title: string,
  subtitle: string,
  image: {
    src: {rawUrl: string}
  },
  text: string
}

df-button-clicked

使用者按下按鈕元素時，就會觸發此事件。事件結構如下所示：

element: {
  icon: {
    type: string,
    color: string
  },
  text: string,
  link: string,
  event: EventInput,
  payload: {}
}

df-chip-clicked

使用者選取建議方塊時，就會觸發這項事件。事件結構如下所示：

query: string // Text of the suggestion chip that was selected.

df-info-card-clicked

當使用者點選標題列中的資訊項目時，就會觸發這項事件。事件結構如下所示：

element: {
  title: string,
  image: {
    src: {rawUrl: string}
  },
  actionLink: string
}

df-list-element-clicked

當使用者點選清單中的項目時，就會觸發這項事件。事件結構如下所示：

element: {
  title: string,
  subtitle: string,
  image: {
    src: {rawUrl}
  },
  event: {
    name: string
  },
  payload: {}
}

df-messenger-error

當 Dialogflow API 傳送錯誤狀態碼時，就會觸發這個事件。事件結構如下所示：

error: {
  "error": {
    "code": <error_code>,
    "message": <error_message>,
    "status": <error_status>
  }
}

df-messenger-loaded

當 df-messenger 元素已完全載入並初始化時，系統會觸發此事件。

df-request-sent

向 Dialogflow API 提出要求時，就會發生這項事件。您可以使用這個事件和 df-response-received 監控要求延遲時間。事件結構如下所示：

requestBody: {
  "queryParams": {
    object(QueryParameters)
  },
  "queryInput": {
    object(QueryInput)
  },
  "inputAudio": string
}

df-response-received

收到 Dialogflow API 回應時，就會觸發這項事件。事件結構如下所示：

response: detectIntentResponse

df-user-input-entered

當使用者輸入查詢時，就會發生這項事件。事件結構如下所示：

input: string // Text entered by user

JavaScript 函式

df-messenger 元素提供可呼叫的函式，可影響其行為。

renderCustomText

此函式會顯示簡單的文字訊息，就像是來自 Conversational Agents (Dialogflow CX) 的簡單文字回覆。

例如：

const dfMessenger = document.querySelector('df-messenger');
dfMessenger.renderCustomText('Custom text');

renderCustomCard

此函式會算繪自訂資訊卡，就好像是來自 Conversational Agents (Dialogflow CX) 執行要求一樣。自訂酬載回應的格式會在「Fulfillment」部分中定義。

例如：

const dfMessenger = document.querySelector('df-messenger');
const payload = [
  {
    "type": "info",
    "title": "Info item title",
    "subtitle": "Info item subtitle",
    "image": {
      "src": {
        "rawUrl": "https://example.com/images/logo.png"
      }
    },
    "actionLink": "https://example.com"
  }];
dfMessenger.renderCustomCard(payload);

showMinChat

這個函式會顯示最精簡的訊息清單。

例如：

const dfMessenger = document.querySelector('df-messenger');
dfMessenger.showMinChat();

Fulfillment

建立執行要求時，您可以建立文字回應和自訂酬載。文字回應用於基本服務專員回應，而自訂酬載則用於複合式回應。所有回應類型的自訂酬載格式具有下列基本結構：

{
  "richContent": [
    [
      {
        "type": "type-id",
        ...
      },
      {
        "type": "type-id",
        ...
      }
    ],
    [
      {
        "type": "type-id",
        ...
      },
      {
        "type": "type-id",
        ...
      }
    ]
  ]
}

請注意，richContent 值允許一個外部和多個內部陣列。內部陣列中的回覆會綁定在單一視覺資訊卡中。如果外部陣列包含多個內部陣列，系統會顯示多個資訊卡，每個內部陣列一個。

其餘各子區段說明可為自訂酬載設定的各種回應類型。

資訊回應類型

資訊回應類型是使用者可點選或輕觸的簡單標題卡。

Messenger 螢幕截圖

下表說明這些欄位：

名稱 類型 說明
type 字串 回應類型：「info」
title 字串 資訊卡標題
subtitle 字串 資訊卡副標題
image 物件 圖片
image.src 物件 圖片來源
image.src.rawUrl 字串 圖片的公開網址
actionLink 字串 點選資訊卡時要前往的網址

例如：

{
  "richContent": [
    [
      {
        "type": "info",
        "title": "Info item title",
        "subtitle": "Info item subtitle",
        "image": {
          "src": {
            "rawUrl": "https://example.com/images/logo.png"
          }
        },
        "actionLink": "https://example.com"
      }
    ]
  ]
}

說明回應類型

說明回應類型是資訊卡，可包含多行文字。

Messenger 螢幕截圖

下表說明這些欄位：

名稱 類型 說明
type 字串 回應類型：「description」
title 字串 資訊卡標題
text array<string> 字串陣列，其中每個字串會在新的一行中顯示

例如：

{
  "richContent": [
    [
      {
        "type": "description",
        "title": "Description title",
        "text": [
          "This is text line 1.",
          "This is text line 2."
        ]
      }
    ]
  ]
}

圖片回應類型

圖片回應類型是使用者可點選或輕觸的圖片資訊卡。

Messenger 螢幕截圖

下表說明這些欄位：

名稱 類型 說明
type 字串 回應類型：「image」
rawUrl 字串 圖片的公開網址
accessibilityText 字串 圖片替代文字

例如：

{
  "richContent": [
    [
      {
        "type": "image",
        "rawUrl": "https://example.com/images/logo.png",
        "accessibilityText": "Example logo"
      }
    ]
  ]
}

按鈕回應類型

按鈕回應類型是使用者可點選或輕觸的圖示小按鈕。

Messenger 螢幕截圖

下表說明這些欄位：

名稱 類型 說明
type 字串 回應類型：「button」
icon 物件 按鈕圖示
icon.type 字串 Material Design 圖示庫中的圖示。預設圖示為箭頭
icon.color 字串 顏色十六進位代碼
text 字串 按鈕文字
link 字串 點按按鈕時要前往的網址
event 物件 點按按鈕時觸發的 Conversational Agents (Dialogflow CX) 事件。

例如：

{
  "richContent": [
    [
      {
        "type": "button",
        "icon": {
          "type": "chevron_right",
          "color": "#FF9800"
        },
        "text": "Button text",
        "link": "https://example.com",
        "event": {
          "name": ""
        }
      }
    ]
  ]
}

清單回應類型

清單回應類型是卡片，使用者可從中選取多個選項。

Messenger 螢幕截圖

回應包含 list 和 divider 回應類型的陣列。下表說明 list 類型：

名稱 類型 說明
type 字串 回應類型：「list」
title 字串 選項名稱
subtitle 字串 選項副標題
event 物件 點選選項時觸發的 Conversational Agents (Dialogflow CX) 事件。

下表說明 divider 類型：

名稱 類型 說明
type 字串 回覆類型：「divider」

例如：

{
  "richContent": [
    [
      {
        "type": "list",
        "title": "List item 1 title",
        "subtitle": "List item 1 subtitle",
        "event": {
          "name": ""
        }
      },
      {
        "type": "divider"
      },
      {
        "type": "list",
        "title": "List item 2 title",
        "subtitle": "List item 2 subtitle",
        "event": {
          "name": ""
        }
      }
    ]
  ]
}

摺頁回應類型

摺疊式回應類型是小型資訊卡，使用者只要點選或輕觸即可展開，查看更多文字。

Messenger 螢幕截圖

下表說明這些欄位：

名稱 類型 說明
type 字串 回應類型：「accordion」
title 字串 摺頁標題
subtitle 字串 摺疊式副標題
image 物件 圖片
image.src 物件 圖片來源
image.src.rawUrl 字串 圖片的公開網址
text 字串 摺頁文字

例如：

{
  "richContent": [
    [
      {
        "type": "accordion",
        "title": "Accordion title",
        "subtitle": "Accordion subtitle",
        "image": {
          "src": {
            "rawUrl": "https://example.com/images/logo.png"
          }
        },
        "text": "Accordion text"
      }
    ]
  ]
}

建議方塊回應類型

建議方塊回應類型會為使用者提供可點選的建議方塊清單。

Messenger 螢幕截圖

下表說明這些欄位：

名稱 類型 說明
type 字串 回應類型：「chips」
options 陣列<物件> Option 物件陣列
options[].text 字串 選項文字
options[].image 物件 選項圖片
options[].image.src 物件 選項圖片來源
options[].image.src.rawUrl 字串 圖片的公開網址選項
options[].link 字串 選項連結

例如：

{
  "richContent": [
    [
      {
        "type": "chips",
        "options": [
          {
            "text": "Chip 1",
            "image": {
              "src": {
                "rawUrl": "https://example.com/images/logo.png"
              }
            },
            "link": "https://example.com"
          },
          {
            "text": "Chip 2",
            "image": {
              "src": {
                "rawUrl": "https://example.com/images/logo.png"
              }
            },
            "link": "https://example.com"
          }
        ]
      }
    ]
  ]
}

結合回應類型

您可以使用 Dialogflow CX Messenger 的個別多媒體訊息元素，建構符合需求的自訂資訊卡。以下是使用上述部分元素的範例：

Messenger 螢幕截圖

{
  "richContent": [
    [
      {
        "type": "image",
        "rawUrl": "https://example.com/images/logo.png",
        "accessibilityText": "Conversational Agents (Dialogflow CX) across platforms"
      },
      {
        "type": "info",
        "title": "Conversational Agents (Dialogflow CX)",
        "subtitle": "Build natural and rich conversational experiences",
        "actionLink": "https://cloud.google.com/dialogflow/docs"
      },
      {
        "type": "chips",
        "options": [
          {
            "text": "Case Studies",
            "link": "https://cloud.google.com/dialogflow/case-studies"
          },
          {
            "text": "Docs",
            "link": "https://cloud.google.com/dialogflow/docs"
          }
        ]
      }
    ]
  ]
}

偵錯

如要在本機測試 Dialogflow CX Messenger 服務專員，請按照下列步驟操作：

  • 按照「HTML 自訂」一節所述，在網頁中嵌入 Dialogflow CX Messenger 元素。
  • 為該網頁啟動本機 HTTP 伺服器，並使用特定通訊埠。
  • 前往 http://localhost:port_number 存取該頁面。