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

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

斜線指令是使用者叫用這類指令並與其互動的常見方式 Chat 應用程式。斜線指令還能幫助使用者 使用 Chat 應用程式的重要功能

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

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

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

包含私人回應的斜線指令

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

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

必要條件

Node.js

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

Apps Script

已啟用互動功能的 Google Chat 應用程式。如要建立 ，請完成快速入門導覽課程。

Python

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

Java

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

設定斜線指令

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

  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 API 的 Chat 應用程式設定。

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

  1. 在 Google Cloud 控制台中，按一下「選單」圖示 > API 與服務 > 已啟用的 API 和服務 > Google Chat API

    前往 Google Chat API 頁面

  2. 按一下「設定」。

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

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

    1. 名稱：指令的顯示名稱，以及使用者要輸入的喚出應用程式名稱。開頭必須是斜線，且只能包含文字，長度上限為 50 個字元。
    2. 說明：說明使用方法和格式的文字 非必填的旗標說明長度上限為 50 個半形字元。
    3. 指令 ID：介於 1 到 1000 的 用來辨識斜線指令的 Chat 應用程式 並傳回回應

  5. 選用：如果想讓 Chat 應用程式回覆 找出內含 dialog 的指令，然後選取 「開啟對話方塊」核取方塊。

  6. 按一下 [儲存]。

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

回應斜線指令

當使用者建立含有斜線指令的 Chat 訊息時，Chat 應用程式會收到 MESSAGE 互動事件。事件酬載包含 slashCommand 和 slashCommandMetadata 物件。這些物件含有訊息中所用指令的詳細資料 ，以便傳回適當的回應。

私人訊息： Cymbal Labs 即時通訊應用程式。這則訊息會顯示 Chat 擴充應用程式是由 Cymbal Labs 所製作，並分享連結 說明文件，以及與支援團隊聯絡的連結。
Chat 擴充應用程式會以私密方式回覆 斜線指令 /help 說明如何取得支援。

以下程式碼顯示 Chat 應用程式回覆 /about 斜線指令的範例，方法是處理 MESSAGE 互動事件，並偵測訊息是否包含相符的指令 ID。如果訊息包含指令 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:
    JsonObject aboutMessage = new JsonObject();
    aboutMessage.addProperty("text", "The Avatar app replies to Google Chat messages.");
    aboutMessage.add("privateMessageViewer", body.getAsJsonObject("user"));
      response.getWriter().write(gson.toJson(aboutMessage));
      return;
  }
}

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