建構 Google Chat 介面

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

在 Google Chat 中，使用者會看到附加元件，就像是 Google Chat 應用程式一樣。詳情請參閱「擴充 Google Chat 總覽」。

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

  • 觸發事件：Google Chat 使用者可用來叫用 Chat 應用程式的方式，例如將應用程式新增至聊天室或傳送訊息。
  • 事件物件：即時通訊應用程式從觸發事件或 UI 互動收到的資料。
  • 動作：聊天應用程式回應互動的方式，例如傳送訊息或傳回資訊卡式使用者介面。
Chat 應用程式會從「新增至聊天室」觸發條件收到事件物件
圖 1：當使用者將 Chat 應用程式新增至聊天室時，新增至聊天室 觸發事件會觸發並傳送事件物件。如要回覆訊息，Chat 應用程式會處理事件物件，並傳回建立訊息的動作。

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

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

觸發條件

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

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

下表列出 Chat 觸發事件、說明，以及 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 應用程式會回應指令。例如回覆訊息或開啟對話方塊。

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

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

事件物件

本節會定義並說明 Chat 事件物件的所有元素。詳情請參閱「事件物件」。

事件物件
commonEventObject object (CommonEventObject)
物件，其中包含所有事件物件共用的資訊，不受主機應用程式影響。
chat object (Chat)
物件，其中包含 Chat 互動相關的所有資訊。

即時通訊

即時通訊
chat.user object (User)
與 Chat 應用程式互動的 Chat 使用者。
chat.space object (Space)
使用者與 Chat 應用程式互動的 Chat 空間。
chat.eventTime

string (Timestamp format)

互動發生的時間。

聯集欄位 payload。

payload 只能是下列其中一項：
chat.messagePayload

object (MessagePayload)

Chat 應用程式從「訊息」觸發事件收到的酬載。
chat.addedToSpacePayload

object (AddedToSpacePayload)

Chat 應用程式從「加入聊天室」觸發事件收到的酬載。
chat.removedFromSpacePayload

object (RemovedFromSpacePayload)

Chat 應用程式從「從聊天室中移除」觸發事件收到的酬載。
chat.buttonClickedPayload

object (ButtonClickedPayload)

使用者點選訊息或資訊卡中的按鈕時，Chat 應用程式收到的酬載。如果使用者按一下按鈕提交資訊，commonEventObject.formInputs 物件就會包含從使用者收集到的值。詳情請參閱「 從 Google Chat 使用者收集資訊」。
chat.widgetUpdatedPayload

object (WidgetUpdatedPayload)

當使用者在 selectionInput 小工具的多重選取選單中輸入文字時，Chat 應用程式收到的酬載。聊天應用程式可以使用這個事件物件，從動態資料來源填入建議項目。舉例來說，如要從外部資料來源填入支援案件，Chat 應用程式可以根據使用者在選單中輸入的內容查詢資料來源，然後將任何相符的支援案件做為可選項目傳回。

CommonEventObject.parameters['autocomplete_widget_query'] 物件包含使用者輸入至選單的字串值。
chat.appCommandPayload

object (AppCommandPayload)

使用者使用 Chat 應用程式中的指令時，Chat 應用程式收到的酬載。

酬載

視互動類型而定，事件會包含含有一或多個 Chat API 資源的酬載。

訊息酬載
MessagePayload
chat.messagePayload.message object (Message)
觸發事件的 Chat 訊息。
chat.messagePayload.space object (Space)
使用者傳送喚出 Chat 應用程式的訊息所在的 Chat 聊天室。

已新增至聊天室酬載
AddedToSpacePayload
chat.addedToSpacePayload.space object (Space)
使用者新增或安裝 Chat 應用程式的 Chat 聊天室。

當管理員安裝 Chat 應用程式時，space.adminInstalled 欄位會設為 true。
chat.addedToSpacePayload.interactionAdd boolean
使用者是否使用訊息將 Chat 應用程式新增至聊天室。例如，@提及 Chat 應用程式或使用斜線指令。如果是 true，Chat 會傳送另一個事件物件，其中包含訊息相關資訊的 messagePayload。

已從聊天室酬載中移除
RemovedFromSpacePayload
chat.removedFromSpacePayload.space object (Space)
使用者移除或解除安裝 Chat 應用程式的 Chat 聊天室。

