以 Google Chat 应用响应斜杠命令

本页介绍了如何设置和响应 Google Chat 应用。

斜杠命令是用户调用 Chat 应用。斜杠命令也有助于用户发现和 使用 Chat 应用的主要功能。

若要使用斜杠命令,用户需要输入一条斜杠 (/),然后输入一个简短的文本命令, 例如 /about,用于获取有关 Chat 应用的信息。 用户只需在 Google Chat,显示了一个窗口,其中列出了 Chat 应用:

<ph type="x-smartling-placeholder">
</ph> 斜杠命令窗口
图 1:用户在 Google Chat 中输入斜杠时显示的窗口。

决定是否应该设置斜杠命令,并了解如何 设计用户互动,请参见 定义所有用户历程

包含私密响应的斜杠命令

当用户发送包含斜杠命令的邮件时,该邮件仅 对用户和 Chat 应用可见。如果 您已将 Chat 应用配置为添加到聊天室 则可以考虑响应斜杠命令 从而确保用户和 Chat 应用。

例如,若要了解某个 Chat 应用, 在聊天室中发现,用户可以使用 /about/help 等指令。 为避免通知聊天室中的其他人, Chat 应用可以私下回复以下对象 如何使用 Chat 应用并获得支持。

前提条件

Node.js

一款已启用互动功能的 Google Chat 应用。要创建 交互式 Chat 应用,请完成此快速入门

Apps 脚本

一款已启用互动功能的 Google Chat 应用。要创建 交互式聊天应用,请完成此快速入门

Python

一款已启用互动功能的 Google Chat 应用。要创建 交互式 Chat 应用,请完成此快速入门

设置斜杠命令

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

  1. 为斜杠命令创建名称
  2. 在 Google Chat API 中配置斜杠命令

为斜杠命令命名

斜杠命令的名称是用户在 Chat 消息中输入的内容 来调用 Chat 应用。简短说明 ,以进一步提示用户如何使用此命令:

<ph type="x-smartling-placeholder">
</ph> 斜杆 (/) 命令名称和说明
图 2:斜杠命令的名称和说明。

为斜杠命令选择名称和说明时,请考虑 以下建议:

  • 如需为斜杠命令命名,请执行以下操作:

    • 请使用简短、说明性并且有实际指导意义的字词或词组, 命令简单明了。例如,不要使用 /createAReminder,请使用 /remindMe
    • 如果您的命令包含多个字词,请帮助用户阅读命令 将第一个单词全部小写,然后将第一个单词的首字母大写, 其他单词的字母。例如,不要使用 /updatecontact, 请使用 /updateContact
    • 请考虑为您的命令使用唯一名称还是通用名称。如果 您的命令描述了典型的交互或功能,那么,您可以使用 用户认可和期望的常用名称,例如 /settings/feedback。否则,请尝试使用唯一的命令名称,因为如果您的 命令名称相同,用户必须 以便查找和使用你的命令
  • 如需描述您的斜杠命令,请执行以下操作:

    • 尽量提供简洁明了的说明,以便用户了解预期结果 它们会调用命令
    • 告知用户该命令是否有任何格式设置要求。 例如,如果您创建了一个需要参数的 /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 控制台中,点击“菜单” &gt; API 和服务 &gt; 已启用的 API 和服务 &gt; Google Chat API

    转到 Google Chat API 页面

  2. 点击配置

  3. 斜杠命令下,点击添加斜杠命令

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

    1. 名称:命令的显示名称以及用户输入的内容 来调用您的应用必须以斜杠开头、只能包含文字,并且不能 不能超过 50 个字符。
    2. 说明:说明如何使用和设置格式的文本 命令。说明最多可包含 50 个字符。
    3. 命令 ID:在命令 Chat 应用用于识别斜杠命令 并返回响应。
  5. 可选:如果您希望 Chat 应用回复 使用对话框执行命令,请选择 打开对话框复选框。

  6. 点击保存

现已为 Chat 应用配置斜杠命令。

响应斜杠命令

<ph type="x-smartling-placeholder">

