本頁面由 Cloud Translation API 翻譯而成。

回覆 Google Chat 應用程式指令

本頁面說明如何以 Google Chat 應用程式的身分設定及回應指令。

指令可協助使用者探索並使用 Chat 應用程式的重點功能。只有 Chat 應用程式可以查看指令的內容。舉例來說，如果使用者傳送含有斜線指令的訊息，該訊息只會顯示給使用者和 Chat 應用程式。

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

Chat 應用程式指令的類型

您可以將 Chat 應用程式指令建構為斜線指令或快速指令。如要探索及使用各類型指令，使用者可以採取下列做法：

斜線指令：使用者輸入斜線 (/) 和預先定義的文字 (例如 /about)，即可傳送指令訊息。即時通訊應用程式也可以要求斜線指令的引數文字。舉例來說，斜線指令 /search 可能會要求用於搜尋查詢的引數文字。
快速指令：使用者只要在 Chat 訊息的回覆區域開啟選單，即可使用指令。如要使用指令，他們只要按一下「新增」圖示，然後從選單中選取指令即可。

下列圖片顯示使用者如何找到斜線指令和快速指令選單：

圖 1. 使用者只要在回覆區域中輸入斜線 / 後接指令名稱，即可探索及使用斜線指令。
圖 2. 使用者可在 Chat 訊息的回覆區域中，透過選單探索及使用快速指令。

必要條件

Node.jsApps ScriptPythonJava

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

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

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

設定指令

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

為指令建立名稱和說明。
在 Google Cloud 控制台中設定指令。

為指令命名並提供說明

指令名稱是使用者輸入或選取用來叫用 Chat 應用程式的名稱。名稱下方也會顯示簡短說明，進一步提示使用者如何使用指令：

為指令選擇名稱和說明時，請考慮下列建議：

如何為指令命名：

使用簡短、具描述性且可採取行動的字詞或詞組，讓使用者清楚瞭解指令。例如，使用 Remind me，而不使用 Create a reminder。
建議使用不重複或常見的名稱做為指令名稱。如果指令描述的是一般互動或功能，您可以使用使用者熟悉且預期的常用名稱，例如 Settings 或 Feedback。否則，請盡量使用獨特的指令名稱，因為如果您的指令名稱與其他 Chat 應用程式相同，使用者就必須篩選類似的指令，才能找到並使用您的指令。

如要說明指令，請按照下列步驟操作：

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

在 Google Cloud 控制台中設定指令

如要建立斜線或快速指令，請在 Chat 應用程式的 Google Chat API 設定中指定指令相關資訊。

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

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

前往 Google Chat API 頁面
按一下「設定」。
在「指令」下方，按一下「新增指令」。
輸入指令的 ID、名稱、說明和指令類型：
- 指令 ID：Chat 應用程式用來辨識指令並傳回回應的 1 到 1000 之間的數字。
- 名稱：指令的顯示名稱。名稱長度上限為 50 個半形字元，且可包含特殊字元。
- 說明：說明指令用途的文字。說明的長度上限為 50 個半形字元，且可以包含特殊字元。
- 指令類型：選取「快速指令」或「斜線指令」。
- 如果要設定斜線指令，請在「斜線指令名稱」欄位中輸入值，指定使用者要輸入哪些內容才能叫用指令。開頭須為斜線，且只能包含文字，長度上限為 50 個半形字元。例如 /remindMe。
選用：如要讓 Chat 應用程式以對話方塊回應指令，請選取「Open a dialog」核取方塊。
按一下 [儲存]。

指令現在已為 Chat 應用程式設定。

回應指令

使用者使用指令時，Chat 應用程式會收到互動事件。事件酬載包含中繼資料，其中包含已叫用的指令詳細資料 (包括指令 ID 和指令類型)，以便您傳回適當的回應。

Cymbal Labs Chat 應用程式的私人訊息。訊息指出 Chat 應用程式是由 Cymbal Labs 建立，並分享說明文件連結和支援團隊聯絡連結。 — Chat 應用程式會私下回應斜線指令 `/help`，說明如何取得支援。

如要回應每種指令類型，您必須在事件酬載中處理不同的事件類型和中繼資料物件：

指令類型	事件類型	指令中繼資料
斜線指令	`MESSAGE`	`message.slashCommand` 或 `message.annotation.slashCommand`
快速指令	`APP_COMMAND`	`appCommandMetadata`

如要瞭解如何回覆指令訊息，請參閱以下各節。

回應斜線指令

以下程式碼為回覆斜線指令 /about 的 Chat 應用程式範例。Chat 應用程式會處理 MESSAGE 互動事件、偵測互動事件是否包含相符的指令 ID，並傳回私人訊息：

Node.js Apps Script Python Java

node/avatar-app/index.js

前往 GitHub 查看

/**
 * Handles slash and quick commands.
 *
 * @param {Object} event - The Google Chat event.
 * @param {Object} res - The HTTP response object.
 */
function handleAppCommands(event, res) {
  const {appCommandId, appCommandType} = event.appCommandMetadata;

  switch (appCommandId) {
    case ABOUT_COMMAND_ID:
      return res.send({
        privateMessageViewer: event.user,
        text: 'The Avatar app replies to Google Chat messages.'
      });
    case HELP_COMMAND_ID:
      return res.send({
        privateMessageViewer: event.user,
        text: 'The Avatar app replies to Google Chat messages.'
      });
  }
}

apps-script/avatar-app/avatar-app.gs

前往 GitHub 查看

// 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/avatar-app/main.py

前往 GitHub 查看

