本页面简要介绍了如何为扩展 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 应用会根据消息内容做出响应。例如,聊天应用会使用一条消息回复 /about 命令,说明聊天应用可以执行的任务。
|
从聊天室中移除 |
用户从聊天室中移除 Chat 应用,或者 Google Workspace 管理员为其组织中的用户卸载 Chat 应用。 用户无法移除其管理员安装的 Chat 应用。如果用户之前安装了 Chat 应用,则无论 Google Workspace 管理员是否尝试卸载,Chat 应用都将保持安装状态。 |
Chat 应用会移除为聊天室配置的所有传入通知(例如删除 webhook),并清除所有内部存储空间。聊天应用无法通过消息回复此触发器,因为它们已不再是聊天室的成员。 |
应用命令 | 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 |
|
联合字段
|
|
chat.messagePayload |
Chat 应用从消息触发器收到的载荷。 |
chat.addedToSpacePayload |
Chat 应用从添加到聊天室触发器收到的载荷。 |
chat.removedFromSpacePayload |
Chat 应用从从聊天室中移除触发器收到的载荷。 |
chat.buttonClickedPayload |
当用户点击消息或卡片中的按钮时,Chat 应用收到的载荷。如果用户点击按钮提交信息, |
chat.widgetUpdatedPayload |
当用户在
|
chat.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 应用时, |
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 聊天室。 |
应用命令载荷
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) 与对话框的互动类型。 |
枚举
|
|
TYPE_UNSPECIFIED |
默认值。未指定。 |
REQUEST_DIALOG |
用户请求显示对话框。例如,他们使用正斜线命令或点击消息中的按钮。 |
SUBMIT_DIALOG |
用户点击对话框中的交互元素。例如,用户在对话框中填写信息,然后点击按钮提交信息。 |
应用命令元数据
AppCommandMetadata | |
---|---|
chat.appCommandPayload.appCommandMetadata.appCommandId |
命令 ID。 |
chat.appCommandPayload.appCommandMetadata.appCommandType |
enum (AppCommandType) 命令类型。 |
枚举
|
|
APP_COMMAND_TYPE_UNSPECIFIED |
默认值。未指定。 |
SLASH_COMMAND |
用户通过发送以斜杠 / 开头的消息来使用该命令。 |
聊天操作
本部分介绍了 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 概览。