以 Google Chat 应用响应斜杠命令

本页介绍了如何为 Google Chat 应用设置和响应正斜线命令。

斜杠命令是用户调用和与 Chat 应用互动的一个常用方式。斜杠命令还有助于用户发现和使用 Chat 应用的关键功能。

如需使用斜杠命令，用户只需输入一个斜杠 (/)，然后输入一个简短的文本命令（例如 /about），即可获取 Chat 应用的相关信息。用户可以在 Google Chat 中输入一个斜杠，系统随即会显示一个窗口，其中列出了 Chat 应用的可用命令：

图 1：用户在 Google Chat 中输入斜杠时显示的窗口。

如需确定是否应设置正斜线命令，以及了解如何设计用户互动，请参阅定义所有用户体验历程。

带有私密回复的斜杠命令

当用户发送包含斜杠命令的消息时，该消息只会显示给用户和 Chat 应用。如果您已将 Chat 应用配置为添加到包含多人的聊天室，则可以考虑私下回复斜杠命令，以便用户与 Chat 应用之间的互动保持私密。

例如，如需了解他们在聊天室中发现的 Chat 应用，用户可以使用 /about 或 /help 等命令。为避免通知聊天室中的其他人，Chat 应用可以私下回复，提供有关如何使用 Chat 应用及获取支持的信息。

前提条件

注意 ：本指南中的代码示例编写为以 Node.js、Python 和 Java 的 Google Cloud Functions 函数形式运行。

Node.js

一款已启用互动功能的 Google Chat 应用。如需使用 HTTP 服务创建交互式 Chat 应用，请完成此快速入门。

Apps 脚本

启用了交互功能的 Google Chat 应用。如需使用 Apps 脚本创建交互式 Chat 应用，请完成此快速入门。

Python

启用了交互功能的 Google Chat 应用。如需使用 HTTP 服务创建交互式 Chat 应用，请完成此快速入门。

Java

启用了交互功能的 Google Chat 应用。如需使用 HTTP 服务创建交互式 Chat 应用，请完成此快速入门。

设置斜杠命令

本部分介绍了如何完成以下步骤来设置正斜线命令：

1. 为您的 Slash 命令创建一个名称。
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 控制台中，依次点击“菜单”图标 > API 和服务 > 已启用的 API 和服务 > Google Chat API

   前往“Google Chat API”页面

2. 点击配置。

3. 在斜杠命令下，点击添加斜杠命令。

4. 为该命令输入名称、命令 ID 和说明：

   1. 名称：命令的显示名称，以及用户键入的内容以调用您的应用。必须以斜杠开头，只能包含文本，并且最多可以包含 50 个字符。
   2. 说明：用于说明如何使用和设置命令格式的文本。说明最多可包含 50 个字符。
   3. 命令 ID：一个介于 1 到 1000 之间的数字，Chat 应用使用该 ID 来识别斜杠命令并返回响应。

5. 可选：如果您希望 Chat 应用使用对话框响应该命令，请选中打开对话框复选框。

6. 点击保存。

现在，Chat 应用的斜杠命令已配置完毕。

响应斜杠命令

如需查看更多示例，请参阅 Google Chat 应用示例。

当用户创建包含斜杠命令的 Chat 消息时，您的 Chat 应用会收到 MESSAGE 互动事件。事件载荷包含 slashCommand 和 slashCommandMetadata 对象。这些对象包含有关消息中使用的命令的详细信息（包括命令 ID），以便您返回适当的响应。

Chat 应用会私下响应斜杠命令 /help，说明如何获取支持。

以下代码展示了一个 Chat 应用示例，该示例通过处理 MESSAGE 互动事件并检测消息是否包含匹配的命令 ID 来回复 /about 正斜线命令。如果消息包含命令 ID，Chat 应用会返回一条私信：

Node.js

node/avatar-app/index.js

在 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 res.send({
        privateMessageViewer: event.user,
        text: 'The Avatar app replies to Google Chat messages.'
      });
  }
}

Apps 脚本

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 上查看

# 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

在 GitHub 上查看

// 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 应用的交互功能。

相关主题

• 查看使用斜杠命令的 Chat 应用示例
• 发送消息
• 发送私信
• 打开 Interactive Dialog