當管理員解除安裝 Chat 應用程式時，space.adminInstalled 欄位會設為 false。

按鈕點擊酬載
ButtonClickedPayload
chat.buttonClickedPayload.message object (Message)
包含使用者按下的按鈕的即時通訊訊息。
chat.buttonClickedPayload.space object (Space)
使用者在 Chat 應用程式訊息中按下按鈕的 Chat 聊天室。
chat.buttonClickedPayload.isDialogEvent boolean
使用者是否點選按鈕，與對話方塊互動。
chat.buttonClickedPayload.dialogEventType enum (DialogEventType)
如果 isDialogEvent 為 true，則為對話方塊中的互動類型。

列舉 DialogEventType。

dialogEventType 的值只能是下列其中一個：
TYPE_UNSPECIFIED 預設值。未指明
REQUEST_DIALOG 使用者要求對話方塊。例如使用斜線指令或點選訊息中的按鈕。
SUBMIT_DIALOG 使用者點選對話方塊中的互動式元素。舉例來說，使用者在對話方塊中填寫資訊，然後按一下按鈕提交資訊。

小工具更新酬載
WidgetUpdatedPayload
chat.widgetUpdatedPayload.space object (Space)
發生互動的 Chat 聊天室。

應用程式指令酬載
AppCommandPayload
chat.appCommandPayload.appCommandMetadata object (AppCommandMetadata)
關於使用者所使用的指令，以及他們如何觸發指令的中繼資料。
chat.appCommandPayload.space object (Space)
使用者使用指令的 Chat 聊天室。
chat.appCommandPayload.thread object (Thread)
如果互動發生在某個會話串中，則為使用者使用指令的 Chat 會話串。
chat.appCommandPayload.message object (Message)
使用者透過斜線指令傳送的訊息。
chat.appCommandPayload.configCompleteRedirectUri string
如果指令需要授權或設定，則是指在使用者完成 Google Chat 以外的程序後，將使用者重新導向至的網址。
chat.appCommandPayload.isDialogEvent boolean
指令是否會開啟對話方塊。
chat.appCommandPayload.dialogEventType enum (DialogEventType)
與對話方塊互動的類型。

列舉 DialogEventType。

dialogEventType 的值只能是下列其中一個：
TYPE_UNSPECIFIED 預設值。未指明
REQUEST_DIALOG 使用者要求對話方塊。例如使用斜線指令或點選訊息中的按鈕。
SUBMIT_DIALOG 使用者點選對話方塊中的互動式元素。舉例來說，使用者在對話方塊中填寫資訊，然後按一下按鈕提交資訊。
應用程式指令中繼資料
AppCommandMetadata
chat.appCommandPayload.appCommandMetadata.appCommandId

string (int64 format)

指令 ID。
chat.appCommandPayload.appCommandMetadata.appCommandType enum (AppCommandType)
指令類型。

列舉 AppCommandType。

AppCommandType 的值只能是下列其中一個：
APP_COMMAND_TYPE_UNSPECIFIED 預設值。未指明
SLASH_COMMAND 使用者傳送開頭為斜線 / 的訊息，即可使用這項指令。

聊天室活動

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

如要回應附加動作，Chat 應用程式必須在 30 秒內回應，且回應必須張貼在發生互動的聊天室中。否則，Chat 應用程式必須設定驗證，並呼叫 Google Chat API 回應。

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

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

Chat 應用程式所需回應 退貨所需的行動
傳送或更新訊息。 DataActions
開啟、更新或關閉對話方塊。 RenderActions
如要收集資訊，請根據使用者在多重選取選單中輸入的內容，建議選取項目。 RenderActions
在 Chat 使用者在聊天室中傳送的訊息中預覽連結。 DataActions

使用 Google Chat API 回覆

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

  • 在 30 秒後回應互動。
  • 在互動發生的聊天室外執行工作。
  • 在 Chat 中執行無法做為外掛程式操作的任務。舉例來說，您可以列出使用者或 Chat 應用程式所屬的聊天室，或是將使用者加入聊天室。
  • 代表 Chat 使用者執行工作 (需要使用者驗證)。

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