回覆 Google Chat 應用程式指令

本頁說明如何設定及回應指令，以 Google Chat 應用程式的身分執行操作。

指令可協助使用者探索及使用 Chat 擴充應用程式的主要功能。只有 Chat 擴充應用程式可以查看指令內容。舉例來說，如果使用者傳送含有斜線指令的訊息，只有使用者和 Chat 應用程式會看到該訊息。

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

Chat 應用程式指令類型

您可以將 Chat 應用程式指令建構為斜線指令、快速指令或訊息動作。如要使用各類指令，使用者可以採取下列做法：

斜線指令：使用者可以從選單中選取斜線指令，或輸入斜線 (/) 和預先定義的文字，例如 /about。通常，Chat 應用程式需要斜線指令的引數文字。

如果 Chat 應用程式需要使用者提供額外輸入內容，請建立斜線指令。舉例來說，您可以建立名為 /search 的斜線指令，在使用者輸入要搜尋的詞組 (例如 /search receipts) 後執行。
快速指令：使用者可以開啟 Chat 訊息回覆區的選單，然後使用指令。如要使用指令，請按一下「新增」，然後從選單中選取指令。

如果 Chat 應用程式可以立即回覆使用者，不必等待其他輸入內容，請建立快速指令。舉例來說，你可以建立名為「隨機圖片」的快速指令，立即回應圖片。
訊息動作： ( 開發人員預覽版) 使用者只要將游標懸停在訊息上，然後點選三點選單，即可使用訊息動作。如要使用指令，請開啟三點選單，然後從選單中選取指令。

如果 Chat 應用程式可以根據訊息內容執行動作，請建立訊息動作。

下圖顯示使用者如何找到斜線和快速指令，以及訊息動作的選單：

使用者發現含有訊息動作的訊息內容選單。 — 使用者會看到訊息內容選單，其中包含「提醒我」訊息動作。

必要條件

Node.js

接收並回應互動事件的 Google Chat 應用程式。如要使用 HTTP 服務建立互動式即時通訊應用程式，請完成這項快速入門導覽課程。

Apps Script

接收並回應互動事件的 Google Chat 應用程式。如要在 Apps Script 中建立互動式 Chat 應用程式，請完成這項快速入門導覽課程。

Python

接收並回應互動事件的 Google Chat 應用程式。如要使用 HTTP 服務建立互動式即時通訊應用程式，請完成這項快速入門導覽課程。

Java

接收並回應互動事件的 Google Chat 應用程式。如要使用 HTTP 服務建立互動式即時通訊應用程式，請完成這項快速入門導覽課程。

設定指令

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

建立指令名稱和說明。
在 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 控制台中設定指令

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

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

前往 Google Cloud 控制台，依序點選「選單」 >「API 和服務」>「已啟用的 API 和服務」>「Google Chat API」

前往 Google Chat API 頁面
按一下「設定」。
在「指令」下方，按一下「新增指令」。
輸入指令的指令 ID、說明、指令類型和名稱：
- 指令 ID：介於 1 到 1000 的數字，Chat 應用程式會使用這個 ID 辨識指令並傳回回應。
- 說明：說明指令用途的文字。說明最多可輸入 50 個半形字元，且可包含特殊字元。
- 指令類型：選取「快速指令」、「斜線指令」或「訊息動作」。
- 指定指令名稱：
  - 快速指令名稱：使用者從選單中選取並叫用指令時，顯示的名稱。最多 50 個半形字元，可包含特殊字元。例如：Remind me。
  - 斜線指令名稱：使用者在訊息中輸入的文字，可叫用指令。開頭須為正斜線，只能包含文字，且最多 50 個半形字元。例如：/remindMe。
  - 訊息動作名稱： ( 開發人員預覽版) 使用者從選單選取的顯示名稱，用於叫用訊息動作。最多可輸入 50 個半形字元，且可包含特殊字元。例如：Remind me。
選用：載入通知訊息： ( 開發人員預覽版) 在執行訊息動作時，向使用者顯示的浮動式通知訊息。僅適用於不會開啟對話方塊的訊息動作。
選用：如要讓 Chat 應用程式以對話方塊回覆指令，請選取「開啟對話方塊」核取方塊。
按一下 [儲存]。

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

回應指令

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

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

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

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

如要瞭解如何透過訊息回覆指令，請參閱下列章節。

回覆斜線指令

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

Node.js

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

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

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

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。

回應快速指令

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

Node.js

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

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

前往 GitHub 查看

/**
 * Handles the APP_COMMAND event type. This function is triggered when a user
 * interacts with a quick command within the Google Chat app.  It responds
 * based on the command ID.
 *
 * @param {Object} event The event object from Google Chat, containing details
 *     about the app command interaction.  It includes information like the
 *     command ID and the user who triggered it.
 */
