接收及回覆使用者互動

本頁說明 Google Chat 應用程式如何接收及回應 Google Chat 中的使用者互動。

如要為 Chat 應用程式建構互動式介面,請使用下列元件:

  • 觸發條件:Google Chat 使用者可透過多種方式叫用 Chat 應用程式,例如將應用程式新增至聊天室,或傳送訊息給應用程式。
  • 事件物件:Chat 應用程式從觸發條件或 UI 互動接收的資料。
  • 動作:Chat 應用程式回應互動的方式,例如傳送訊息或傳回以資訊卡為基礎的使用者介面。
Chat 應用程式會從「新增至聊天室」觸發條件接收事件物件
圖 1:使用者將 Chat 應用程式新增至聊天室時,系統會觸發「已新增至聊天室」事件,並傳送事件物件。如要回覆訊息,Chat 應用程式會處理事件物件,並傳回建立訊息的動作。

聊天室應用程式可透過下列方式建構及顯示介面:

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

必要條件

使用者互動的運作方式

使用者與 Chat 應用程式互動時,Google Chat 會叫用已設定的觸發條件,並將事件物件傳送至 Chat 應用程式的端點或函式。Chat 應用程式會處理事件物件,並在 30 秒內同步傳回動作,或使用 Chat API 進行非同步回應。

下圖說明 Google Chat 擴充應用程式如何處理及回應使用者互動:

Google Chat 擴充應用程式處理使用者互動的架構。

觸發條件

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

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

觸發條件 說明 一般回覆
已新增至聊天室

使用者將 Chat 應用程式加入聊天室,或 Google Workspace 管理員為機構中的使用者,在即時訊息聊天室中安裝 Chat 應用程式。如要瞭解管理員安裝的 Chat 應用程式,請參閱 Google Workspace 管理員說明文件中的「為貴機構安裝 Marketplace 中的應用程式」。

Chat 應用程式會傳送新手上路訊息,說明應用程式的功能,以及聊天室使用者與應用程式的互動方式。
訊息

使用者透過下列方式與 Chat 應用程式中的訊息互動:

  • 透過 Chat 應用程式在即時訊息聊天室中傳送訊息。
  • 在任何類型的聊天室中 @提及 Chat 應用程式。
  • 傳送含有符合連結預覽網址模式的訊息。
  • 在小工具的複選選單中輸入文字。 selectionInput
Chat 應用程式會根據訊息內容回覆。例如,Chat 應用程式會回覆訊息、附加連結預覽資訊卡,或在多選選單中建議項目。
已從聊天室中移除

使用者從聊天室移除 Chat 應用程式,或 Google Workspace 管理員為機構中的使用者解除安裝 Chat 應用程式。

使用者無法移除管理員安裝的 Chat 擴充應用程式。如果使用者先前已安裝 Chat 應用程式,即使 Google Workspace 管理員嘗試解除安裝,Chat 應用程式仍會保留在裝置上。

Chat 應用程式會移除為聊天室設定的所有來電通知 (例如刪除 Webhook),並清除所有內部儲存空間。Chat 應用程式已不是聊天室成員,因此無法回覆這個觸發條件的訊息。
應用程式指令

使用者叫用 Chat 應用程式指令 (例如斜線指令、快速指令或訊息動作)。

Chat 應用程式會回覆指令。例如,回覆訊息或開啟對話方塊。
應用程式主畫面

使用者在與 Chat 應用程式互傳的個人即時訊息 (DM) 空間中開啟「首頁」分頁,或與首頁資訊卡上的小工具互動。

Chat 應用程式會傳回 RenderActions 物件,推送首頁資訊卡 (pushCard) 或更新顯示的首頁資訊卡 (updateCard)。

您可以在 Google Cloud 控制台的 Chat API「設定」頁面,設定這些觸發條件的端點或回呼函式。如需逐步操作說明,請參閱「設定 Google Chat API」。

設定啟動提示詞

使用者透過應用程式開啟空白的 1:1 即時訊息時,系統會顯示入門提示,協助他們瞭解 Chat 應用程式的功能。您最多可以設定三個入門提示。

