Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

建構 Google Chat 介面

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

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

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

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

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

訊息：可包含文字、靜態或互動式資訊卡，以及按鈕。
首頁：與 Chat 應用程式互傳 1:1 即時訊息時，會顯示在「首頁」分頁中。
對話方塊：這類資訊卡會在新的視窗中開啟，通常會提示使用者提交資訊。
連結預覽：顯示外部服務資訊的預覽資訊卡。

觸發條件

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

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

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

觸發條件	說明	一般回覆
已新增至聊天室	使用者將 Chat 應用程式加入聊天室，或 Google Workspace 管理員為機構中的使用者，在即時訊息聊天室中安裝 Chat 應用程式。如要瞭解管理員安裝的 Chat 應用程式，請參閱 Google Workspace 管理員說明文件中的「為貴機構安裝 Marketplace 中的應用程式」。	Chat 應用程式會傳送新手上路訊息，說明應用程式的功能，以及聊天室使用者與應用程式的互動方式。
訊息	使用者透過下列其中一種方式與 Chat 應用程式中的訊息互動：透過 Chat 應用程式在即時訊息聊天室中傳送訊息。在任何類型的聊天室中 @提及 Chat 應用程式。傳送含有符合連結預覽網址模式的訊息。在小工具的複選選單中輸入文字。 `selectionInput`	Chat 應用程式會根據訊息內容回覆。舉例來說，Chat 應用程式會回覆 `/about` 斜線指令，並說明 Chat 應用程式可執行的工作。
已從聊天室中移除	使用者從聊天室移除 Chat 應用程式，或 Google Workspace 管理員為機構中的使用者解除安裝 Chat 應用程式。使用者無法移除管理員安裝的 Chat 擴充應用程式。如果使用者先前已安裝 Chat 應用程式，即使 Google Workspace 管理員嘗試解除安裝，Chat 應用程式仍會保留在裝置上。	Chat 應用程式會移除為聊天室設定的所有通知 (例如刪除 Webhook)，並清除所有內部儲存空間。聊天應用程式無法對這個觸發條件回覆訊息，因為應用程式已不是聊天室成員。
應用程式指令	使用者使用 Chat 應用程式指令。	Chat 應用程式會回覆指令。例如回覆訊息或開啟對話方塊。
應用程式主畫面	使用者在與 Chat 應用程式互傳的個人即時訊息 (DM) 空間中開啟「首頁」分頁，或與首頁資訊卡上的小工具互動。	Chat 應用程式會傳回 `RenderActions` 物件，推送首頁資訊卡 (`pushCard`) 或更新顯示的首頁資訊卡 (`updateCard`)。

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

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

事件物件

當 Chat 觸發程序執行，或 Chat 使用者與 Chat 應用程式的 UI 互動 (例如點選按鈕) 時，Chat 應用程式會收到事件物件。您可以使用事件物件中的互動資料，做出回應或更新 UI。

事件物件酬載

每個 Chat 事件物件都包含 commonEventObject，其中含有主機和平台詳細資料 (hostApp: "CHAT"、clientPlatform、userLocale、userTimezone 和 formInputs)，以及包含 Chat 專屬內容的 chat 物件：

如果是「應用程式首頁」觸發條件 (使用者在與 Chat 應用程式的 1 對 1 即時訊息中開啟「首頁」分頁)，則 chat 物件會包含 chat.user 和 chat.eventTime，但沒有聯集 payload 欄位。使用者點選首頁資訊卡中的按鈕時，事件物件也會包含 commonEventObject.parameters (如果資訊卡含有表單輸入內容，則也會包含 commonEventObject.formInputs)。
如果是聊天室和訊息互動 (「已加入聊天室」、「訊息」、「已從聊天室移除」、「應用程式指令」，或是按鈕和小工具互動)，chat 物件會包含 chat.user、chat.space、chat.eventTime，以及對應的互動酬載 (messagePayload、addedToSpacePayload、removedFromSpacePayload、buttonClickedPayload、widgetUpdatedPayload 或 appCommandPayload)。

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

如要瞭解 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`
如要從資訊卡或對話方塊收集資訊，請根據使用者在多重選單中輸入的內容，建議選取項目。	`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 總覽」。