function onAppCommand(event) {
  // Executes the quick command logic based on its ID.
  // Command IDs are set in the Google Chat API configuration.
  switch (event.appCommandMetadata.appCommandId) {
    case HELP_COMMAND_ID:
      return {
        privateMessageViewer: event.user,
        text: 'The Avatar app replies to Google Chat messages.'
      };
  }
}

Python

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

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。

回應訊息動作

以下程式碼範例顯示回覆「提醒我」訊息動作的即時通訊應用程式。Chat 應用程式會處理 APP_COMMAND 互動事件、偵測互動事件是否包含相符的指令 ID，並傳回私人訊息：

Node.js

/**
 * Responds to an APP_COMMAND interaction event from Google Chat.
 *
 * @param {Object} event The interaction event from Google Chat.
 * @param {Object} res The HTTP response object.
 * @return {Object} The JSON response message with a confirmation.
 */
function handleAppCommand(event, res) {
  // Collect the command ID and type from the event metadata.
  const {appCommandId, appCommandType} = event.appCommandMetadata;

  // Use appCommandType to detect message actions.
  if (appCommandType === 'MESSAGE_ACTION' &&
      appCommandId === REMIND_ME_COMMAND_ID) {

    // Message actions can access the context of the message they were
    // invoked on, such as the text or sender of that message.
    const messageText = event.message.text;

    // Return a response that includes details from the original message.
    return res.send({
      text: `Setting a reminder for this message: "${messageText}"`
    });
  }
}

Apps Script

/**
 * Responds to an APP_COMMAND interaction event in Google Chat.
 *
 * @param {Object} event The interaction event from Google Chat.
 * @return {Object} The JSON response message with a confirmation.
 */
function onAppCommand(event) {
  // Collect the command ID and type from the event metadata.
  const {appCommandId, appCommandType} = event.appCommandMetadata;

  if (appCommandType === 'MESSAGE_ACTION' &&
      appCommandId === REMIND_ME_COMMAND_ID) {

    // Message actions can access the context of the message they were
    // invoked on, such as the text or sender of that message.
    const messageText = event.message.text;

    // Return a response that includes details from the original message.
    return { "text": "Setting a reminder for message: " + messageText };
  }
}

Python

def handle_app_command(event):
    """Responds to an APP_COMMAND interaction event from Google Chat.

    Args:
        event (dict): The interaction event from Google Chat.

    Returns:
        dict: The JSON response message with a confirmation.
    """
    # Collect the command ID and type from the event metadata.
    metadata = event.get('appCommandMetadata', {})
    if metadata.get('appCommandType') == 'MESSAGE_ACTION' and \
       metadata.get('appCommandId') == REMIND_ME_COMMAND_ID:

        # Message actions can access the context of the message they were
        # invoked on, such as the text or sender of that message.
        message_text = event.get('message', {}).get('text')

        # Return a response that includes details from the original message.
        return {
            "text": f'Setting a reminder for message: "{message_text}"'
        }

Java

/**
 * Responds to an APP_COMMAND interaction event from Google Chat.
 *
 * @param event The interaction event from Google Chat.
 * @param response The HTTP response object.
 */
void handleAppCommand(JsonObject event, HttpResponse response) throws Exception {
  // Collect the command ID and type from the event metadata.
  JsonObject metadata = event.getAsJsonObject("appCommandMetadata");
  String appCommandType = metadata.get("appCommandType").getAsString();

  if (appCommandType.equals("MESSAGE_ACTION")) {
    int commandId = metadata.get("appCommandId").getAsInt();
    if (commandId == REMIND_ME_COMMAND_ID) {
      // Message actions can access the context of the message they were
      // invoked on, such as the text or sender of that message.
      String messageText = event.getAsJsonObject("message").get("text").getAsString();

      // Return a response that includes details from the original message.
      JsonObject responseMessage = new JsonObject();
      responseMessage.addProperty("text", "Setting a reminder for message: " + messageText);
      response.getWriter().write(responseMessage.toString());
    }
  }
}

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

測試指令

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

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

回覆 Google Chat 應用程式指令 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

Chat 應用程式指令類型

必要條件

Node.js

Apps Script

Python

Java

設定指令

為指令命名並輸入說明

如何命名指令：

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

在 Google Cloud 控制台中設定指令

回應指令

回覆斜線指令

Node.js

Apps Script

Python

Java

回應快速指令

Node.js

Apps Script

Python

Java

回應訊息動作

Node.js

Apps Script

Python

Java

測試指令

相關主題

回覆 Google Chat 應用程式指令