接收及回覆使用者互動

本頁說明 Google Chat 應用程式如何接收及回應使用者互動，也就是所謂的 Google Chat 應用程式互動事件。

本頁面將說明如何執行下列操作：

  • 設定 Chat 應用程式以接收互動事件。
  • 在基礎架構中處理互動事件。
  • 視情況回應互動事件。

建構互動式 Chat 應用程式，做為 Google Workspace 外掛程式

如要建構可與 Chat 使用者互動的 Chat 應用程式，您可以建構可擴充 Chat 功能的 Google Workspace 外掛程式。Chat 應用程式不會從 Chat API 接收互動事件，而是會接收及回應外掛程式事件物件。詳情請參閱 Google Workspace 外掛程式說明文件中的「擴充 Google Chat」一節。

必要條件

已啟用互動功能的 Google Chat 應用程式。如要建立互動式 Chat 應用程式，請根據要使用的應用程式架構，完成下列其中一個快速入門：

互動事件類型

Google Chat 應用程式互動事件代表使用者執行的任何操作，用於叫用或與 Chat 應用程式互動，例如 @提及 Chat 應用程式，或將其新增至聊天室。

當使用者與 Chat 應用程式互動時，Google Chat 會傳送互動事件給 Chat 應用程式，在 Chat API 中以 Event 類型表示。Chat 應用程式可以使用事件處理互動，並視需要傳送訊息回應。

針對每種使用者互動類型，Google Chat 都會傳送不同類型的互動事件，協助 Chat 應用程式相應處理每種事件類型。互動事件類型會使用 eventType 物件表示。

舉例來說，如果使用者將 Chat 應用程式加入聊天室，Google Chat 會使用事件類型 ADDED_TO_SPACE 處理這項互動，讓 Chat 應用程式立即在聊天室中回覆歡迎訊息。

即時通訊應用程式會發布歡迎訊息。
圖 1：當使用者將 Chat 應用程式新增至聊天室時，Chat 應用程式會收到 ADDED_TO_SPACE 互動事件，並透過 Chat 應用程式處理，在聊天室中傳送歡迎訊息。

下表列出常見的使用者互動、Chat 應用程式收到的互動事件類型，以及 Chat 應用程式通常的回應方式：

使用者互動 eventType Chat 應用程式的一般回應
使用者可以透過 @提及或使用斜線指令叫用 Chat 應用程式。 MESSAGE Chat 應用程式會根據訊息內容回應。舉例來說，Chat 應用程式會回覆 /about 指令，並附上說明 Chat 應用程式可執行的任務。
使用者將 Chat 應用程式新增至聊天室。 ADDED_TO_SPACE Chat 應用程式會傳送 新手上路訊息，說明這項功能的用途，以及聊天室使用者如何與其互動。
使用者從聊天室中移除 Chat 應用程式。 REMOVED_FROM_SPACE Chat 應用程式會移除為聊天室設定的任何傳入通知 (例如刪除 webhook)，並清除所有內部儲存空間。
使用者在 Chat 應用程式訊息、對話方塊或首頁中，按下資訊卡上的按鈕。 CARD_CLICKED Chat 應用程式會處理並儲存使用者提交的任何資料，或傳回另一張資訊卡。
使用者在 1 對 1 訊息中按一下「首頁」分頁，即可開啟 Chat 應用程式的首頁。 APP_HOME Chat 應用程式會從首頁傳回靜態或互動式資訊卡。
使用者透過 Chat 應用程式的首頁提交表單。 SUBMIT_FORM Chat 應用程式會處理並儲存使用者提交的任何資料，或傳回另一張資訊卡。
使用者使用快速指令叫用指令。 APP_COMMAND Chat 應用程式會根據所叫用的指令回應。舉例來說，Chat 應用程式會回覆「關於」指令，並附上說明 Chat 應用程式可執行的任務。

如要查看所有支援的互動事件，請參閱 EventType 參考文件。

對話方塊的互動事件

