构建 Google Chat 界面

本页面简要介绍了如何为扩展 Google Chat 的 Google Workspace 插件构建界面 (UI)。

在 Google Chat 中，插件会以 Google Chat 应用的形式向用户显示。如需了解详情，请参阅扩展 Google Chat 概览。

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

  • 触发器：Google Chat 用户可以通过哪些方式调用 Chat 应用，例如将其添加到聊天室或向其发送消息。
  • 事件对象：Chat 应用从触发器或界面互动收到的数据。
  • 操作：聊天应用可以通过哪些方式响应互动，例如发送消息或返回基于卡片的界面。
Chat 应用从“添加到聊天室”触发器收到事件对象
图 1：当用户将 Chat 应用添加到聊天室时，添加到聊天室触发器会触发并发送事件对象。如需使用消息进行响应，Chat 应用会处理事件对象，并返回用于创建消息的操作。

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

  • 消息，可以包含文字、静态或互动卡片和按钮。
  • 对话框：在新窗口中打开的卡片，通常会提示用户提交信息。
  • 链接预览：用于预览外部服务相关信息的卡片。

触发器

本部分介绍 Google Workspace 插件在 Chat 中使用的触发器。

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

下表显示了 Chat 触发器、说明以及 Chat 应用的典型响应方式：

触发器 说明 典型回复
已添加到聊天室

用户将 Chat 应用添加到聊天室，或者 Google Workspace 管理员为其组织中的用户在私信聊天室中安装 Chat 应用。如需了解管理员安装的 Chat 应用，请参阅 Google Workspace 管理员帮助文档中的在您的网域中安装 Marketplace 中的应用。

 Chat 应用会发送一条新手入门消息，说明该应用的用途以及聊天室中的用户如何与之互动。
短信

用户通过以下任一方式在消息中与 Chat 应用互动：

  • 使用 Chat 应用在私信 (DM) 聊天室中发送消息。
  • 在任何类型的聊天室中 @ 提及 Chat 应用。
  • 发送包含与链接预览网址格式匹配的链接的消息。
  • 向 selectionInput widget 的多选菜单中输入文本。
 Chat 应用会根据消息内容做出响应。例如，聊天应用会使用一条消息回复 /about 命令，说明聊天应用可以执行的任务。
从聊天室中移除

用户从聊天室中移除 Chat 应用，或者 Google Workspace 管理员为其组织中的用户卸载 Chat 应用。

用户无法移除其管理员安装的 Chat 应用。如果用户之前安装了 Chat 应用，则无论 Google Workspace 管理员是否尝试卸载，Chat 应用都将保持安装状态。

 Chat 应用会移除为聊天室配置的所有传入通知（例如删除 webhook），并清除所有内部存储空间。聊天应用无法通过消息回复此触发器，因为它们已不再是聊天室的成员。
应用命令

用户使用 Chat 应用中的快捷命令或斜杠命令。

 Chat 应用会对该命令做出响应。例如，使用消息进行回复或打开对话框。

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

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

事件对象

本部分定义并介绍了 Chat 事件对象的所有元素。如需了解详情，请参阅事件对象。

事件对象
commonEventObject object (CommonEventObject)
一个对象，包含所有事件对象（无论是哪个托管应用）共有的信息。
chat object (Chat)
一个对象，其中包含有关 Chat 互动的所有信息。

聊天

聊天
chat.user object (User)
与 Chat 应用互动的 Chat 用户。
chat.space object (Space)
用户与 Chat 应用互动的 Chat 聊天室。
chat.eventTime

string (Timestamp format)

互动发生的时间。

联合字段 payload。

payload 只能是下列其中一项：
chat.messagePayload

object (MessagePayload)

Chat 应用从消息触发器收到的载荷。
chat.addedToSpacePayload

object (AddedToSpacePayload)

Chat 应用从添加到聊天室触发器收到的载荷。
chat.removedFromSpacePayload

object (RemovedFromSpacePayload)

Chat 应用从从聊天室中移除触发器收到的载荷。
chat.buttonClickedPayload

object (ButtonClickedPayload)

当用户点击消息或卡片中的按钮时，Chat 应用收到的载荷。如果用户点击按钮提交信息，commonEventObject.formInputs 对象将包含从用户收集的值。如需了解详情，请参阅 从 Google Chat 用户收集信息。
chat.widgetUpdatedPayload

object (WidgetUpdatedPayload)

当用户在 selectionInput widget 的多选菜单中输入文本时，Chat 应用收到的载荷。聊天应用可以使用此事件对象从动态数据源填充建议内容。例如，如需从外部数据源填充支持请求，聊天应用可以根据用户在菜单中输入的内容查询数据源，然后将任何匹配的支持请求作为可选项返回。

CommonEventObject.parameters['autocomplete_widget_query'] 对象包含用户输入到菜单中的字符串值。
chat.appCommandPayload

object (AppCommandPayload)

当用户使用 Chat 应用中的命令时，Chat 应用收到的载荷。

载荷

根据互动类型，该事件包含一个或多个 Chat API 资源的载荷。