def handle_app_commands(event: Mapping[str, Any]) -> Mapping[str, Any]:
    """Handles slash and quick commands.

    Args:
        Mapping[str, Any] event: The Google Chat event.

    Returns:
        Mapping[str, Any]: the response
    """
    app_command_id = event["appCommandMetadata"]["appCommandId"]

    if app_command_id == ABOUT_COMMAND_ID:
        return {
            "privateMessageViewer": event["user"],
            "text": "The Avatar app replies to Google Chat messages.",
        }
    elif app_command_id == HELP_COMMAND_ID:
        return {
            "privateMessageViewer": event["user"],
            "text": "The Avatar app replies to Google Chat messages.",
        }
    return {}

java/avatar-app/src/main/java/AvatarApp.java

前往 GitHub 查看

/**
 * Handles slash and quick commands.
 *
 * @param event    The Google Chat event.
 * @param response The HTTP response object.
 */
private void handleAppCommands(JsonObject event, HttpResponse response) throws Exception {
  int appCommandId = event.getAsJsonObject("appCommandMetadata").get("appCommandId").getAsInt();

  switch (appCommandId) {
    case ABOUT_COMMAND_ID:
      Message aboutMessage = new Message();
      aboutMessage.setText("The Avatar app replies to Google Chat messages.");
      aboutMessage.setPrivateMessageViewer(new User()
          .setName(event.getAsJsonObject("user").get("name").getAsString()));
      response.getWriter().write(gson.toJson(aboutMessage));
      return;
    case HELP_COMMAND_ID:
      Message helpMessage = new Message();
      helpMessage.setText("The Avatar app replies to Google Chat messages.");
      helpMessage.setPrivateMessageViewer(new User()
          .setName(event.getAsJsonObject("user").get("name").getAsString()));
      response.getWriter().write(gson.toJson(helpMessage));
      return;
  }
}

將 ABOUT_COMMAND_ID 替換為您在 Google Cloud 控制台中設定指令時指定的指令 ID。

回覆快速指令

以下程式碼為 Chat 應用程式回覆快速指令「Help」的範例。Chat 應用程式會處理 APP_COMMAND 互動事件、偵測互動事件是否包含相符的指令 ID，並傳回私人訊息：

Node.js Apps Script Python Java

node/avatar-app/index.js

前往 GitHub 查看

/**
 * Handles slash and quick commands.
 *
 * @param {Object} event - The Google Chat event.
 * @param {Object} res - The HTTP response object.
 */
function handleAppCommands(event, res) {
  const {appCommandId, appCommandType} = event.appCommandMetadata;

  switch (appCommandId) {
    case ABOUT_COMMAND_ID:
      return res.send({
        privateMessageViewer: event.user,
        text: 'The Avatar app replies to Google Chat messages.'
      });
    case HELP_COMMAND_ID:
      return res.send({
        privateMessageViewer: event.user,
        text: 'The Avatar app replies to Google Chat messages.'
      });
  }
}

apps-script/avatar-app/avatar-app.gs

前往 GitHub 查看

// 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/avatar-app/main.py

前往 GitHub 查看

def handle_app_commands(event: Mapping[str, Any]) -> Mapping[str, Any]:
    """Handles slash and quick commands.

    Args:
        Mapping[str, Any] event: The Google Chat event.

    Returns:
        Mapping[str, Any]: the response
    """
    app_command_id = event["appCommandMetadata"]["appCommandId"]

    if app_command_id == ABOUT_COMMAND_ID:
        return {
            "privateMessageViewer": event["user"],
            "text": "The Avatar app replies to Google Chat messages.",
        }
    elif app_command_id == HELP_COMMAND_ID:
        return {
            "privateMessageViewer": event["user"],
            "text": "The Avatar app replies to Google Chat messages.",
        }
    return {}

java/avatar-app/src/main/java/AvatarApp.java

前往 GitHub 查看

/**
 * Handles slash and quick commands.
 *
 * @param event    The Google Chat event.
 * @param response The HTTP response object.
 */
private void handleAppCommands(JsonObject event, HttpResponse response) throws Exception {
  int appCommandId = event.getAsJsonObject("appCommandMetadata").get("appCommandId").getAsInt();

  switch (appCommandId) {
    case ABOUT_COMMAND_ID:
      Message aboutMessage = new Message();
      aboutMessage.setText("The Avatar app replies to Google Chat messages.");
      aboutMessage.setPrivateMessageViewer(new User()
          .setName(event.getAsJsonObject("user").get("name").getAsString()));
      response.getWriter().write(gson.toJson(aboutMessage));
      return;
    case HELP_COMMAND_ID:
      Message helpMessage = new Message();
      helpMessage.setText("The Avatar app replies to Google Chat messages.");
      helpMessage.setPrivateMessageViewer(new User()
          .setName(event.getAsJsonObject("user").get("name").getAsString()));
      response.getWriter().write(gson.toJson(helpMessage));
      return;
  }
}

將 HELP_COMMAND_ID 替換為您在 Google Cloud 主控台中設定指令時指定的指令 ID。

測試指令

如要測試指令和程式碼，請參閱「測試 Google Chat 應用程式的互動功能」。

如要瞭解如何在 Chat UI 中測試及使用指令，請參閱 Google Chat 說明文件中的「在 Google Chat 中使用應用程式」。

回覆 Google Chat 應用程式指令

Chat 應用程式指令的類型

必要條件

設定指令

為指令命名並提供說明

如何為指令命名：

如要說明指令，請按照下列步驟操作：

在 Google Cloud 控制台中設定指令

回應指令

回應斜線指令

回覆快速指令

測試指令

相關主題