如要新增及設定啟動提示,請按照下列步驟操作:

  1. 在 Google Cloud 控制台中,前往 Chat API 的「Configuration」(設定) 頁面:

    前往 Chat API 設定頁面

  2. 在「互動功能」下方,找到「入門提示」,然後點按「新增提示」。

  3. 在「Rank (1-3)」(排名 (1-3)) 欄位中,輸入 1 到 3 之間的數字,指定顯示順序。

  4. 在「類型選取」下方,選擇提示的運作方式:

    • 文字提示詞:使用者點選提示詞方塊時,撰寫列會填入預先定義的文字。
    • 命令提示字元:點選後會執行已註冊的斜線指令或快速指令。無法選取需要額外引數的指令。
  5. 根據所選類型設定提示:

    • 如果選取「文字提示詞」:

      1. 在「標題」中,輸入顯示在方塊上的提示標題 (最多 30 個半形字元)。
      2. 在「提示文字」中,輸入撰寫列中填入的文字 (最多 60 個半形字元)。
      3. 選用:為其他語言的使用者新增本地化標題和文字:
      4. 在「本地化提示」下方,按一下「新增語言」。
      5. 在「語言」中,從下拉式選單選取支援的語言。
      6. 在「Localized Title」(本地化名稱) 中,輸入本地化名稱 (最多 30 個半形字元)。
      7. 在「Localized Prompt text」(本地化提示文字) 中,輸入本地化提示文字 (最多 60 個半形字元)。
      8. 視需要重複上述步驟,新增更多語言。
    • 如果選取「命令提示字元」:

      1. 在「斜線指令 / 快速指令」中,從下拉式選單選取指令。
  6. 按一下「完成」,然後點選頁面底部的「儲存」。

處理對服務的 HTTP 呼叫重試

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

事件物件

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

事件物件酬載

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

  • 如果是「應用程式首頁」觸發條件 (使用者在與 Chat 應用程式的 1 對 1 即時訊息中開啟「首頁」分頁),則 chat 物件會包含 chat.user 和 chat.eventTime,但沒有聯集 payload 欄位。使用者點選首頁資訊卡中的按鈕時,事件物件會包含 chat.buttonClickedPayload 和 commonEventObject.parameters (如果資訊卡包含表單輸入內容,則會包含 commonEventObject.formInputs)。
  • 如果是聊天室和訊息互動 (「已加入聊天室」、「訊息」、「已從聊天室移除」、「應用程式指令」,或是按鈕和小工具互動),chat 物件會包含 chat.user、chat.space、chat.eventTime 和對應的互動酬載:
    • messagePayload:使用者傳送訊息時,包含 space、message 和 configCompleteRedirectUri。
    • addedToSpacePayload:當 Chat 應用程式新增至聊天室時,會包含 space、interactionAdd 和 configCompleteRedirectUri。
    • removedFromSpacePayload:當 Chat 應用程式從聊天室中移除時,包含 space。
    • buttonClickedPayload:使用者點選資訊卡或對話方塊上的按鈕時,會包含 space、message、isDialogEvent 和 dialogEventType。
    • widgetUpdatedPayload:使用者與小工具互動時 (例如在具有外部資料來源的多重選取選單中輸入內容),會包含 space。
    • appCommandPayload:包含 space、message、appCommandMetadata、isDialogEvent、dialogEventType 和 configCompleteRedirectUri,使用者叫用應用程式指令時會傳送這些值。

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

提供回覆

本節說明 Chat 應用程式如何使用動作,同步回應使用者互動。

如要以動作回應,Chat 應用程式必須在 30 秒內回應,且回應必須套用至發生互動的聊天室。這些同步回應不需要驗證。如果 Chat 應用程式需要超過 30 秒的時間,或需要在聊天室外執行動作,請設定驗證機制,並使用 Google Chat API 進行非同步回應。

