此页面由 Cloud Translation API 翻译。

响应 Google Chat 应用命令

本页介绍如何以 Google Chat 应用的形式设置和响应命令。

命令有助于用户发现和使用 Chat 应用的主要功能。只有 Chat 应用可以看到命令的内容。例如，如果用户发送包含斜杠命令的消息，则该消息仅对用户和 Chat 应用可见。

如需决定是否应构建命令并了解如何设计用户互动，请参阅定义所有用户历程。

Chat 应用命令类型

您可以将 Chat 应用命令构建为斜杠命令或快速命令。如需发现和使用每种类型的命令，用户需要执行以下操作：

斜杠命令：用户通过依次输入斜杠 (/) 和预定义文本（如 /about）将命令作为消息发送。 Chat 应用可能还要求使用斜杠命令的参数文本。例如，斜杠命令 /search 可以要求用于搜索查询的参数文本。
快速命令：用户可通过在 Chat 消息的回复区域打开菜单来使用命令。如需使用命令，请点击 Add 图标，然后从菜单中选择一个命令。

下图显示了用户如何发现包含斜杠命令和快捷命令的菜单：

图 1. 用户可以通过在回复区域输入斜杠 / 后跟命令名称来发现和使用斜杠命令。
图 2.用户可以在 Chat 消息回复区域的菜单中发现和使用快捷命令。

前提条件

HTTP

拥有对 Google Chat 访问权限的商务版或企业版 Google Workspace 账号。
创建 Google Cloud 项目。
配置 OAuth 同意屏幕。
启用 Google Chat API。
托管 Chat 应用的服务架构的 HTTP 端点。

Apps 脚本

拥有对 Google Chat 访问权限的商务版或企业版 Google Workspace 账号。
创建 Google Cloud 项目。
配置 OAuth 同意屏幕。
启用 Google Chat API。
创建独立的 Apps 脚本项目，然后启用高级聊天服务。
通过添加 addons.chat 对象和任何必需的范围 (oauthScopes) 或 HTTPS 网址前缀 (urlFetchWhitelist)，在清单中配置 Chat。

设置命令

本部分介绍如何完成以下步骤，以设置命令：

为命令创建名称和说明。
在 Google Cloud 控制台中配置该命令。

为命令命名并添加说明

命令的名称是用户输入或选择的内容，用于调用 Chat 应用。名称下方还会显示简短的说明，以进一步提示用户使用该命令：

为命令选择名称和说明时，请考虑以下建议：

如需命名命令，请执行以下操作：

使用简短、说明性并且可操作的字词或短语，让用户清楚知道命令。例如，不要使用 Create a reminder，而要使用 Remind me。
请考虑为您的命令使用唯一或通用名称。如果您的命令描述了典型的互动或功能，您可以使用用户认识和预期的常用名称，例如 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 Chat API 中配置斜杠命令，请完成以下步骤：

在 Google Cloud 控制台中，点击“菜单”图标 > API 和服务 > 已启用的 API 和服务 > Google Chat API

转到 Google Chat API 页面
点击配置。
在连接设置下，前往触发器并指定端点详细信息。在下一部分中，您必须使用此触发器来响应命令。
1. HTTP 端点网址：您可以在此处指定一个常用的 HTTP 端点网址。或者，如需为不同的触发器使用不同的 HTTP 端点，请直接在应用命令字段中指定端点。
2. Apps 脚本：输入 Apps 脚本部署 ID。默认情况下，系统将调用 onAppCommand 函数。要使用其他 Apps 脚本函数，请在应用命令字段中指定自定义函数名称。
在命令下，点击添加命令。
输入有关该命令的以下信息：
1. Command ID（命令 ID）：一个 1 到 1000 之间的数字，Chat 应用使用该 ID 来识别命令并返回响应。
2. 说明：说明如何使用该命令以及设置其格式的文本。说明最多可包含 50 个字符。
3. 命令类型：选择快速命令或斜杠命令。
4. 为快捷命令或斜杠命令指定名称：
  - 快速命令名称：用户从菜单中选择以调用命令的显示名称。最多可以包含 50 个字符，并且包含特殊字符。例如 Remind me。
  - 斜杠命令名称：用户为调用消息中的命令而输入的文本。必须以斜杠开头，只能包含文本，并且最多可以包含 50 个字符。例如 /remindMe。
可选：如果您希望 Chat 应用通过对话框响应命令，请选中打开对话框复选框。
点击保存。

系统现已为 Chat 应用配置该命令。

响应命令

当用户使用命令时，您的 Chat 应用会收到一个事件对象。事件载荷包含一个 appCommandPayload 对象，该对象包含所调用命令的详细信息（包括命令 ID 和命令类型），以便您可以返回适当的响应。该事件对象会发送到您在配置 App Command 触发器时指定的 HTTP 端点或 Apps 脚本函数。

