本页面简要介绍了如何为扩展 Google Chat 的 Google Workspace 插件构建界面 (UI)。
在 Google Chat 中，插件会以 Google Chat 应用的形式向用户显示。如需了解详情，请参阅扩展 Google Chat 概览。
如需为 Chat 应用构建界面，您可以使用以下插件组件：
- 触发器：Google Chat 用户可以通过哪些方式调用 Chat 应用，例如将其添加到聊天室或向其发送消息。
- 事件对象：Chat 应用从触发器或界面互动收到的数据。
- 操作：聊天应用可以通过哪些方式响应互动，例如发送消息或返回基于卡片的界面。
Chat 应用可以在以下界面中构建和显示卡片：
触发器
本部分介绍 Google Workspace 插件在 Chat 中使用的触发器。
触发器是指用户使用 Chat 界面调用 Chat 应用的具体方式，例如使用 @提及或斜杠命令。
下表显示了 Chat 触发器、说明以及 Chat 应用的典型响应方式：
| 触发器 | 说明 | 典型回复 |
|---|---|---|
| 已添加到聊天室 |
用户将 Chat 应用添加到聊天室，或者 Google Workspace 管理员为其组织中的用户在私信聊天室中安装 Chat 应用。如需了解管理员安装的 Chat 应用，请参阅 Google Workspace 管理员帮助文档中的在您的网域中安装 Marketplace 中的应用。 |
Chat 应用会发送一条新手入门消息，说明该应用的用途以及聊天室中的用户如何与之互动。 |
| 短信 |
用户通过以下任一方式在消息中与 Chat 应用互动： |
Chat 应用会根据消息内容做出响应。例如，Chat 应用会回复 /about 命令，并附上一条消息来说明 Chat 应用可以执行的任务。
|
| 从聊天室中移除 |
用户从聊天室中移除 Chat 应用，或者 Google Workspace 管理员为其组织中的用户卸载 Chat 应用。 用户无法移除其管理员安装的 Chat 应用。如果用户之前安装了 Chat 应用，则无论 Google Workspace 管理员是否尝试卸载，Chat 应用都将保持安装状态。 |
Chat 应用会移除为聊天室配置的所有传入通知（例如删除 webhook），并清除所有内部存储空间。聊天应用无法通过消息回复此触发器，因为它们已不再是聊天室的成员。 |
与其他 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 |
|
联合字段
|
|
chat.messagePayload |
Chat 应用从消息触发器收到的载荷。 |
chat.addedToSpacePayload |
Chat 应用从添加到聊天室触发器收到的载荷。 |
chat.removedFromSpacePayload |
Chat 应用从从聊天室中移除触发器收到的载荷。 |
chat.buttonClickedPayload |
当用户点击消息或卡片中的按钮时，Chat 应用收到的载荷。如果用户点击按钮提交信息， |
chat.widgetUpdatedPayload |
当用户在
|
载荷
根据互动类型，该事件包含一个或多个 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 应用时， |
chat.addedToSpacePayload.interactionAdd |
boolean用户是否使用消息将 Chat 应用添加到聊天室。例如，@提及 Chat 应用或使用斜线命令。 如果为 true，Chat 会发送另一个事件对象，其中包含一个 messagePayload，其中包含有关消息的信息。
|
已从聊天室载荷中移除
| RemovedFromSpacePayload | |
|---|---|
chat.removedFromSpacePayload.space |
object
(Space)
用户从中移除或卸载 Chat 应用的 Chat 聊天室。 当管理员卸载 Chat 应用时， |
按钮点击载荷
| 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，则为对话框中的互动类型。
|
枚举
|
|
TYPE_UNSPECIFIED |
默认值。未指定。 |
REQUEST_DIALOG |
用户请求显示对话框。例如，他们使用正斜线命令或点击消息中的按钮。 |
SUBMIT_DIALOG |
用户点击对话框中的交互元素。例如，用户在对话框中填写信息，然后点击按钮提交信息。 |
更新后的微件载荷
| WidgetUpdatedPayload | |
|---|---|
chat.widgetUpdatedPayload.space |
object
(Space)
发生互动的 Chat 聊天室。 |
聊天操作
本部分介绍了 Chat 应用如何使用插件操作来响应用户互动。
如需使用插件操作进行响应，聊天应用必须在 30 秒内响应，并且响应必须发布在发生互动的位置。否则，Chat 应用必须设置身份验证并调用 Google Chat API 才能做出响应。
聊天应用可以通过多种方式处理和回应互动。在许多情况下，聊天应用会通过消息进行回复。聊天应用还可以从数据源查询一些信息、记录事件对象信息，或记录几乎任何其他信息。这种处理行为在本质上定义了 Google Chat 应用。
如需响应用户互动，聊天应用必须处理相应的事件对象，并返回以下 JSON 对象之一：
DataActions：创建或更新 Google Workspace 数据。如需发送或更新 Chat 消息，该对象必须包含用于定义对Message数据所做的更改的标记，该标记表示为chatDataActionMarkup。RenderActions：在消息和对话框中显示卡片或在卡片之间导航。basic_authorization_prompt：使用授权卡提示用户登录或对 Google 以外的服务进行身份验证。如需了解详情，请参阅将 Google Workspace 插件与第三方服务相关联。
| 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 概览。