如要同步回應使用者互動,您的 Chat 應用程式會處理傳入的事件物件,並傳回下列其中一個 JSON 物件:

  • DataActions:使用 chatDataActionMarkup 建立或更新即時通訊訊息 (CreateMessageAction、UpdateMessageAction),或附加連結預覽 (UpdateInlinePreviewAction)。
  • RenderActions:建立、更新或關閉首頁或對話方塊 (pushCard、updateCard、endNavigation: "CLOSE_DIALOG"),或為多選選單 (modifyCard) 提供動態輸入建議。
  • AuthorizationError:提示使用者使用基本授權卡 (basic_authorization_prompt) 登入或驗證外部服務。

下表說明 Chat 應用程式如何透過動作回應。Chat 應用程式可以直接傳回 JSON 物件,也可以使用 Apps Script 的 AddOnResponseService 和 CardService 建構回應。

Chat 應用程式回覆 傳回的必要動作 (JSON) 傳回的必要動作 (Apps Script)
傳送訊息或更新訊息。 DataActions (createMessageAction 或 updateMessageAction) DataActionsResponse
預覽連結:在聊天室中,預覽 Chat 使用者傳送的訊息。 DataActions (updateInlinePreviewAction) DataActionsResponse
在即時訊息的「首頁」分頁中,算繪或更新首頁。 RenderActions (pushCard 或 updateCard) ActionResponse
開啟、更新或關閉對話方塊。 RenderActions (pushCard、updateCard 或 endNavigation: "CLOSE_DIALOG") ActionResponse
如要從資訊卡或對話方塊收集資訊,請根據使用者在多選選單中輸入的內容,建議選取項目。 RenderActions (modifyCard) ActionResponse
要求設定或授權外部服務。 AuthorizationError (basic_authorization_prompt) AuthorizationException

使用訊息回覆

對話應用程式可以針對下列任一觸發條件或互動,回覆訊息:

  • 訊息觸發條件,例如使用者 @提及或直接傳送訊息給 Chat 應用程式。
  • 已加入聊天室觸發條件,例如使用者從 Google Workspace Marketplace 安裝 Chat 應用程式,或將其新增至聊天室時。
  • 應用程式指令觸發,例如使用者叫用斜線指令或快速指令時。
  • 訊息或對話方塊中的資訊卡按鈕點擊次數。舉例來說,使用者輸入資訊並點選「提交」時。

即時通訊應用程式可以在訊息中加入下列任一項目:

  • 包含超連結、@提及和表情符號的文字。請參閱「設定郵件格式」。
  • 一或多張資訊卡,可顯示在訊息中,或在新視窗中以對話方塊形式開啟。請參閱「為 Google Chat 應用程式建構資訊卡」。
  • 一或多個配件小工具,也就是顯示在郵件中任何文字或資訊卡後方的按鈕。

如要回覆訊息,請傳回 DataActions 和 CreateMessageAction 物件:

{
  "hostAppDataAction": {
    "chatDataAction": {
      "createMessageAction": {
        "message": <var>MESSAGE</var>
      }
    }
  }
}

將 MESSAGE 替換為 Chat API 的 Message 資源。

在下列範例中,每當 Chat 應用程式新增至聊天室時,都會透過回應「已新增至聊天室」觸發條件和 DataActions,建立並傳送新手指引簡訊:

Node.js

/**
 * Sends an onboarding message when the Chat app is added to a space.
 *
 * @param {Object} req The request object from Google Chat.
 * @param {Object} res The response object from the Chat app.
 */
