本页介绍了如何作为 Google Chat 应用设置和响应命令。
命令可帮助用户发现和使用 Chat 应用的关键功能。只有 Chat 应用可以看到命令的内容。例如，如果用户使用正斜线命令发送消息，则只有该用户和 Chat 应用可以看到该消息。
如需确定是否应构建命令，以及了解如何设计用户互动，请参阅定义所有用户历程。
Chat 应用命令的类型
您可以将 Chat 应用命令构建为斜杠命令或快捷命令。如需发现和使用每种类型的命令，用户可以执行以下操作：-
正斜线命令：用户可以通过输入正斜线 (
/) 和预定义文本（例如/about）来以消息的形式发送命令。 聊天应用还可以要求斜杠命令提供参数文本。例如，正斜线命令/search可能需要用于搜索查询的参数文本。 -
快捷命令：用户通过在 Chat 消息的回复区域中打开菜单来使用命令。如需使用某个命令，用户只需点击添加图标
，然后从菜单中选择相应命令即可。
-
图 1. 用户可以在回复区域中输入斜杠 /后跟命令名称，以发现和使用 Slash 命令。 -
图 2. 用户可在 Chat 消息的回复区域内通过菜单发现和使用快捷命令。
前提条件
- 拥有对 Google Chat 访问权限的商务版或企业版 Google Workspace 账号。
- 创建 Google Cloud 项目。
- 配置 OAuth 同意屏幕。
- 启用以下 Google Workspace API：
- Google Chat API
- Google Workspace Add-ons API
- 托管 Chat 应用服务架构的 HTTP 端点。
- 拥有对 Google Chat 访问权限的商务版或企业版 Google Workspace 账号。
- 创建 Google Cloud 项目。
- 配置 OAuth 同意屏幕。
- 启用 Google Chat API。
- 创建一个独立的 Apps 脚本项目，然后开启高级聊天服务。
- 在清单中配置 Chat，方法是添加
addons.chat对象以及任何必需的镜重范围 (oauthScopes) 或 HTTPS 网址前缀 (urlFetchWhitelist)。
设置命令
本部分介绍了如何完成以下步骤来设置命令：
为命令命名并添加说明
用户输入或选择的用于调用 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 中配置命令，请完成以下步骤： o 如需在 Google Chat API 中配置正斜线命令，请完成以下步骤：
在 Google Cloud 控制台中，依次点击“菜单”图标 > API 和服务 > 已启用的 API 和服务 > Google Chat API
点击配置。
在高级设置下，前往触发器，然后检查 App command 字段是否包含触发器，例如 HTTP 端点或 Apps Script 函数。您必须在下一部分中使用此触发器来响应该命令。
在命令下，点击添加命令。
输入以下有关该命令的信息：
- 命令 ID：一个介于 1 到 1000 之间的数字，Chat 应用使用该数字来识别命令并返回响应。
- 命令类型：选择快捷命令或 Slash 命令。
- 如果您要配置正斜线命令，请为 Slash command name（正斜线命令名称）字段输入一个值，以指定用户要输入什么内容才能调用该命令。必须以斜线开头，只能包含文本，且长度不得超过 50 个字符。例如
/remindMe。 - 名称：命令的易懂名称。名称最多可包含 50 个字符，并且可以包含特殊字符。
- 说明：用于说明如何使用和设置命令格式的文本。说明最多可包含 50 个字符。
可选：如果您希望 Chat 应用通过对话框响应该命令，请选中打开对话框复选框。
点击保存。
该命令现已针对 Chat 应用配置完毕。
响应命令
当用户使用某个命令时，您的 Chat 应用会收到一个事件对象。事件载荷包含一个 appCommandPayload 对象，其中包含有关所调用命令的详细信息（包括命令 ID 和命令类型），以便您返回适当的响应。事件对象会发送到您在配置应用命令触发器时指定的 HTTP 端点或 Apps 脚本函数。
/help，说明如何获取支持。以下代码展示了一个 Chat 应用示例，该示例会使用文本消息回复正斜线命令 /about。为了响应正斜线命令，Chat 应用会处理来自应用命令触发器的事件对象。当事件对象的载荷包含正斜线命令 ID 时，Chat 应用会返回包含 createMessageAction 对象的操作 DataActions：
// 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 }
}]
}]
}
}]
}}}}});
}
};
// 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 中使用应用。