本頁說明 Google Chat 應用程式如何接收及回應使用者互動，也就是所謂的 Google Chat 應用程式互動事件。
本頁說明如何執行下列操作：
- 設定 Chat 應用程式，接收互動事件。
- 在基礎架構上處理互動事件。
- 視情況回應互動事件。
必要條件
- 公司或企業專用 Google Workspace 帳戶，且可存取 Google Chat。
- 建立 Google Cloud 專案。
- 設定 OAuth 同意畫面。
- 啟用 Google Chat API。
互動事件類型
Google Chat 應用程式互動事件是指使用者為叫用或與 Chat 應用程式互動而執行的任何動作，例如 @提及 Chat 應用程式或將其新增至聊天室。
使用者與 Chat 應用程式互動時，Google Chat 會傳送互動事件給 Chat 應用程式，這類事件在 Chat API 中以 Event 型別表示。Chat 應用程式可使用事件處理互動，並視需要回覆訊息。
針對每種使用者互動，Google Chat 會傳送不同類型的互動事件，協助 Chat 應用程式相應處理各個事件類型。互動事件類型會以 eventType 物件表示。
舉例來說，使用者將 Chat 擴充應用程式新增至聊天室時，Google Chat 會使用 ADDED_TO_SPACE 事件類型，讓 Chat 擴充應用程式立即在聊天室中傳送歡迎訊息。
ADDED_TO_SPACE 互動事件，並處理該事件，在聊天室中傳送歡迎訊息。下表列出常見的使用者互動、Chat 擴充應用程式收到的互動事件類型，以及 Chat 擴充應用程式通常的回應方式：
| 使用者互動 | eventType |
Chat 應用程式的典型回覆 |
|---|---|---|
| 使用者傳送訊息給 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 應用程式會回覆「About」指令，說明 Chat 應用程式可執行的工作。 |
如要查看所有支援的互動事件，請參閱EventType參考文件。
對話方塊的互動事件
如果 Chat 應用程式開啟對話方塊，互動事件會包含下列額外資訊，可用於處理回覆：
isDialogEvent設為true。DialogEventType說明互動是否會觸發開啟對話方塊、從對話方塊提交資訊，或關閉對話方塊。
下表列出與對話方塊的常見互動、對應的對話方塊事件類型，以及 Chat 應用程式通常的回應方式說明：
| 使用者與對話方塊的互動 | 對話事件類型 | 一般回覆 |
|---|---|---|
| 使用者觸發對話要求。例如使用斜線指令或點選訊息中的按鈕。 | REQUEST_DIALOG |
Chat 應用程式會開啟對話方塊。 |
| 使用者點選按鈕，在對話方塊中提交資訊。 | SUBMIT_DIALOG |
Chat 應用程式會導覽至另一個對話方塊，或關閉對話方塊來完成互動。 |
| 使用者在提交資訊前離開或關閉對話方塊。 | CANCEL_DIALOG |
Chat 應用程式也可以視需要回覆新訊息，或更新使用者開啟對話方塊的訊息或資訊卡。 |
詳情請參閱「開啟互動式對話方塊」。
接收 Chat 應用程式互動事件
本節說明如何接收及處理 Google Chat 應用程式的互動事件。
設定 Chat 擴充應用程式以接收互動事件
並非所有 Chat 應用程式都具備互動功能。舉例來說，連入的 Webhook 只能傳送外寄訊息，無法回覆使用者。如要建構互動式 Google Chat 應用程式，請務必選擇端點，讓 Chat 應用程式接收、處理及回覆互動事件。如要進一步瞭解如何設計 Chat 應用程式，請參閱「Chat 應用程式實作架構」。
如要建構互動式功能，請務必更新 Chat API 中的設定，讓 Google Chat 將相關的互動事件傳送至 Chat 應用程式：
前往 Google Cloud 控制台的 Chat API 頁面，然後按一下「Configuration」(設定) 頁面：
在「互動式功能」下方，查看設定並根據要建構的功能更新：
欄位 說明 功能 必填。一組欄位，可決定 Chat 應用程式與使用者互動的方式。根據預設，使用者可以在 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 應用程式」。
指令 (選用步驟) Chat 擴充應用程式的斜線指令和快速指令。使用者可以透過指令要求執行動作，或使用 Chat 擴充應用程式的特定功能。詳情請參閱「回應 Google Chat 擴充應用程式指令」。 啟動提示詞 (選用步驟) ( 開發人員預覽版)
：使用者透過 Chat 應用程式開啟空白的 1 對 1 即時訊息時，最多會顯示三個初始提示詞。提示詞可以在撰寫區域填入文字 (支援多種語言的在地化)，或直接觸發斜線/快速指令。詳情請參閱「設定啟動提示」。連結預覽 (選用步驟) Chat 應用程式可辨識的網址模式，並能在使用者傳送連結時提供額外內容。詳情請參閱「預覽連結」。 瀏覽權限 (選用步驟) 最多五位使用者，或一或多個可查看及安裝 Chat 擴充應用程式的 Google 群組。您可以使用這個欄位測試 Chat 擴充應用程式，或與團隊分享。詳情請參閱「測試互動功能」。 按一下 [儲存]。儲存 Chat 應用程式設定後，Google Workspace 機構中指定的使用者就能使用該應用程式。
Chat 擴充應用程式現已設為接收 Google Chat 的互動事件。
設定啟動提示詞
使用者透過應用程式開啟空白的 1:1 即時訊息時，系統會顯示入門提示，協助他們瞭解 Chat 應用程式的功能。您最多可以設定三個入門提示。
如要新增及設定啟動提示，請按照下列步驟操作：
在 Google Cloud 控制台中，前往 Chat API 的「Configuration」(設定) 頁面：
在「互動功能」下方，找到「入門提示」，然後點按「新增提示」。
在「Rank (1-3)」(排名 (1-3)) 欄位中，輸入
1到3之間的數字，指定顯示順序。在「類型選取」下方，選擇提示的運作方式：
- 文字提示詞：使用者點選提示詞方塊時，撰寫列會填入預先定義的文字。
- 命令提示字元：點選後會執行已註冊的斜線指令或快速指令。無法選取需要額外引數的指令。
根據所選類型設定提示：
如果選取「文字提示詞」：
- 在「標題」中，輸入顯示在方塊上的提示標題 (最多 30 個半形字元)。
- 在「提示文字」中，輸入撰寫列中填入的文字 (最多 60 個半形字元)。
- 選用：為其他語言的使用者新增本地化標題和文字：
- 在「本地化提示」下方，按一下「新增語言」。
- 在「語言」中，從下拉式選單選取支援的語言。
- 在「Localized Title」(本地化名稱) 中，輸入本地化名稱 (最多 30 個半形字元)。
- 在「Localized Prompt text」(本地化提示文字) 中，輸入本地化提示文字 (最多 60 個半形字元)。
- 視需要重複上述步驟，新增更多語言。
如果選取「命令提示字元」：
- 在「斜線指令 / 快速指令」中，從下拉式選單選取指令。
按一下「完成」，然後點選頁面底部的「儲存」。
處理對服務的 HTTP 呼叫重試
如果對服務發出的 HTTPS 要求失敗 (例如逾時、暫時性網路故障或非 2xx HTTPS 狀態碼)，Google Chat 可能會在幾分鐘內重試傳送幾次 (但無法保證)。因此，在某些情況下，Chat 應用程式可能會收到同一則訊息好幾次。如果要求順利完成，但傳回無效的訊息酬載，Google Chat 不會重試要求。
處理或回應互動事件
本節說明 Google Chat 應用程式如何處理及回應互動事件。
Chat 應用程式收到 Google Chat 的互動事件後，可以透過多種方式回應。在許多情況下，互動式 Chat 應用程式會回覆使用者訊息。Google Chat 應用程式也可以從資料來源查詢某些資訊、記錄互動事件資訊，或執行其他任何動作。這項處理行為基本上就是 Google Chat 應用程式的定義。
如要同步回應，Chat 應用程式必須在 30 秒內回覆，且回覆內容必須發布在互動發生的聊天室中。否則，Chat 應用程式可以非同步回覆。
對於每個互動事件，Chat 應用程式都會收到要求主體，也就是代表事件的 JSON 酬載。您可以根據這些資訊處理回覆。如需事件酬載範例，請參閱「Chat 應用程式互動事件類型」。
下圖說明 Google Chat 應用程式通常如何處理或回應不同類型的互動事件：
即時回覆
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.
*/
exports.cymbalApp = function cymbalApp(req, res) {
// 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`.'
});
}
};
Python
from flask import Flask, request, json
app = Flask(__name__)
@app.route('/', methods=['POST'])
def cymbal_app():
"""Sends an onboarding message when the Chat app is added to a space.
Returns:
Mapping[str, Any]: The response object from the Chat app.
"""
event = request.get_json()
if event['type'] == 'ADDED_TO_SPACE':
return json.jsonify({
'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`.'
})
return json.jsonify({})
Java
@SpringBootApplication
@RestController
public class App {
public static void main(String[] args) {
SpringApplication.run(App.class, args);
}
/*
* Sends an onboarding message when the Chat app is added to a space.
*
* @return The response object from the Chat app.
*/
@PostMapping("/")
@ResponseBody
public Message onEvent(@RequestBody JsonNode event) {
switch (event.get("type").asText()) {
case "ADDED_TO_SPACE":
return new Message().setText(
"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`.");
default:
return new Message();
}
}
}
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.
*/
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 應用程式可以呼叫 Google Chat API，以非同步方式回覆。
如要使用 Chat API 建立訊息，請參閱「建立訊息」。如需使用其他 Chat API 方法的指南，請參閱 Chat API 總覽。