消息载荷
MessagePayload
chat.messagePayload.message object (Message)
触发事件的 Chat 消息。
chat.messagePayload.space object (Space)
用户发送了调用 Chat 应用的消息所在的 Chat 聊天室。

已添加到聊天室载荷
AddedToSpacePayload
chat.addedToSpacePayload.space object (Space)
用户添加或安装 Chat 应用的 Chat 聊天室。

管理员安装 Chat 应用时，space.adminInstalled 字段会设为 true。

chat.addedToSpacePayload.interactionAdd boolean
用户是否使用消息将 Chat 应用添加到聊天室。例如，@提及 Chat 应用或使用斜线命令。 如果为 true，Chat 会发送另一个事件对象，其中包含一个 messagePayload，其中包含有关消息的信息。

已从聊天室载荷中移除
RemovedFromSpacePayload
chat.removedFromSpacePayload.space object (Space)
用户从中移除或卸载 Chat 应用的 Chat 聊天室。

当管理员卸载 Chat 应用时，space.adminInstalled 字段会设为 false。

按钮点击载荷
ButtonClickedPayload
chat.buttonClickedPayload.message object (Message)
包含用户点击的按钮的 Chat 消息。
chat.buttonClickedPayload.space object (Space)
用户点击 Chat 应用消息中的按钮所在的 Chat 聊天室。
chat.buttonClickedPayload.isDialogEvent boolean
用户是否点击了按钮以与对话框进行互动。
chat.buttonClickedPayload.dialogEventType enum (DialogEventType)
如果 isDialogEvent 为 true，则为对话框中的互动类型。

枚举 DialogEventType。

dialogEventType 的值只能是以下值之一：
TYPE_UNSPECIFIED 默认值。未指定。
REQUEST_DIALOG 用户请求显示对话框。例如，他们使用正斜线命令或点击消息中的按钮。
SUBMIT_DIALOG 用户点击对话框中的交互元素。例如，用户在对话框中填写信息，然后点击按钮提交信息。

更新后的微件载荷
WidgetUpdatedPayload
chat.widgetUpdatedPayload.space object (Space)
发生互动的 Chat 聊天室。

应用命令载荷
AppCommandPayload
chat.appCommandPayload.appCommandMetadata object (AppCommandMetadata)
有关用户使用了哪个命令以及如何触发该命令的元数据。
chat.appCommandPayload.space object (Space)
用户使用该命令的 Chat 聊天室。
chat.appCommandPayload.thread object (Thread)
如果互动发生在某个会话中，则为用户使用该命令的 Chat 会话。
chat.appCommandPayload.message object (Message)
用户使用正斜线命令发送的消息。
chat.appCommandPayload.configCompleteRedirectUri string
如果命令需要授权或配置，则为用户在 Google Chat 之外完成流程后重定向到的网址。
chat.appCommandPayload.isDialogEvent boolean
命令是否会打开对话框。
chat.appCommandPayload.dialogEventType enum (DialogEventType)
与对话框的互动类型。

枚举 DialogEventType。

dialogEventType 的值只能是以下值之一：
TYPE_UNSPECIFIED 默认值。未指定。
REQUEST_DIALOG 用户请求显示对话框。例如，他们使用正斜线命令或点击消息中的按钮。
SUBMIT_DIALOG 用户点击对话框中的交互元素。例如，用户在对话框中填写信息，然后点击按钮提交信息。
应用命令元数据
AppCommandMetadata
chat.appCommandPayload.appCommandMetadata.appCommandId

string (int64 format)

命令 ID。
chat.appCommandPayload.appCommandMetadata.appCommandType enum (AppCommandType)
命令类型。

枚举 AppCommandType。

AppCommandType 的值只能是以下值之一：
APP_COMMAND_TYPE_UNSPECIFIED 默认值。未指定。
SLASH_COMMAND 用户通过发送以斜杠 / 开头的消息来使用该命令。

聊天操作

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

如需使用插件操作进行响应，聊天应用必须在 30 秒内响应，并且响应必须发布在发生互动的位置。否则，Chat 应用必须设置身份验证并调用 Google Chat API 才能做出响应。

聊天应用可以通过多种方式处理和回应互动。在许多情况下，聊天应用会通过消息进行回复。聊天应用还可以从数据源查询一些信息、记录事件对象信息，或记录几乎任何其他信息。这种处理行为在本质上定义了 Google Chat 应用。

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

Chat 应用的预期响应 退货所需的操作
发送或更新消息。 DataActions
打开、更新或关闭对话框。 RenderActions
如需从卡片或对话框中收集信息，请根据用户在多选菜单中输入的内容建议选择项。 RenderActions
预览 Chat 用户在聊天室中发送的消息中的链接。 DataActions

使用 Google Chat API 进行回复

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

  • 在 30 秒后响应互动。
  • 在发生互动的工作区之外执行任务。
  • 在 Chat 中执行无法作为插件操作执行的任务。例如，列出用户或 Chat 应用所属的聊天室，或向聊天室添加用户。
  • 代表 Chat 用户执行任务（需要用户身份验证）。

如需了解如何对 Chat API 进行身份验证和调用，请参阅 Chat API 概览。