用于发送 Cymbal Labs Chat 应用的私信。该消息指出 Chat 应用是由 Cymbal Labs 创建的，并分享了文档链接和支持团队的联系链接。 — Chat 应用以私密方式响应斜杠命令 `/help`，以说明如何获取支持。

以下代码展示了一个使用文本消息回复斜杠命令 /about 的 Chat 应用示例。为了响应斜杠命令，Chat 应用会处理来自应用命令触发器的事件对象。当事件对象的载荷包含斜杠命令 ID 时，Chat 应用会返回 DataActions 操作以及 createMessageAction 对象：

Node.js

// The ID of the slash command "/about".
// It's not enabled by default, set to the actual ID to enable it. You must
// use the same ID as set in the Google Chat API configuration.
const ABOUT_COMMAND_ID = 0;

/**
 * Google Cloud Function that responds to events sent from a
 * Google Chat space.
 *
 * @param {Object} req Request sent from Google Chat space
 * @param {Object} res Response to send back
 */
exports.avatarApp = function avatarApp(req, res) {
    if (req.method === 'GET' || !req.body.chat) {
        return res.send('Hello! This function is meant to be used ' +
            'in a Google Chat Space.');
    }
    // Stores the Google Chat event as a variable.
    const chatEvent = req.body.chat;

    // Handles events that contain payloads about commands
    if (chatEvent.appCommandPayload) {

      // Stores the Google Chat app command metadata as a variable.
      const appCommandMetadata = chatEvent.appCommandPayload.appCommandMetadata;

      // Executes the slash command logic based on its ID.
      // Slash command IDs are set in the Google Chat API configuration.
      switch (appCommandMetadata.appCommandId) {
          case ABOUT_COMMAND_ID:
              return res.send({ hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
                  text: 'The Avatar app replies to Google Chat messages.'
              }}}}});
      }
    // Handles MESSAGE events
    } else if (chatEvent.messagePayload) {

        // Stores the Google Chat event as a variable.
        const chatMessage = chatEvent.messagePayload.message;

        // Replies with the sender's avatar in a card otherwise.
        const displayName = chatMessage.sender.displayName;
        const avatarUrl = chatMessage.sender.avatarUrl;
        res.send({ hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
            text: 'Here\'s your avatar',
            cardsV2: [{
                cardId: 'avatarCard',
                card: {
                    name: 'Avatar Card',
                    header: {
                        title: `Hello ${displayName}!`,
                    },
                    sections: [{
                        widgets: [{
                            textParagraph: { text: 'Your avatar picture: ' }
                        }, {
                            image: { imageUrl: avatarUrl }
                        }]
                    }]
                }
            }]
        }}}}});
    }
};

Apps 脚本

// The ID of the slash command "/about".
// It's not enabled by default, set to the actual ID to enable it. You must
// use the same ID as set in the Google Chat API configuration.
const ABOUT_COMMAND_ID = 0;

/**
 * Responds to a MESSAGE event in Google Chat.
 *
 * @param {Object} event the event object from Google Chat
 */
function onMessage(event) {

    // Stores the Google Chat event as a variable.
    const chatMessage = event.chat.messagePayload.message;

    // Replies with the sender's avatar in a card otherwise.
    const displayName = chatMessage.sender.displayName;
    const avatarUrl = chatMessage.sender.avatarUrl;
    return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
        text: 'Here\'s your avatar',
        cardsV2: [{
            cardId: 'avatarCard',
            card: {
                name: 'Avatar Card',
                header: {
                    title: `Hello ${displayName}!`,
                },
                sections: [{
                    widgets: [{
                        textParagraph: { text: 'Your avatar picture: ' }
                    }, {
                        image: { imageUrl: avatarUrl }
                    }]
                }]
            }
        }]
    }}}}};
}

/**
 * Responds to an APP_COMMAND event in Google Chat.
 *
 * @param {Object} event the event object from Google Chat
 */
function onAppCommand(event) {

  // Stores the Google Chat app command metadata as a variable.
  const appCommandMetadata = event.chat.appCommandPayload.appCommandMetadata;

  // Executes the slash command logic based on its ID.
  // Slash command IDs are set in the Google Chat API configuration.
  switch (appCommandMetadata.appCommandId) {
      case ABOUT_COMMAND_ID:
          return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
              text: 'The Avatar app replies to Google Chat messages.'
          }}}}};
  }
}

如需使用此代码示例，请将 ABOUT_COMMAND_ID 替换为您在在 Chat API 中配置命令时指定的命令 ID。

测试命令

如需测试命令和代码，请参阅测试 Google Chat 应用的互动功能。

如需了解如何在 Chat 界面中测试和使用该命令，请参阅 Google Chat 帮助文档中的在 Google Chat 中使用应用。

响应 Google Chat 应用命令

Chat 应用命令类型

前提条件

HTTP

Apps 脚本

设置命令

为命令命名并添加说明

如需命名命令，请执行以下操作：

描述命令的方法如下：

在 Google Cloud 控制台中配置命令

响应命令

Node.js

Apps 脚本

测试命令

相关主题