本頁面由 Cloud Translation API 翻譯而成。

建構 Google Chat 介面

本頁概要說明如何為擴充 Google Chat 的 Google Workspace 外掛程式建構使用者介面 (UI)。

如要建構 Chat 應用程式的介面，請使用下列外掛程式元件：

觸發條件：Google Chat 使用者叫用 Chat 應用程式的方式，例如將應用程式新增至聊天室或傳送訊息給應用程式。
事件物件：Chat 應用程式從觸發條件或 UI 互動接收的資料。
動作：Chat 應用程式回應互動的方式，例如傳送訊息或傳回以資訊卡為基礎的使用者介面。

Chat 應用程式會從「已新增至聊天室」觸發條件收到事件物件 — **圖 1**：使用者將 Chat 應用程式新增至聊天室時，系統會觸發「新增至聊天室」事件，並傳送事件物件。如要回覆訊息，Chat 應用程式會處理事件物件，並傳回建立訊息的動作。

Chat 應用程式可以在下列介面中建構及顯示資訊卡：

訊息：可包含文字、靜態或互動式資訊卡，以及按鈕。
對話方塊：這類資訊卡會在新的視窗中開啟，通常會提示使用者提交資訊。
連結預覽：顯示外部服務相關資訊的預覽資訊卡。

觸發條件

本節說明 Google Workspace 外掛程式在 Google Chat 中使用的觸發條件。

觸發條件是指使用者透過 Chat UI 叫用 Chat 應用程式的特定方式，例如使用 @提及或應用程式指令。

下表列出即時通訊觸發條件、說明，以及即時通訊應用程式通常的回應方式：

觸發條件	說明	一般回覆
新增至聊天室	使用者將 Chat 應用程式新增至聊天室，或 Google Workspace 管理員為機構中的使用者，在即時訊息聊天室中安裝 Chat 應用程式。如要瞭解管理員安裝的 Chat 應用程式，請參閱 Google Workspace 管理員說明文件中的「在網域內安裝 Marketplace 中的應用程式」。	Chat 應用程式會傳送入門訊息，說明應用程式的功能，以及聊天室使用者與應用程式的互動方式。
訊息	使用者透過下列其中一種方式與 Chat 應用程式中的訊息互動：透過 Chat 應用程式，在即時訊息 (DM) 聊天室中傳送訊息。在任何類型的聊天室中 @提及 Chat 應用程式。傳送包含符合連結預覽網址模式的訊息。在小工具的複選選單中輸入文字。 `selectionInput`	Chat 應用程式會根據訊息內容回覆。舉例來說，Chat 應用程式會回覆斜線指令 `/about`，並說明 Chat 應用程式可執行的工作。
已從聊天室中移除	使用者從聊天室移除 Chat 應用程式，或 Google Workspace 管理員為機構中的使用者解除安裝 Chat 應用程式。使用者無法移除管理員安裝的 Chat 擴充應用程式。如果使用者先前已安裝 Chat 應用程式，即使 Google Workspace 管理員嘗試解除安裝，Chat 應用程式仍會保留在裝置上。	Chat 應用程式會移除為聊天室設定的所有通知 (例如刪除 Webhook)，並清除所有內部儲存空間。即時通訊應用程式已不是聊天室成員，因此無法回覆這個觸發事件。
應用程式指令	使用者使用 Chat 應用程式指令。	Chat 應用程式會回應指令。For example, replies with a message or opens a dialog.

與其他 Google Workspace 外掛程式不同，您必須使用 Google Chat API，為這些觸發條件設定任何回呼函式。如需相關指引，請參閱「設定 Google Chat 應用程式」。

如要回應觸發條件，請參閱下列指南：

事件物件

當 Chat 觸發條件觸發時，或當 Chat 使用者與 Chat 應用程式的 UI 互動時 (例如點選按鈕)，Chat 應用程式會收到事件物件。事件物件包含互動資料，Chat 應用程式可用於回應或更新 UI。

如要瞭解如何處理事件物件，請參閱下列指南：

如要瞭解 Chat 和其他 Google Workspace 應用程式中的外掛程式事件物件，請參閱「事件物件」。

聊天室活動

本節說明 Chat 擴充應用程式如何使用外掛程式動作回應使用者互動。

如要使用外掛程式動作回覆，Chat 應用程式必須在 30 秒內回覆，且回覆內容必須發布在互動發生的聊天室中。否則，Chat 擴充應用程式必須設定驗證機制，並呼叫 Google Chat API 來回應。

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

如要回應使用者互動，Chat 應用程式必須處理相應的事件物件，並傳回下列其中一個 JSON 物件：

DataActions：建立或更新 Google Workspace 資料。如要傳送或更新即時通訊訊息，物件必須包含定義 Message 資料變更的標記，以 chatDataActionMarkup 表示。
RenderActions：建立或更新對話方塊，或為多選選單提供輸入建議。
AuthorizationError：提示使用者透過授權卡登入或驗證 Google 外部服務。在 Chat 中，系統僅支援基本授權卡。

下表說明 Chat 應用程式如何透過動作回應。Chat 應用程式可以傳回 JSON 物件，或使用 Apps Script 的 AddOnResponseService 建構回應。

Chat 應用程式回覆	傳回必要動作 (JSON)	傳回的必要動作 (Apps Script)
傳送或更新訊息。	`DataActions`	`DataActionsResponse`
開啟、更新或關閉對話方塊。	`RenderActions`	`ActionResponse`
如要從資訊卡或對話方塊收集資訊，請根據使用者在多選選單中輸入的內容，建議選取項目。	`RenderActions`	`ActionResponse`
Chat 使用者在聊天室中傳送的訊息預覽連結。	`DataActions`	`DataActionsResponse`

使用 Google Chat API 回覆

Chat 擴充應用程式可能需要使用 Google Chat API 回應互動，而不是傳回外掛程式動作。舉例來說，Chat 應用程式必須呼叫 Google Chat API，才能執行下列任一操作：

在 30 秒後回應互動。
在互動發生的空間以外執行工作。
在 Chat 中執行無法透過外掛程式動作執行的工作。舉例來說，列出使用者或 Chat 應用程式所屬的聊天室，或將使用者新增至聊天室。
代表 Chat 使用者執行工作 (需要使用者驗證)。

如要在 30 秒後回應互動事件，請務必在 30 秒內傳送空白回覆來確認收到互動事件，以免使用者看到「Chat 擴充應用程式未回應」的錯誤訊息，如下所示：

Node.js

async function onEvent(req, res) {
  // Trigger asynchronous job that will respond using the Google Chat API.
  ...

  // Respond with an empty response to the Google Chat platform.
  return res.send({});
};

Python

def on_event(event) -> dict:
  # Trigger asynchronous job that will respond using the Google Chat API.
  ...

  # Respond with an empty response to the Google Chat platform.
  return {}

Java

public String onEvent(JsonNode event) {
  // Trigger asynchronous job that will respond using the Google Chat API.
  ...

  // Respond with an empty response to the Google Chat platform.
  return "{}";
}

Apps Script

function onEvent(event) {
  // Trigger asynchronous job that will respond using the Google Chat API.
  ...

  // Respond with an empty response to the Google Chat platform.
  return null;
}

如要瞭解如何驗證及呼叫 Chat API，請參閱「Chat API 總覽」。