Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

构建 Google Chat 界面

本页概述了如何为扩展 Google Chat 的 Google Workspace 插件构建界面 (UI)。

如需为 Chat 应用构建界面，您可以使用以下插件组件：

触发器：Google Chat 用户调用 Chat 应用的方式，例如将其添加到聊天室或向其发送消息。
事件对象：Chat 应用从触发器或界面互动接收的数据。
操作：Chat 应用可以响应互动的方式，例如发送消息或返回基于卡片的用户界面。

Chat 应用从“已添加到聊天室”触发器接收事件对象 — **图 1**：当用户将 Chat 应用添加到聊天室时，**添加到聊天室**触发器会触发并发送事件对象。如需通过消息进行回复，Chat 应用会处理事件对象并返回一个用于创建消息的操作。

聊天应用可以在以下界面中构建和显示卡片：

消息：可以包含文字、静态或互动卡片以及按钮。
在与 Chat 应用的 1 对 1 私信的首页标签页中显示的首页。
对话框：在新的窗口中打开的卡片，通常会提示用户提交信息。
链接预览，即用于预览外部服务相关信息的卡片。

触发器

本部分介绍了 Google Workspace 加载项在 Chat 中使用的触发器。

触发器是指用户通过 Chat 界面调用 Chat 应用的具体方式，例如使用 @提及或应用命令。

下表显示了聊天触发器、说明以及聊天应用通常如何响应：

触发器	说明	典型回答
已添加到聊天室	用户将 Chat 应用添加到聊天室，或者 Google Workspace 管理员为组织中的用户在私信聊天室中安装 Chat 应用。如需了解管理员安装的 Chat 应用，请参阅 Google Workspace 管理员帮助文档中的在您的网域中安装 Marketplace 中的应用。	Chat 应用会发送一条引导消息，说明其功能以及聊天室中的用户如何与其互动。
短信	用户可以通过以下任一方式在消息中与 Chat 应用互动：在私信 (DM) 聊天室中使用 Chat 应用发送消息。在任何类型的聊天室中 @提及 Chat 应用。发送包含与链接预览的网址格式匹配的链接的消息。在 `selectionInput` widget 的多选菜单中输入文本。	聊天应用会根据消息内容做出回答。例如，聊天应用会回复斜杠命令 `/about`，并发送一条消息来解释聊天应用可以执行的任务。
从聊天室中移除	用户从聊天室中移除 Chat 应用，或者 Google Workspace 管理员为其组织中的用户卸载 Chat 应用。用户无法移除由其管理员安装的 Chat 扩展应用。如果用户之前已安装 Chat 应用，则无论 Google Workspace 管理员是否尝试卸载，Chat 应用都会保持安装状态。	Chat 应用会移除为聊天室配置的所有入站通知（例如删除 Webhook），并清理所有内部存储空间。聊天应用无法通过消息响应此触发器，因为它们已不再是相应聊天室的成员。
应用命令	用户使用 Chat 应用命令。	Chat 应用会响应该命令。例如，回复消息或打开对话框。
应用首页	用户在与 Chat 应用的一对一私信 (DM) 聊天室中打开首页标签页，或与首页卡片上的 widget 互动。	Chat 应用会返回一个 `RenderActions` 对象，该对象用于推送首页卡片 (`pushCard`) 或更新显示的首页卡片 (`updateCard`)。

与其他插件不同，您必须使用 Google Chat API 为这些触发器配置任何回调函数。如需相关指导，请参阅配置聊天应用。

如需响应触发器，请参阅以下指南：

事件对象

当 Chat 触发器运行或 Chat 用户与 Chat 应用中的界面（例如点击按钮）互动时，Chat 应用会收到事件对象。借助事件对象，您可以使用互动数据来响应或更新界面。

事件对象载荷

每个 Chat 事件对象都包含一个 commonEventObject，其中包含主机和平台详细信息（hostApp: "CHAT"、clientPlatform、userLocale、userTimezone 和 formInputs），以及一个 chat 对象，其中包含特定于 Chat 的上下文：

对于应用首页触发器（当用户在与 Chat 应用的 1 对 1 私信中打开首页标签页时），chat 对象包含 chat.user 和 chat.eventTime，但不包含联合 payload 字段。当用户点击首页卡片中的按钮时，事件对象还会包含 commonEventObject.parameters（如果卡片包含表单输入，则还会包含 commonEventObject.formInputs）。
对于聊天室和消息互动（已添加到聊天室、消息、已从聊天室中移除、应用命令或按钮和 widget 互动），chat 对象包含 chat.user、chat.space、chat.eventTime 和相应的互动载荷（messagePayload、addedToSpacePayload、removedFromSpacePayload、buttonClickedPayload、widgetUpdatedPayload 或 appCommandPayload）。

如需了解如何处理事件对象，请参阅以下指南：

如需了解 Chat 和其他 Google Workspace 应用中的插件事件对象，请参阅事件对象。

对话操作

本部分将介绍 Chat 应用如何使用插件操作来响应用户互动。

如需通过插件操作进行回复，Chat 应用必须在 30 秒内做出响应，并且必须在发生互动的聊天室中发布响应。否则，Chat 应用必须设置身份验证并调用 Google Chat API 以做出响应。

聊天应用可以通过多种方式处理互动并做出回应。在许多情况下，Chat 应用会回复消息。聊天应用还可以从数据源中查找某些信息、记录事件对象信息，或者执行其他任何操作。这种处理行为从本质上定义了 Google Chat 应用。

为了响应用户互动，聊天应用必须处理相应的事件对象，并返回以下 JSON 对象之一：

DataActions：创建或更新 Google Workspace 数据。如需发送或更新即时通讯消息，该对象必须包含用于定义 Message 数据更改的标记（以 chatDataActionMarkup 表示）。
RenderActions：创建或更新首页或对话框，或为多选菜单提供输入建议。
AuthorizationError：通过授权卡片提示用户登录或向 Google 外部的服务进行身份验证。在聊天中，仅支持基本授权卡片。

下表展示了 Chat 应用如何通过操作进行响应。Chat 应用可以返回 JSON 对象，也可以使用 Apps 脚本的 AddOnResponseService 构建响应。

聊天应用回答	返回（JSON）所需的操作	返回所需的操作（Apps 脚本）
发送或更新消息。	`DataActions`	`DataActionsResponse`
在私信的主屏幕标签页中呈现或更新首页。	`RenderActions`	`ActionResponse`
打开、更新或关闭对话框。	`RenderActions`	`ActionResponse`
为了从卡片或对话框中收集信息，根据用户在多选菜单中输入的内容建议选择项。	`RenderActions`	`ActionResponse`
Chat 用户在聊天室中发送的消息中的链接预览。	`DataActions`	`DataActionsResponse`

使用 Google Chat API 进行回复

Chat 应用可能需要使用 Google Chat API 来响应互动，而不是返回加购项操作。例如，Chat 应用必须调用 Google Chat API 才能执行以下任何操作：

在 30 秒后响应互动。
在互动发生的空间之外执行任务。
在 Chat 中执行无法作为插件操作执行的任务。例如，列出用户或 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 进行身份验证和调用，请参阅 Chat API 概览。