exports.cymbalApp = function cymbalApp(req, res) {
  const chatEvent = req.body.chat;
  // Send an onboarding message when added to a Chat space
  if (chatEvent.addedToSpacePayload) {
    res.json({ hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
      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.
  """
  chat_event = request.get_json()["chat"]
  if "addedToSpacePayload" in chat_event:
    return json.jsonify({ "hostAppDataAction": { "chatDataAction": {
      "createMessageAction": { "message": {
        "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`.'
      }}
    }}})

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 GenericJson onEvent(@RequestBody JsonNode event) throws Exception {
    JsonNode chatEvent = event.at("/chat");
    if (!chatEvent.at("/addedToSpacePayload").isEmpty()) {
      return new GenericJson() { {
        put("hostAppDataAction", new GenericJson() { {
          put("chatDataAction", new GenericJson() { {
            put("createMessageAction", new GenericJson() { {
              put("message", 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`."
              ));
            } });
          } });
        } });
      } };
    }
    return new GenericJson();
  }
}

Apps Script

/**
 * Sends an onboarding message when the Chat app is added to a space.
 *
 * @param {Object} event The event object from Google Chat.
 * @return {Object} Response from the Chat app.
 */
function onAddedToSpace(event) {
  return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
    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 應用程式可以更新訊息。

如要更新 Chat 應用程式訊息以回應互動,請傳回 DataActions 和 UpdateMessageAction:

{
  "hostAppDataAction": {
    "chatDataAction": {
      "updateMessageAction": {
        "message": <var>MESSAGE</var>
      }
    }
  }
}

將 MESSAGE 替換為 Chat API 的 Message 資源。

Chat 擴充應用程式也可以使用 updateInlinePreviewAction 更新使用者傳送的訊息,附加連結預覽資訊卡。詳情請參閱「預覽連結」。

使用 Google Chat API 進行非同步回覆

Chat 應用程式可能需要呼叫 Google Chat API,才能回應互動或傳送主動式訊息,而不是同步傳回動作。舉例來說,Chat 應用程式必須呼叫 Google Chat API,才能執行下列操作:

  • 在 30 秒後回應互動 (例如完成長時間執行的工作後)。
  • 排定訊息傳送時間,或傳送外部資源變更通知。
  • 在互動發生的空間以外執行工作。
  • 在 Chat 中執行無法以同步動作執行的工作,例如列出聊天室或在聊天室中新增成員。
  • 代表 Google Chat 使用者執行工作 (需要使用者驗證)。

在 30 秒後回應互動時,為避免使用者看到「Chat 應用程式未回應」的錯誤訊息,您必須在 30 秒內傳回空白回應,確認收到事件物件:

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 傳送訊息,請設定驗證並呼叫 spaces.messages.create 方法。如需操作步驟,請參閱「傳送訊息」。如需使用其他 Chat API 方法的指南,請參閱 Chat API 總覽。

非外掛程式的 Chat 應用程式:接收及回應使用者互動

不是 Google Workspace 外掛程式的即時通訊應用程式會收到Chat API 互動事件 (Event),而不是 Google Workspace 外掛程式事件物件 (EventObject),並傳回 Message 資源而非動作來回應。

如要將非外掛程式的 Chat 應用程式升級至 Google Workspace 外掛程式架構,請參閱「將 Google Chat 應用程式轉換為 Google Workspace 外掛程式」。

互動事件類型

針對每種使用者互動,Google Chat 會傳送 Event 物件給非外掛程式的 Chat 應用程式,物件的類型由 eventType 欄位表示:

使用者互動 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 應用程式可執行的工作。

如要查看所有支援的互動事件和 JSON 酬載範例,請參閱「Types of Chat app interaction events」(Chat 擴充應用程式互動事件類型) 和EventType參考文件。

對話方塊的互動事件

如果 Chat 應用程式 (非外掛程式) 開啟對話方塊,互動事件會包含下列額外資訊,可用於處理回覆:

  • isDialogEvent 欄位設為 true。
  • DialogEventType (REQUEST_DIALOG、SUBMIT_DIALOG 或 CANCEL_DIALOG) 可說明互動是否會觸發開啟對話方塊、從對話方塊提交資訊,或關閉對話方塊。

設定非外掛程式的 Chat 應用程式,以接收互動事件

  1. 在 Google Cloud 控制台中,前往 Chat API 的「Configuration」(設定) 頁面:

    前往 Chat API 設定頁面

  2. 在「互動功能」下方,取消勾選「將這個 Chat 應用程式建構為 Google Workspace 外掛程式」,然後設定「功能」、單一「連線設定」端點 (HTTP 端點網址、Apps Script、Cloud Pub/Sub 主題名稱或 Dialogflow)、「指令」、「啟動提示詞」、「連結預覽」和「顯示設定」。

  3. 按一下 [儲存]。

透過非外掛程式的 Chat 擴充應用程式回覆訊息

如要在非外掛程式的 Chat 應用程式中同步回應,請直接傳回 Message 物件。以下範例會以簡訊回應 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`.'
  };
}