以 Google Chat 應用程式的形式回應斜線指令

本頁面說明如何設定 Google Chat 應用程式的斜線指令,並回應這些指令。

斜線指令是使用者叫用 Chat 應用程式並與之互動的常見方式。Slash 指令也會協助使用者探索及使用 Chat 應用程式的主要功能。

如要使用斜線指令,使用者請輸入斜線 (/),然後輸入簡短文字指令,例如 /about,即可取得 Chat 應用程式相關資訊。使用者只要在 Google Chat 中輸入斜線,系統就會顯示一個視窗,列出 Chat 應用程式可用的指令:

斜線指令視窗
圖 1:使用者在 Google Chat 中輸入斜線時顯示的視窗。

如要決定是否應設定斜線指令,以及瞭解如何設計使用者互動,請參閱「定義所有使用者歷程」。

含有私人回應的斜線指令

當使用者傳送含有斜線指令的訊息時,只有使用者和 Chat 應用程式可看到該訊息。如果您已將 Chat 應用程式加入含有多位使用者的聊天室,建議您私下回應斜線指令,以便保留使用者和 Chat 應用程式之間的私人互動。

舉例來說,使用者可以使用 /about/help 等指令,瞭解在聊天室中探索的 Chat 應用程式。為避免通知聊天室中的其他使用者,Chat 應用程式可私下回覆,說明如何使用 Chat 應用程式和取得支援。

必要條件

Node.js

已啟用互動功能的 Google Chat 應用程式。如要使用 HTTP 服務建立互動式 Chat 應用程式,請完成這個快速入門導覽課程

Apps Script

已啟用互動功能的 Google Chat 應用程式。如要在 Apps Script 中建立互動式 Chat 應用程式,請完成這個快速入門

Python

已啟用互動功能的 Google Chat 應用程式。如要使用 HTTP 服務建立互動式 Chat 應用程式,請完成這個快速入門導覽課程

Java

已啟用互動功能的 Google Chat 應用程式。如要使用 HTTP 服務建立互動式 Chat 應用程式,請完成這個快速入門導覽課程

設定斜線指令

本節說明如何完成下列步驟,設定斜線指令:

  1. 為斜線指令命名
  2. 在 Google Chat API 中設定斜線指令

為斜線指令命名

斜線指令的名稱是使用者在 Chat 訊息中輸入的內容,用於叫用 Chat 應用程式。名稱下方也會顯示簡短說明,進一步提示使用者如何使用指令:

斜線指令名稱和說明
圖 2:斜線指令的名稱和說明。

選擇斜線指令的名稱和說明時,請考慮下列建議:

  • 如要為斜線指令命名:

    • 使用簡短、敘述性且可行的字詞或詞組,讓使用者更容易瞭解指令。例如,使用 /remindMe,而不使用 /createAReminder
    • 如果指令包含多個字詞,請使用小寫字母輸入第一個字詞,然後將其他字詞的首字母改為大寫,方便使用者閱讀指令。例如,使用 /updateContact,而不使用 /updatecontact
    • 請考慮要為指令使用不重複或常見的名稱。如果指令描述的是一般互動或功能,您可以使用使用者熟悉且期待的常用名稱,例如 /settings/feedback。否則,請嘗試使用不重複的指令名稱,因為如果其他 Chat 應用程式的指令名稱相同,使用者就必須篩選類似的指令,以尋找並使用您的指令名稱。
  • 如何描述斜線指令:

    • 請簡短明確地說明,讓使用者知道執行指令時會發生什麼事。
    • 請告知使用者指令是否有任何格式規定。舉例來說,如果您建立需要引數文字的 /remindMe 指令,請將說明設為 Remind me to do [something] at [time] 之類的內容。
    • 請讓使用者知道 Chat 應用程式會回覆聊天室中的所有人,還是只回覆叫用指令的使用者。例如,如果是斜線指令 /about,您可以將其描述為 Learn about this app (Only visible to you)

在 Google Chat API 中設定斜線指令

如要建立斜線指令,您必須在 Chat 應用程式的 Google Chat API 設定中指定指令相關資訊。

