本页介绍了如何配置 Google Chat 应用以响应正斜线命令。
在 Google Chat 中，插件会作为 Google Chat 应用显示给用户。如需了解详情，请参阅扩展 Google Chat 概览。
斜杠命令是用户调用和与 Chat 应用互动的常用方式。斜杠命令还有助于用户发现和使用 Chat 应用的关键功能。如需确定是否应设置斜杠命令，以及了解如何设计用户互动，请参阅 Chat API 文档中的定义所有用户历程。
用户如何使用斜杠命令
如需使用斜杠命令，用户只需输入一个斜杠 (/)，然后输入一个简短的文本命令（例如 /about），即可获取 Chat 应用的相关信息。用户可以在 Google Chat 中输入一个斜杠，系统随即会显示一个窗口，其中列出了 Chat 应用的可用命令：
当用户发送包含斜杠命令的消息时，该消息只会显示给用户和 Chat 应用。如果您已将 Chat 应用配置为添加到多人聊天室，则可以考虑私下回复斜杠命令，以便用户与 Chat 应用之间的互动保持私密。
例如，如需了解用户在聊天室中发现的 Chat 应用，用户可以使用 /about 或 /help 等命令。为避免通知聊天室中的所有其他人，Chat 应用可以私下回复，提供有关如何使用 Chat 应用和获取支持的信息。
前提条件
Node.js
这款 Google Workspace 插件可扩展 Google Chat 的功能。如需构建一个，请完成 HTTP 快速入门。
Apps 脚本
这款 Google Workspace 插件可扩展 Google Chat 的功能。如需构建一个，请完成 Apps Script 快速入门。
设置斜杠命令
本部分介绍了如何完成以下步骤来设置正斜线命令：
为斜杠命令命名
斜杠命令的名称是用户在 Chat 消息中输入的内容，用于调用 Chat 应用。名称下方还会显示简短说明，以便进一步提示用户如何使用该命令：
为斜杠命令选择名称和说明时，请考虑以下建议：
如需为斜杠命令命名，请执行以下操作：
- 使用简短、描述性强且切实可行的字词或短语，让用户能够清晰简明地执行命令。例如，使用
/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 中配置斜杠命令，请完成以下步骤：
在 Google Cloud 控制台中，依次点击“菜单”图标 > API 和服务 > 已启用的 API 和服务 > Google Chat API
点击配置。
在高级设置下，前往触发器，然后检查 App command 字段是否包含触发器，例如 HTTP 端点或 Apps Script 函数。您必须在下一部分中使用此触发器来响应正斜线命令。
在命令下，点击添加命令。
输入命令 ID、命令类型、斜杠命令名称、名称和说明：
- 命令 ID：一个介于 1 到 1000 之间的数字，Chat 应用使用该 ID 来识别斜杠命令并返回响应。
- 命令类型：选择斜杠命令。
- 斜杠命令名称：命令的显示名称，即用户用于调用应用的输入内容。必须以斜杠开头，仅包含文本，并且最多可包含 50 个字符。
- 名称：命令的易懂名称。名称最多可包含 50 个字符，并且可以包含特殊字符。
- 使用简短、具描述性且切实可行的字词或短语，让用户清楚地了解命令。例如，对于用于修改联系人记录的命令，请使用更新联系人。
- 说明：用于说明如何使用和设置命令格式的文本。说明最多可包含 50 个字符。
可选：如果您希望 Chat 应用通过对话框响应该命令，请选中打开对话框复选框。
点击保存。
现在，Chat 应用的斜杠命令已配置完毕。
响应斜杠命令
当用户创建 Chat 消息时，您的 Chat 应用会收到包含消息相关信息的事件对象。事件对象包含一个 AppCommand 载荷，其中包含有关消息中使用的命令的详细信息（包括命令 ID），以便您返回适当的响应。
如需响应正斜线命令，您必须实现应用命令触发器，以便 Chat 应用能够处理包含应用命令元数据的任何事件对象。
/help，说明如何获取支持。以下代码展示了一个 Chat 应用示例，该应用会使用文本消息回复 /about 正斜线命令。为了响应正斜线命令，Chat 应用会处理来自应用命令触发器的事件对象。当事件对象的载荷包含正斜线命令 ID 时，Chat 应用会返回包含 createMessageAction 对象的操作 DataActions：
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 APP_COMMAND events
if (chatEvent.appCommandPayload) {
// Stores the Google Chat app command metadata as a variable.
const appCommandMetadata = chatEvent.appCommandPayload.appCommandMetadata;
if (appCommandMetadata.appCommandType === "SLASH_COMMAND") {
// 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;
if (appCommandMetadata.appCommandType == "SLASH_COMMAND") {
// 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。