如果 Chat 應用程式開啟對話方塊，互動事件就會包含下列額外資訊，可用於處理回應：

  • isDialogEvent 設為 true。
  • DialogEventType 會說明互動是否會觸發對話方塊開啟、提交對話方塊中的資訊，或是關閉對話方塊。

下表列出常見的對話互動、對應的對話事件類型，以及 Chat 應用程式通常如何回應：

使用者與對話方塊的互動 對話方塊事件類型 一般回應
使用者觸發對話方塊要求。例如使用斜線指令或點選訊息中的按鈕。 REQUEST_DIALOG Chat 應用程式會開啟對話方塊。
使用者按下按鈕，提交對話方塊中的資訊。 SUBMIT_DIALOG Chat 應用程式會前往其他對話方塊，或關閉對話方塊來完成互動。
使用者在提交資訊前離開或關閉對話方塊。 CANCEL_DIALOG Chat 應用程式可以選擇以新訊息回應，或更新使用者開啟對話方塊的訊息或資訊卡。

詳情請參閱「開啟互動式對話方塊」。

接收 Chat 應用程式互動事件

本節說明如何接收及處理 Chat 應用程式的互動事件。

設定 Chat 應用程式以接收互動事件

並非所有 Chat 應用程式都支援互動功能。舉例來說，「連入 Webhook」只能傳送傳出訊息，無法回覆使用者。如果您要建構互動式 Chat 應用程式，必須選擇端點，讓 Chat 應用程式接收、處理及回應互動事件。如要進一步瞭解如何設計 Chat 應用程式，請參閱「Chat 應用程式實作架構」。

針對您要建構的每項互動功能，您都必須更新 Chat API 中的設定，讓 Google Chat 將相關互動事件傳送至 Chat 應用程式：

  1. 在 Google Cloud 控制台中，前往 Chat API 頁面，然後按一下「Configuration」頁面：

    前往 Chat API 設定頁面

  2. 在「互動式功能」下方，根據您要建構的功能查看設定並更新：

    欄位 說明
    功能 必要欄位。一組欄位，用於決定 Chat 應用程式與使用者互動的方式：
    • 接收 1 對 1 訊息：使用者可以在 Google Chat 中找到 Chat 應用程式並直接傳送訊息。
    • 加入聊天室和群組對話：使用者可以將 Chat 應用程式加入聊天室和群組對話。
    連線設定 必要欄位。Chat 應用程式的端點，為下列其中一個：
    • HTTP 端點網址：代管 Chat 應用程式實作的 HTTPS 端點。
    • Apps Script：實作 Chat 應用程式的 Apps Script 專案部署 ID。
    • Cloud Pub/Sub 主題名稱：Chat 應用程式訂閱的 Pub/Sub 主題，做為端點。
    • Dialogflow：使用 Dialogflow 整合功能註冊 Chat 應用程式。詳情請參閱「建構可理解自然語言的 Dialogflow Google Chat 應用程式」。
    斜線指令 選用設定。可在 Google Chat 中向使用者顯示的指令。允許使用者在 Google Chat 中查看 Chat 應用程式的核心動作，並選擇要互動的特定動作。詳情請參閱「以 Chat 應用程式回應斜線指令」。
    連結預覽 選用設定。Chat 應用程式可以辨識的網址模式，且可在使用者傳送連結時提供額外內容。詳情請參閱「預覽連結」。
    顯示設定 選用設定。最多五位使用者，或一或多個可查看及安裝 Chat 應用程式的 Google 群組。您可以使用這個欄位測試 Chat 應用程式，或與團隊成員分享 Chat 應用程式。詳情請參閱「測試互動式功能」。

  3. 按一下 [儲存]。儲存 Chat 應用程式設定後，Google Workspace 機構中的指定使用者就能使用 Chat 應用程式。

Chat 應用程式現已設定為接收 Google Chat 的互動事件。

處理服務的 HTTP 呼叫重試

如果對服務的 HTTPS 要求失敗 (例如逾時、暫時性網路故障或非 2xx HTTPS 狀態代碼)，Google 即時通訊可能會在幾分鐘內重試傳送幾次 (但無法保證)。因此，在某些情況下，Chat 應用程式可能會收到相同訊息好幾次。如果要求順利完成，但傳回無效的訊息酬載，Google Chat 就不會重試要求。