如果用户创建包含斜杠命令的 Chat 消息, 您的 Chat 应用收到 MESSAGE 互动事件。 事件载荷包含 slashCommandslashCommandMetadata 对象的操作。这些对象包含有关邮件中所用命令的详细信息 (包括命令 ID),以便您可以返回适当的响应。

<ph type="x-smartling-placeholder">
</ph> 的私人讯息
  Cymbal Labs Chat 应用。消息显示,
  由 Cymbal Labs 打造的 Chat 应用分享了 1 个链接
  文档以及与支持团队联系的链接。
Chat 应用以私密方式响应 斜杠命令 /help,用于说明如何获取支持。

以下代码展示了 Chat 应用的示例 响应 /help 斜杠命令,方法是处理 MESSAGE 个互动事件和检测 消息是否包含匹配的命令 ID。如果邮件中包含 该命令 ID,Chat 应用就会返回一条私信 ,其中说明了如何获取帮助:

Node.js

/**
* Responds to a MESSAGE event in Google Chat.
*
* @param {!Object} req Request sent from Google Chat app
* @param {!Object} res Response to send back
*
* @return {!Object} respond to slash command
*/
exports.onMessage = function onMessage(req, res) {
  if (req.method === 'GET' || !req.body.message) {
    return res.send('Hello! This function is meant to be used in Google Chat app.');
  }

  const event = req.body;

  // Checks for the presence of event.message.slashCommand.
  // If the slash command is "/help", responds with a private text message.
  if (event.message.slashCommand) {
    switch (event.message.slashCommand.commandId) {
      case 'ID': // The ID for your slash command
        return res.json({
          privateMessageViewer: event.user, // Optional. Responds privately to the slash command.
          text: 'This Chat app was created by Cymbal Labs. To get help with this app, <https://cymbalgroup.com/docs|see our documentation> or <https://cymbalgroup.com/support|contact our support team>.'
        });
    }
  }

  // If the Chat app doesn't detect a slash command, it responds
  // with a private text message
  return res.json({
    privateMessageViewer: event.user,
    text: 'Try a slash command.'
  });
};

Apps 脚本

/**
* Responds to a MESSAGE event in Google Chat.
*
* @param {Object} event the event object from Google Chat
*/
function onMessage(event) {
  if (event.message.slashCommand) {
    switch (event.message.slashCommand.commandId) {
      case ID: // The ID for your slash command
        return {
          "privateMessageViewer": event.user, // Optional. Responds privately to the slash command.
          "text": "This Chat app was created by Cymbal Labs. To get help with this app, <https://cymbalgroup.com/docs|see our documentation> or <https://cymbalgroup.com/support|contact our support team>."
        };
    }
  }
  else {
    return { "text": "Try a slash command.", "privateMessageViewer": event.user };
  }
}

Python

from typing import Any, Mapping

import flask
import functions_framework

@functions_framework.http
def main(req: flask.Request) -> Mapping[str, Any]:
  """Responds to a MESSAGE event in Google Chat.

  Args:
      req (flask.Request): the event object from Chat API.

  Returns:
      Mapping[str, Any]: open a Dialog in response to a card's button click.
  """
  if req.method == 'GET':
    return 'Hello! This function must be called from Google Chat.'

  request = req.get_json(silent=True)

  # Checks for the presence of event.message.slashCommand.
  # If the slash command is "/help", responds with a private text message.
  if request.get('message', {}).get('slashCommand'):
    command_id = request.get('message', {}).get('slashCommand').get('commandId')
    if command_id == 'ID': # The ID for your slash command
      return {
          'privateMessageViewer': request.get('user'),
          'text': (
              'This Chat app was created by Cymbal Labs. To get help with this'
              ' app, <https://cymbalgroup.com/docs|see our documentation> or'
              ' <https://cymbalgroup.com/support|contact our support team>.'
          ),
      }

  return {
      'privateMessageViewer': request.get('user'), # Optional. Responds privately to the slash command.
      'text': 'Try a slash command.',
  }

ID 替换为您在测试过程中 在 Chat API 中配置了斜杠命令。 如需测试此代码,请参阅 测试 Google Chat 应用的互动功能