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

接收和响应用户互动

本页介绍了 Google Chat 应用如何接收和响应 Google Chat 中的用户互动。

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

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

Chat 应用从“已添加到聊天室”触发器接收事件对象 — **图 1**：当用户将 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 应用如何处理用户互动并做出响应：

Google Chat 应用处理用户互动的架构。

触发器

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

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

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

您可以在 Google Cloud 控制台的 Chat API 配置页面中配置这些触发器的端点或回调函数。如需查看分步说明，请参阅配置 Google Chat API。

配置预设提示

当用户打开与您的 Chat 应用之间的空白一对一私信时，初始提示可帮助用户了解您的 Chat 应用的功能。您最多可以配置三个初始提示。

如需添加和配置启动提示，请执行以下操作：

在 Google Cloud 控制台中，前往 Chat API 配置页面：

前往 Chat API 配置页面
在互动功能下，找到初始提示，然后点击添加提示。
在排名（1-3）字段中，输入一个介于 1 到 3 之间的数字，以指定显示顺序。
在类型选择下，选择提示的行为方式：
- 文本提示：当用户点击提示条状标签时，在撰写栏中填充预定义的文本。
- 命令提示符：点击后运行已注册的斜杠命令或快捷命令。无法选择需要额外实参的命令。
根据您选择的类型配置提示：
- 如果您选择了“文本提示”：
  1. 在标题中，输入显示在条状标签上的提示标题（最多 30 个字符）。
  2. 在提示文本中，输入撰写栏中填充的文字（最多 60 个字符）。
  3. 可选：为使用其他语言的用户添加本地化标题和文字：
  4. 在本地化提示下，点击添加语言。
  5. 在语言中，从下拉菜单中选择一种支持的语言。
  6. 在本地化标题中，输入本地化标题（最多 30 个字符）。
  7. 在本地化提示文本中，输入本地化提示文本（最多 60 个字符）。
  8. 根据需要重复此步骤以添加更多语言。
- 如果您选择了“命令提示符”：
  1. 在 斜杠命令 / 快速命令中，从下拉菜单中选择命令。
点击完成，然后点击页面底部的保存。

处理对服务的 HTTP 调用重试

如果向您的服务发出的 HTTPS 请求失败（例如超时、临时网络故障或非 2xx HTTPS 状态代码），Google Chat 可能会在几分钟内重试几次（但不能保证）。因此，在某些情况下，Chat 应用可能会多次收到同一事件。如果请求成功完成，但返回的响应载荷无效，Google Chat 不会重试该请求。

事件对象

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

事件对象载荷

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

对于应用首页触发器（当用户在与 Chat 应用的 1 对 1 私信中打开首页标签页时），chat 对象包含 chat.user 和 chat.eventTime，但不包含联合 payload 字段。当用户点击首页卡片中的按钮时，事件对象会包含 chat.buttonClickedPayload 以及 commonEventObject.parameters（如果卡片包含表单输入，还会包含 commonEventObject.formInputs）。
对于聊天室和消息互动（添加到聊天室、消息、从聊天室中移除、应用命令或按钮和小部件互动），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 应用如何使用操作来同步响应用户互动。

如需通过操作进行响应，聊天应用必须在 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 应用如何通过操作进行响应。聊天应用可以直接返回 JSON 对象，也可以使用 Apps 脚本的 AddOnResponseService 和 CardService 构建响应。

聊天应用回答	返回（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 应用发送消息时。
添加到聊天室触发器，例如当用户从 Google Workspace Marketplace 安装 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 应用消息以响应互动，请返回包含 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 概览。

非插件型 Chat 应用：接收并响应用户互动

不是 Google Workspace 加载项的聊天应用会收到 Chat API 互动事件 (Event)，而不是 Google Workspace 加载项事件对象 (EventObject)，并通过返回 Message 资源（而非操作）进行响应。

如需将非插件的 Chat 扩展应用升级到 Google Workspace 插件框架，请参阅将 Google Chat 扩展应用转换为 Google Workspace 插件。

互动事件类型

对于每种类型的用户互动，Google Chat 都会向非插件型 Chat 应用发送一个 Event 对象，该对象的类型由 eventType 字段表示：

用户互动	`eventType`	非插件型聊天应用的典型响应
用户向 Chat 应用发送消息。例如， @提及 Chat 应用或使用斜杠命令。	`MESSAGE`	聊天应用会根据消息的内容做出回答。例如，聊天应用会回复斜杠命令 `/about`，并发送一条消息来解释聊天应用可以执行的任务。
用户将 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 应用会根据调用的命令做出响应。例如，聊天应用会回复 About 命令，并发送一条消息来解释该聊天应用可以执行的任务。

如需查看所有受支持的互动事件和 JSON 载荷示例，请参阅聊天应用互动事件的类型和 EventType 参考文档。

对话框中的互动事件

如果您的非插件 Chat 应用打开对话框，互动事件会包含以下额外信息，您可以使用这些信息来处理回答：

isDialogEvent 字段设置为 true。
DialogEventType（REQUEST_DIALOG、SUBMIT_DIALOG 或 CANCEL_DIALOG）用于明确互动是触发打开对话框、提交对话框中的信息，还是关闭对话框。

配置非插件 Chat 应用以接收互动事件

在 Google Cloud 控制台中，前往 Chat API 配置页面：

前往 Chat API 配置页面
在互动功能下，取消选中将此聊天应用构建为 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`.'
  };
}

接收和响应用户互动 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

前提条件

用户互动的运作方式

触发器

配置预设提示

处理对服务的 HTTP 调用重试

事件对象

事件对象载荷

交付回答

使用信息回复

Node.js

Python

Java

Apps 脚本

更新消息

使用 Google Chat API 异步响应

Node.js

Python

Java

Apps 脚本

相关主题

非插件型 Chat 应用：接收并响应用户互动

互动事件类型

对话框中的互动事件

配置非插件 Chat 应用以接收互动事件

在非插件的 Chat 应用中回复消息

Node.js

Python

Java

Apps 脚本

接收和响应用户互动