處理或回應互動事件

本節說明 Google Chat 應用程式如何處理及回應互動事件。

Chat 應用程式收到 Google Chat 的互動事件後，可以透過多種方式回應。在許多情況下，互動式即時通訊應用程式會透過訊息回覆使用者。Google Chat 應用程式也可以從資料來源查詢某些資訊、記錄互動事件資訊，或執行其他操作。這項處理行為基本上就是 Google Chat 應用程式的定義。

如要同步回覆，即時通訊應用程式必須在 30 秒內回覆，且回覆內容必須張貼在發生互動的聊天室中。否則，Chat 應用程式可以非同步回應。

每個互動事件，Chat 應用程式都會收到一個要求主體，也就是代表事件的 JSON 酬載。您可以使用這些資訊處理回應。如需事件酬載的範例，請參閱「Chat 應用程式互動事件類型」。

下圖說明 Google Chat 應用程式通常如何處理或回應不同類型的互動事件：

Google Chat 應用程式處理互動事件的架構。

即時回覆

互動事件可讓 Chat 應用程式即時或同步回應。同步回應不需要驗證。

如要即時回應，即時通訊應用程式必須傳回 Message 物件。如要在聊天室中回覆訊息，Message 物件可以包含 text、cardsV2 和 accessoryWidgets 物件。如要搭配其他類型的回應使用，請參閱下列指南：

使用訊息回覆

在這個範例中，Chat 應用程式會在新增至聊天室時建立及傳送文字訊息。如要瞭解使用者新手上路的最佳做法，請參閱「向使用者介紹 Chat 應用程式」。

如要在使用者將 Chat 應用程式加入聊天室時傳送文字訊息，Chat 應用程式會回應 ADDED_TO_SPACE 互動事件。如要使用文字訊息回應 ADDED_TO_SPACE 互動事件，請使用下列程式碼：

Node.js

/**
 * Sends an onboarding message when the Chat app is added to a space.
 *
 * @param {Object} req The event object from Chat API.
 * @param {Object} res The response object from the Chat app. An onboarding message that
 * introduces the app and helps people get started with it.
 */
exports.onMessage = function onMessage(req, res) {
  if (req.method === 'GET' || !req.body.message) {
    res.send(
      'Hello! This function is meant to be used in a Google Chat space.');
  }

  // Send an onboarding message when added to a Chat space
  if (req.body.type === 'ADDED_TO_SPACE') {
    res.json({
      'text': 'Hi, Cymbal at your service. I help you manage your calendar
      from Google Chat. Take a look at your schedule today by typing
      `/checkCalendar`, or schedule a meeting with `/scheduleMeeting`. To
      learn what else I can do, type `/help`.'
    });
  }
};

Apps Script

/**
 * Sends an onboarding message when the Chat app is added to a space.
 *
 * @param {Object} event The event object from Chat API.
 * @return {Object} Response from the Chat app. An onboarding message that
 * introduces the app and helps people get started with it.
 */
function onAddToSpace(event) {

  return {
    'text': 'Hi, Cymbal at your service. I help you manage your calendar
    from Google Chat. Take a look at your schedule today by typing
    `/checkCalendar`, or schedule a meeting with `/scheduleMeeting`. To learn
    what else I can do, type `/help`.'
  }
}

程式碼範例會傳回以下文字訊息：

新手上路訊息範例。

以非同步方式回應

有時 Chat 應用程式必須在 30 秒後回應互動事件，或在產生互動事件的聊天室外執行任務。舉例來說，Chat 應用程式可能需要在完成長時間執行的工作後，回應使用者。在這種情況下，Chat 應用程式可以透過呼叫 Google Chat API 以非同步方式回應。

如要使用 Chat API 建立訊息，請參閱「建立訊息」一文。如需使用其他 Chat API 方法的指南，請參閱 Chat API 總覽。