本页面介绍了 Google Chat 应用如何在 Google Chat 中接收和响应用户互动。
如需为 Chat 应用构建交互式界面,您可以使用以下组件:
- 触发器:Google Chat 用户调用 Chat 应用的方式,例如将其添加到聊天室或向其发送消息。
- 事件对象:Chat 应用从触发器或界面互动接收的数据。
- 操作:Chat 应用可以响应互动的方式,例如发送消息或返回基于卡片的用户界面。
Chat 应用可以通过以下方式构建和显示界面:
- 消息,可以包含文本、静态或互动卡片以及辅助按钮。
- 首页(应用首页):显示在与 Chat 应用的 1 对 1 私信的首页标签页中。
- 对话框:在新窗口中打开的卡片,通常会提示用户提交信息。
- 链接预览,即预览外部服务相关信息的卡片。
前提条件
- 可访问 Google Chat 的 Google Workspace 商务版或企业版账号。
- 创建 Google Cloud 项目。
- 配置 OAuth 权限请求页面。
- 启用并配置 Google Chat API。
用户互动的工作原理
当用户与 Chat 应用互动时,Google Chat 会调用配置的触发器,并将事件对象发送到 Chat 应用的端点或函数。Chat 应用会处理事件对象,并可在 30 秒内同步返回操作,或使用 Chat API 异步响应。
下图展示了 Google Chat 应用如何处理和响应用户互动:
触发器
触发器是用户通过 Chat 界面调用 Chat 应用的具体方式,例如使用 @提及或应用命令。
下表显示了 Chat 触发器、说明以及 Chat 应用通常如何响应:
| 触发器 | 说明 | 典型回答 |
|---|---|---|
| 已添加到聊天室 |
用户将 Chat 应用添加到聊天室,或者 Google Workspace 管理员为组织中的用户在私信聊天室中安装 Chat 应用。如需了解由管理员安装的 Chat 应用,请参阅 Google Workspace 管理员帮助文档中的在您的网域中安装 Marketplace 中的应用。 |
Chat 应用会发送一条新手入门消息,说明其功能以及聊天室中的用户如何与其互动。 |
| 短信 |
用户通过以下任一方式在消息中与 Chat 应用互动:
|
Chat 应用会根据消息内容进行回复。例如,Chat 应用会回复消息、附加链接预览卡片或在多选菜单中建议内容。 |
| 从聊天室中移除 |
用户从聊天室中移除 Chat 应用,或者 Google Workspace 管理员为组织中的用户卸载 Chat 应用。 用户无法移除由管理员安装的 Chat 扩展应用。如果用户之前安装了 Chat 应用,则无论 Google Workspace 管理员是否尝试卸载该应用,Chat 应用都会保持安装状态。 |
Chat 应用会移除为聊天室配置的所有传入通知(例如删除 Webhook),并清理所有内部存储空间。Chat 应用已不再是聊天室的成员,因此无法通过消息响应此触发器。 |
| 应用指令 |
用户调用 Chat 应用命令(例如斜杠命令、快速命令或消息操作)。 |
Chat 应用会响应命令。例如,它会回复消息或打开对话框。 |
| 应用首页 |
用户在与 Chat 应用的 1 对 1 私信 (DM) 聊天室中打开首页标签页,或与首页卡片上的 widget 互动。 |
Chat 应用会返回一个 RenderActions 对象,该对象会推送首页卡片 (pushCard) 或更新显示的首页卡片 (updateCard)。
|
您可以在 Google Cloud 控制台的 Chat API 配置页面上为这些触发器配置端点或回调函数。如需查看分步说明,请参阅配置 Google Chat API。
配置预设提示词
当用户打开与您的应用的空白 1 对 1 私信时,预设提示词可帮助用户了解您的 Chat 应用的功能。您最多可以配置三个预设提示词。
如需添加和配置预设提示词,请执行以下操作:
在 Google Cloud 控制台中,前往 Chat API 配置页面:
在互动功能下,找到预设提示词,然后点击添加提示词。
在排名 (1-3) 字段中,输入
1到3之间的数字,以指定显示顺序。在类型选择下,选择提示的行为方式:
- 文本提示词:当用户点击提示词条状标签时,在撰写栏中填充预定义文本。
- 命令提示符:点击后会运行已注册的斜杠命令或快捷命令。无法选择需要额外参数的命令。
根据您选择的类型配置提示:
如果您选择了“文本提示词”:
- 在标题中,输入条状标签上显示的提示标题(最多 30 个字符)。
- 在提示文本中,输入要在撰写栏中填充的文本(最多 60 个字符)。
- 可选:为使用其他语言的用户添加本地化标题和文字:
- 在本地化提示下,点击添加语言。
- 在语言中,从下拉菜单中选择一种受支持的语言。
- 在本地化标题中,输入本地化标题(最多 30 个字符)。
- 在本地化提示文本中,输入本地化提示文本(最多 60 个字符)。
- 根据需要重复上述步骤,添加更多语言。
如果您选择了“命令提示符”:
- 在斜杠命令/快捷命令中,从下拉菜单中选择相应命令。
点击完成,然后点击页面底部的保存。
处理对服务的 HTTP 调用重试
如果向您的服务发出的 HTTPS 请求失败(例如超时、临时网络故障或非 2xx HTTPS 状态代码),Google Chat 可能会在几分钟内重试几次(但不保证一定能成功)。因此,在某些情况下,Chat 应用可能会多次收到同一事件。如果请求成功完成,但返回了无效的响应载荷,Google Chat 不会重试该请求。
事件对象
当 Chat 触发器运行或 Chat 用户与 Chat 应用中的界面互动(例如点击按钮或提交对话框)时,Chat 应用会收到事件对象。借助事件对象,您可以使用互动数据来响应或更新界面。
2025 年,Google Chat 应用进行了扩展,以支持插件事件,自 2025 年 7 月起,这一直是新 Chat 应用的默认设置。在整个 Chat 文档中,插件事件是指南和代码示例中显示的标准事件类型。Chat 事件(适用于非 Google Workspace 插件的 Chat 应用)的文档分为折叠部分(例如,非插件的 Chat 应用:接收和响应互动事件)。
确定事件和响应类型
当 Chat 应用收到事件对象时,载荷的结构以及您的响应方式取决于 Chat 应用是否配置为 Google Workspace 插件。
如需确认您的应用会收到哪种类型的事件对象以及应如何响应,请使用下表检查应用的配置:
| 应用类型 | 接收插件事件 (2025 年 7 月之后创建的新应用的默认设置) |
接收 Chat 事件 (2025 年 7 月之前的默认设置) |
|---|---|---|
| Apps 脚本应用 检查清单文件 ( appsscript.json) |
chat 对象在 addOns 中配置:
|
chat 对象在清单的根目录中配置:
|
| 其他应用 查看 Google Chat API 配置页面 |
“将此 Chat 扩展应用作为 Google Workspace 插件构建”复选框已选中。 | 未选中“将此 Chat 扩展应用作为 Google Workspace 插件构建”复选框。 |
| 如何找到文档 | 在指南和代码示例中 事件参考文档: 插件事件对象 |
收起的部分(例如,非插件的 Chat 应用:接收和响应互动事件) 事件参考文档: Chat API 互动事件 |
| 如何回应 | 返回操作,例如 DataActions 或 RenderActions。了解如何通过操作进行响应 |
返回 Message 资源。了解如何通过消息回复 |
事件对象载荷
每个插件事件对象都包含一个 commonEventObject,其中包含主机和平台详细信息(hostApp: "CHAT"、clientPlatform、userLocale、userTimezone、parameters 和 formInputs),以及一个包含 Chat 专用上下文的 chat 对象:
- 对于应用首页触发器(当用户在与 Chat 应用的 1 对 1 私信中打开首页标签页时),
chat对象包含chat.user和chat.eventTime,但不包含联合payload字段。当用户点击首页卡片中的按钮时,事件对象会包含chat.buttonClickedPayload以及commonEventObject.parameters(如果卡片包含表单输入,则还包含commonEventObject.formInputs)。 - 对于聊天室和消息互动(已添加到聊天室、消息、已从聊天室中移除、应用命令或按钮和 widget 互动),
chat对象包含chat.user、chat.space、chat.eventTime和相应的互动载荷:messagePayload:包含用户发送消息时的space、message和configCompleteRedirectUri。addedToSpacePayload:包含将 Chat 应用添加到聊天室时的space、interactionAdd和configCompleteRedirectUri。removedFromSpacePayload:包含从聊天室中移除 Chat 应用时的space。buttonClickedPayload:当用户点击卡片或对话框上的按钮时,包含space、message、isDialogEvent和dialogEventType。widgetUpdatedPayload:当用户与 widget 互动时(例如在具有外部数据源的多选菜单中输入内容),包含space。appCommandPayload:包含用户调用应用命令时的space、message、appCommandMetadata、isDialogEvent、dialogEventType和configCompleteRedirectUri。
如需了解 Chat 和其他 Google Workspace 应用中的插件事件对象,请参阅事件对象。
给出针对性回应
本部分介绍了 Chat 应用如何使用操作同步响应用户互动。
如需通过操作进行响应,Chat 应用必须在 30 秒内响应,并且响应必须应用于发生互动的聊天室。这些同步响应不需要身份验证。如果您的 Chat 应用需要超过 30 秒的时间或需要在聊天室之外执行操作,请设置身份验证并使用 Google Chat API 异步响应。
为了同步响应用户互动,Chat 应用会处理传入的事件对象,并返回以下 JSON 对象之一:
DataActions:使用chatDataActionMarkup创建或更新聊天消息(CreateMessageAction、UpdateMessageAction)或附加链接预览 (UpdateInlinePreviewAction)。RenderActions:创建、更新或关闭首页或对话框(pushCard、updateCard、endNavigation: "CLOSE_DIALOG"),或为多选菜单 (modifyCard) 提供动态输入建议。AuthorizationError:提示用户使用基本授权卡片 (basic_authorization_prompt) 登录或向外部服务进行身份验证。
下表展示了 Chat 应用如何通过操作进行响应。Chat 应用可以直接返回 JSON 对象,也可以使用 Apps 脚本的 AddOnResponseService 和 CardService 构建响应。
| Chat 应用响应 | 要返回的操作(JSON 格式,必填) | 需要采取的行动(Apps 脚本) |
|---|---|---|
| 发送消息或更新消息。 | DataActions(createMessageAction 或 updateMessageAction) |
DataActionsResponse |
| 预览 Chat 用户在聊天室中发送的消息中的链接。 | DataActions (updateInlinePreviewAction) |
DataActionsResponse |
| 在私信的主屏幕标签页中呈现或更新首页。 | RenderActions(pushCard 或 updateCard) |
ActionResponse |
| 打开、更新或关闭对话框。 | RenderActions(pushCard、updateCard 或 endNavigation: "CLOSE_DIALOG") |
ActionResponse |
| 如需从卡片或对话框中收集信息,请根据用户在多选菜单中输入的内容建议选择项。 | RenderActions (modifyCard) |
ActionResponse |
| 请求外部服务的配置或授权。 | AuthorizationError (basic_authorization_prompt) |
AuthorizationException |
使用信息回复
Chat 应用可以针对以下任何触发器或互动回复消息:
- 消息触发器,例如用户 @提及 Chat 应用或向 Chat 应用发送私信。
- 添加到聊天室触发器,例如当用户从 Google Workspace Marketplace 安装 Chat 应用或将其添加到聊天室时。
- 应用命令触发器,例如当用户调用斜杠命令或快捷命令时。
- 消息或对话框中卡片的按钮点击次数。例如,当用户输入信息并点击“提交”时。
Chat 应用可以在消息中包含以下任何内容:
- 包含超链接、@提及和表情符号的文本。请参阅设置消息格式。
- 一张或多张卡片,可以显示在消息中,也可以作为对话框在新窗口中打开。请参阅为 Google Chat 应用构建卡片。
- 一个或多个辅助微件,即显示在消息中的任何文本或卡片后面的按钮。
如需回复消息,请返回包含 CreateMessageAction 对象的 DataActions:
{
"hostAppDataAction": {
"chatDataAction": {
"createMessageAction": {
"message": <var>MESSAGE</var>
}
}
}
}
将 MESSAGE 替换为 Chat API 中的 Message 资源。
在以下示例中,Chat 应用在被添加到聊天室时,会通过使用 DataActions 响应已添加到聊天室触发器来创建并发送新手入门短信:
Node.js
/**
* Sends an onboarding message when the Chat app is added to a space.
*
* @param {Object} req The request object from Google Chat.
* @param {Object} res The response object from the Chat app.
*/
exports.cymbalApp = function cymbalApp(req, res) {
const chatEvent = req.body.chat;
// Send an onboarding message when added to a Chat space
if (chatEvent.addedToSpacePayload) {
res.json({ hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
text: 'Hi, Cymbal at your service. I help you manage your calendar ' +
'from Google Chat. Take a look at your schedule today by typing ' +
'`/checkCalendar`, or schedule a meeting with `/scheduleMeeting`. ' +
'To learn what else I can do, type `/help`.'
}}}}});
}
};
Python
from flask import Flask, request, json
app = Flask(__name__)
@app.route('/', methods=['POST'])
def cymbal_app():
"""Sends an onboarding message when the Chat app is added to a space.
Returns:
Mapping[str, Any]: The response object from the Chat app.
"""
chat_event = request.get_json()["chat"]
if "addedToSpacePayload" in chat_event:
return json.jsonify({ "hostAppDataAction": { "chatDataAction": {
"createMessageAction": { "message": {
"text": 'Hi, Cymbal at your service. I help you manage your calendar ' +
'from Google Chat. Take a look at your schedule today by typing ' +
'`/checkCalendar`, or schedule a meeting with `/scheduleMeeting`. ' +
'To learn what else I can do, type `/help`.'
}}
}}})
Java
@SpringBootApplication
@RestController
public class App {
public static void main(String[] args) {
SpringApplication.run(App.class, args);
}
/*
* Sends an onboarding message when the Chat app is added to a space.
*
* @return The response object from the Chat app.
*/
@PostMapping("/")
@ResponseBody
public GenericJson onEvent(@RequestBody JsonNode event) throws Exception {
JsonNode chatEvent = event.at("/chat");
if (!chatEvent.at("/addedToSpacePayload").isEmpty()) {
return new GenericJson() { {
put("hostAppDataAction", new GenericJson() { {
put("chatDataAction", new GenericJson() { {
put("createMessageAction", new GenericJson() { {
put("message", new Message().setText(
"Hi, Cymbal at your service. I help you manage your calendar " +
"from Google Chat. Take a look at your schedule today by typing " +
"`/checkCalendar`, or schedule a meeting with `/scheduleMeeting`. " +
"To learn what else I can do, type `/help`."
));
} });
} });
} });
} };
}
return new GenericJson();
}
}
Apps 脚本
/**
* Sends an onboarding message when the Chat app is added to a space.
*
* @param {Object} event The event object from Google Chat.
* @return {Object} Response from the Chat app.
*/
function onAddedToSpace(event) {
return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
text: 'Hi, Cymbal at your service. I help you manage your calendar ' +
'from Google Chat. Take a look at your schedule today by typing ' +
'`/checkCalendar`, or schedule a meeting with `/scheduleMeeting`. ' +
'To learn what else I can do, type `/help`.'
}}}}};
}
该代码示例会返回以下短信:
更新消息
Chat 应用还可以更新其发送的消息。例如,在用户提交对话框或点击消息中卡片上的按钮后,Chat 应用可以更新消息。
如需更新 Chat 应用消息以响应互动,请返回包含 UpdateMessageAction 的 DataActions:
{
"hostAppDataAction": {
"chatDataAction": {
"updateMessageAction": {
"message": <var>MESSAGE</var>
}
}
}
}
将 MESSAGE 替换为 Chat API 中的 Message 资源。
Chat 应用还可以使用 updateInlinePreviewAction 更新用户发送的消息,以附加链接预览卡片。如需了解详情,请参阅预览链接。
使用 Google Chat API 异步回复
Chat 应用可能需要调用 Google Chat API 来响应互动或发送主动消息,而不是同步返回操作。例如,Chat 应用必须调用 Google Chat API 才能执行以下任一操作:
- 在 30 秒后响应互动(例如在完成长时间运行的任务后)。
- 按时间表发送消息,或发送有关外部资源更改的通知。
- 在互动发生的聊天室之外执行任务。
- 在 Chat 中执行无法作为同步操作执行的任务,例如列出聊天室或向聊天室添加成员。
- 代表 Chat 用户执行任务(需要用户身份验证)。
如果在 30 秒后响应互动,为避免向用户显示 Chat 应用未响应的错误消息,您必须在 30 秒内返回空响应,以确认收到事件对象:
Node.js
async function onEvent(req, res) {
// Trigger asynchronous job that will respond using the Google Chat API.
...
// Respond with an empty response to the Google Chat platform.
return res.send({});
};
Python
def on_event(event) -> dict:
# Trigger asynchronous job that will respond using the Google Chat API.
...
// Respond with an empty response to the Google Chat platform.
return {}
Java
public String onEvent(JsonNode event) {
// Trigger asynchronous job that will respond using the Google Chat API.
...
// Respond with an empty response to the Google Chat platform.
return "{}";
}
Apps 脚本
function onEvent(event) {
// Trigger asynchronous job that will respond using the Google Chat API.
...
// Respond with an empty response to the Google Chat platform.
return null;
}
如需使用 Chat API 发送消息,请设置身份验证并调用 spaces.messages.create 方法。如需了解相关步骤,请参阅发送消息。如需查看有关使用其他 Chat API 方法的指南,请参阅 Chat API 概览。
相关主题
- 配置 Google Chat API
- 发送消息
- 响应命令
- 打开互动式对话框
- 读取用户在卡片上输入的表单数据
- 预览链接
- 为 Chat 应用构建首页
- 验证来自 Chat 的请求
- 测试 Google Chat 应用的互动功能
非插件的 Chat 应用:接收并响应用户互动
非 Google Workspace 插件的 Chat 应用会收到 Chat API 互动事件 (Event),而不是 Google Workspace 插件事件对象 (EventObject),并通过返回 Message 资源(而非操作)进行响应。
如需将非插件的 Chat 应用升级到 Google Workspace 插件框架,请参阅将 Google Chat 应用转换为 Google Workspace 插件。
互动事件类型
对于每种类型的用户互动,Google Chat 都会向非插件的 Chat 应用发送一个 Event 对象,其类型由 eventType 字段表示:
| 用户互动 | eventType |
非插件 Chat 应用的典型回答 |
|---|---|---|
| 用户向 Chat 应用发送消息。例如,@提及 Chat 应用或使用斜杠命令。 | MESSAGE |
Chat 应用会根据消息内容进行回复。例如,Chat 应用会回复斜杠命令 /about,并发送一条消息,说明 Chat 应用可以执行的任务。 |
| 用户将 Chat 应用添加到聊天室。 | ADDED_TO_SPACE |
Chat 应用会发送一条新手入门消息,说明其功能以及聊天室中的用户如何与其互动。 |
| 用户从聊天室中移除 Chat 应用。 | REMOVED_FROM_SPACE |
Chat 应用会移除为聊天室配置的所有传入通知(例如删除 Webhook),并清理所有内部存储空间。 |
| 用户点击 Chat 应用消息、对话框或首页中的卡片上的按钮。 | CARD_CLICKED |
Chat 应用会处理并存储用户提交的所有数据,或返回另一张卡片。 |
| 用户通过点击 1 对 1 消息中的首页标签页,打开 Chat 应用的首页。 | APP_HOME |
Chat 应用会从首页返回静态或互动式卡片。 |
| 用户从 Chat 应用的首页提交表单。 | SUBMIT_FORM |
Chat 应用会处理并存储用户提交的所有数据,或返回另一张卡片。 |
| 用户使用快捷指令调用指令。 | APP_COMMAND |
Chat 应用会根据调用的命令做出响应。例如,Chat 应用会回复 About 命令,并显示一条消息,说明 Chat 应用可以执行的任务。 |
如需查看所有受支持的互动事件和 JSON 载荷示例,请参阅 Chat 应用互动事件的类型和 EventType 参考文档。
对话框中的互动事件
如果您的 Chat 应用不是插件,而是打开对话框,则互动事件会包含以下额外信息,您可以使用这些信息来处理响应:
isDialogEvent字段设置为true。DialogEventType(REQUEST_DIALOG、SUBMIT_DIALOG或CANCEL_DIALOG)阐明了互动是触发对话框打开、提交对话框中的信息,还是关闭对话框。
将非插件 Chat 应用配置为接收互动事件
在 Google Cloud 控制台中,前往 Chat API 配置页面:
在互动功能下,清除将此 Chat 应用构建为 Google Workspace 插件,然后配置功能、单个连接设置端点(HTTP 端点网址、Apps 脚本、Cloud Pub/Sub 主题名称或 Dialogflow)、命令、预设提示词、链接预览和公开范围。
点击保存。
在非插件的 Chat 应用中回复消息
如需在非插件的 Chat 应用中同步响应,请直接返回 Message 对象。以下示例使用短信响应 ADDED_TO_SPACE 互动事件:
Node.js
/**
* Sends an onboarding message when the Chat app is added to a space.
*
* @param {Object} req The event object from Chat API.
* @param {Object} res The response object from the Chat app.
*/
exports.cymbalApp = function cymbalApp(req, res) {
// Send an onboarding message when added to a Chat space
if (req.body.type === 'ADDED_TO_SPACE') {
res.json({
'text': 'Hi, Cymbal at your service. I help you manage your calendar ' +
'from Google Chat. Take a look at your schedule today by typing ' +
'`/checkCalendar`, or schedule a meeting with `/scheduleMeeting`. To ' +
'learn what else I can do, type `/help`.'
});
}
};
Python
from flask import Flask, request, json
app = Flask(__name__)
@app.route('/', methods=['POST'])
def cymbal_app():
"""Sends an onboarding message when the Chat app is added to a space.
Returns:
Mapping[str, Any]: The response object from the Chat app.
"""
event = request.get_json()
if event['type'] == 'ADDED_TO_SPACE':
return json.jsonify({
'text': 'Hi, Cymbal at your service. I help you manage your calendar ' +
'from Google Chat. Take a look at your schedule today by typing ' +
'`/checkCalendar`, or schedule a meeting with `/scheduleMeeting`. To ' +
'learn what else I can do, type `/help`.'
})
return json.jsonify({})
Java
@SpringBootApplication
@RestController
public class App {
public static void main(String[] args) {
SpringApplication.run(App.class, args);
}
/*
* Sends an onboarding message when the Chat app is added to a space.
*
* @return The response object from the Chat app.
*/
@PostMapping("/")
@ResponseBody
public Message onEvent(@RequestBody JsonNode event) {
switch (event.get("type").asText()) {
case "ADDED_TO_SPACE":
return new Message().setText(
"Hi, Cymbal at your service. I help you manage your calendar " +
"from Google Chat. Take a look at your schedule today by typing " +
"`/checkCalendar`, or schedule a meeting with `/scheduleMeeting`. " +
"To learn what else I can do, type `/help`.");
default:
return new Message();
}
}
}
Apps 脚本
/**
* Sends an onboarding message when the Chat app is added to a space.
*
* @param {Object} event The event object from Chat API.
* @return {Object} Response from the Chat app.
*/
function onAddToSpace(event) {
return {
'text': 'Hi, Cymbal at your service. I help you manage your calendar ' +
'from Google Chat. Take a look at your schedule today by typing ' +
'`/checkCalendar`, or schedule a meeting with `/scheduleMeeting`. To learn ' +
'what else I can do, type `/help`.'
};
}