发送 Google Chat 消息

本页介绍了 Google Chat 应用如何发送消息来回复用户互动。

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

  • 通过斜杠命令提供联系表单。
    图 1. 聊天应用使用文本消息和按钮响应斜杠命令。
  • 对话框中的联系表单。
    图 2. 聊天应用打开一个对话框，供用户输入信息。
  • 包含表单输入 widget 的卡片消息。
    图 5. Chat 应用发送包含文本和交互式卡片的消息。

前提条件

Node.js

这款 Google Workspace 插件可扩展 Google Chat 的功能。如需构建一个，请完成 HTTP 快速入门。

Apps 脚本

这款 Google Workspace 插件可扩展 Google Chat 的功能。如需构建此类应用，请完成 Apps 脚本快速入门。

设计消息

聊天应用可以在消息中包含以下任一内容：

  • 包含超链接、@提及和表情符号的文本。
  • 一个或多个卡片，可显示在消息中，或以对话框的形式在新窗口中打开。
  • 一个或多个配件 widget，即在消息中的任何文本或卡片后面显示的按钮。

如需了解如何设计消息，请参阅以下 Google Chat API 文档：

使用信息回复

Chat 应用可以通过消息响应以下任一触发器或互动：

  • 消息触发器，例如当用户向 Chat 应用发送 @mention 消息或私信时。
  • 添加到聊天室触发器，例如当用户从 Google Workspace Marketplace 安装 Chat 应用或将其添加到聊天室时。
  • 消息或对话框中卡片的按钮点击。例如，当用户输入信息并点击“提交”时。

否则，Chat 应用可以通过调用 Google Chat API 主动发送消息。

如需使用消息进行回复，请返回包含 CreateMessageAction 对象的操作 DataActions：

{ "hostAppDataAction": { "chatDataAction": { "createMessageAction": {
  "message": MESSAGE
}}}

将 MESSAGE 替换为 Chat API 中的 Message 资源。如需详细了解操作的运作方式，请参阅聊天操作。

在以下示例中，每当 Chat 应用被添加到聊天室时，都会创建并发送一条文本消息。如需在用户将您的 Chat 应用添加到聊天室时发送文本消息，您的 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 Workspace Add-on.
 * @param {Object} res The response object from the Chat app. An onboarding message that
 *                     introduces the app and helps people get started with it.
 */
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`.'
    }}}}});
  }
};

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. An onboarding message that
 *                  introduces the app and helps people get started with it.
 */
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 应用消息，请返回带有 UpdateMessageAction 的操作 DataActions，如以下示例所示：

{ "hostAppDataAction": { "chatDataAction": { "updateMessageAction": {
  "message": MESSAGE
}}}}

将 MESSAGE 替换为 Chat API 中的 Message 资源。

如需详细了解操作的运作方式，请参阅聊天操作。

Chat 扩展应用还可以更新用户发来的消息，以返回他们发送的链接的预览。有关详情，请参阅预览 Google Chat 消息中的链接。

使用 Google Chat API 回复互动或发送主动消息

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

  • 按计划发送消息，或发送有关外部资源更改的消息。例如，有关新问题或支持请求的通知。
  • 在互动后超过 30 秒才回复。例如，在完成长时间运行的任务后，使用消息进行响应。
  • 在发生互动聊天室之外发送消息。
  • 代表 Chat 用户发送消息。

如需使用 Chat API 发送消息，您必须设置身份验证，并对 Message 资源调用 create() 方法。如需了解相关步骤，请参阅使用 Google Chat API 发送消息。