本页介绍如何以 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。
设置命令
本部分介绍如何完成以下步骤,以设置命令:
为命令命名并添加说明
命令的名称是用户输入或选择的内容,用于调用 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
点击配置。
在连接设置下,前往触发器并指定端点详细信息。在下一部分中,您必须使用此触发器来响应命令。
- HTTP 端点网址:您可以在此处指定一个常用的 HTTP 端点网址。或者,如需为不同的触发器使用不同的 HTTP 端点,请直接在应用命令字段中指定端点。
- Apps 脚本:输入 Apps 脚本部署 ID。默认情况下,系统将调用
onAppCommand
函数。要使用其他 Apps 脚本函数,请在应用命令字段中指定自定义函数名称。
在命令下,点击添加命令。
输入有关该命令的以下信息:
- Command ID(命令 ID):一个 1 到 1000 之间的数字,Chat 应用使用该 ID 来识别命令并返回响应。
- 说明:说明如何使用该命令以及设置其格式的文本。说明最多可包含 50 个字符。
- 命令类型:选择快速命令或斜杠命令。
- 为快捷命令或斜杠命令指定名称:
- 快速命令名称:用户从菜单中选择以调用命令的显示名称。最多可以包含 50 个字符,并且包含特殊字符。例如
Remind me
。 - 斜杠命令名称:用户为调用消息中的命令而输入的文本。必须以斜杠开头,只能包含文本,并且最多可以包含 50 个字符。例如
/remindMe
。
- 快速命令名称:用户从菜单中选择以调用命令的显示名称。最多可以包含 50 个字符,并且包含特殊字符。例如
可选:如果您希望 Chat 应用通过对话框响应命令,请选中打开对话框复选框。
点击保存。
系统现已为 Chat 应用配置该命令。
响应命令
当用户使用命令时,您的 Chat 应用会收到一个事件对象。事件载荷包含一个 appCommandPayload
对象,该对象包含所调用命令的详细信息(包括命令 ID 和命令类型),以便您可以返回适当的响应。该事件对象会发送到您在配置 App Command 触发器时指定的 HTTP 端点或 Apps 脚本函数。

/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 中使用应用。