如要在 Google Chat API 中設定斜線指令,請完成下列步驟:

  1. 在 Google Cloud 控制台中,依序點選「Menu」圖示 >「API 和服務」 >「已啟用的 API 和服務」 >「Google Chat API」

    前往 Google Chat API 頁面

  2. 按一下「設定」

  3. 在「斜線指令」下方,按一下「新增斜線指令」

  4. 輸入指令的名稱、指令 ID 和說明:

    1. 「Name」:指令的顯示名稱,以及使用者叫用應用程式的輸入內容。必須以斜線開頭、只包含文字,長度上限為 50 個半形字元。
    2. 說明:說明指令的使用方式及設定格式的文字。說明長度上限為 50 個半形字元。
    3. 指令 ID:Chat 應用程式用來辨識斜線指令並傳回回應的 1 到 1000 之間的數字。
  5. 選用:如要讓 Chat 應用程式以對話方塊回應指令,請選取「Open a dialog」核取方塊。

  6. 按一下 [儲存]

系統隨即會為 Chat 應用程式設定斜線指令。

回應斜線指令

當使用者建立含有斜線指令的 Chat 訊息時,Chat 應用程式會收到 MESSAGE 互動事件。事件酬載包含 slashCommandslashCommandMetadata 物件。這些物件含有訊息中使用的指令詳細資料 (包括指令 ID),方便您傳回適當的回應。

Cymbal Labs Chat 應用程式的私人訊息。這則訊息顯示 Chat 應用程式是由 Cymbal Labs 所建立,並分享說明文件連結,以及與支援團隊聯絡的連結。
Chat 應用程式會私下回應斜線指令 /help,說明如何取得支援。

以下程式碼示範如何透過處理 MESSAGE 互動事件並偵測訊息是否包含相符的指令 ID,藉此回覆 /about 斜線指令。如果訊息包含指令 ID,Chat 應用程式會傳回私人訊息:

Node.js

node/avatar-app/index.js
// Checks for the presence of a slash command in the message.
if (event.message.slashCommand) {
  // Executes the slash command logic based on its ID.
  // Slash command IDs are set in the Google Chat API configuration.
  switch (event.message.slashCommand.commandId) {
    case ABOUT_COMMAND_ID:
      return res.send({
        privateMessageViewer: event.user,
        text: 'The Avatar app replies to Google Chat messages.'
      });
  }
}

Apps Script

apps-script/avatar-app/avatar-app.gs
// Checks for the presence of a slash command in the message.
if (event.message.slashCommand) {
  // Executes the slash command logic based on its ID.
  // Slash command IDs are set in the Google Chat API configuration.
  switch (event.message.slashCommand.commandId) {
    case ABOUT_COMMAND_ID:
      return {
        privateMessageViewer: event.user,
        text: 'The Avatar app replies to Google Chat messages.'
      };
  }
}

Python

python/avatar-app/main.py
# Checks for the presence of a slash command in the message.
if "slashCommand" in request_json["message"]:
  # Executes the slash command logic based on its ID.
  # Slash command IDs are set in the Google Chat API configuration.
  if request_json["message"]["slashCommand"]["commandId"] == ABOUT_COMMAND_ID:
    return {
      "privateMessageViewer": request_json["user"],
      "text": 'The Avatar app replies to Google Chat messages.'
    }

Java

java/avatar-app/src/main/java/App.java
// Checks for the presence of a slash command in the message.
if (body.getAsJsonObject("message").has("slashCommand")) {
  // Executes the slash command logic based on its ID.
  // Slash command IDs are set in the Google Chat API configuration.
  JsonObject slashCommand = body.getAsJsonObject("message").getAsJsonObject("slashCommand");
  switch (slashCommand.get("commandId").getAsString()) {
    case ABOUT_COMMAND_ID:
      Message aboutMessage = new Message();
      aboutMessage.setText("The Avatar app replies to Google Chat messages.");
      aboutMessage.setPrivateMessageViewer(new User()
        .setName(body.getAsJsonObject("user").get("name").getAsString()));
      response.getWriter().write(gson.toJson(aboutMessage));
      return;
  }
}

使用在 Chat API 中設定斜線指令時指定的指令 ID 設定 ABOUT_COMMAND_ID。如要測試這段程式碼,請參閱「測試 Google Chat 應用程式的互動式功能」。