向 Google Chat 用户发送私信

本页介绍如何以 Google Chat 应用的形式创建和发送私信。

私信是只有指定 Chat 用户才能看到的 Chat 应用消息。您可以在与多人的聊天室中使用私信，让他们可以与 Chat 应用进行私密互动。例如，您的 Chat 应用可以私密地发送消息以执行以下任一操作：

  • 响应斜杠命令。例如，如果用户在聊天室中调用您的 Chat 应用的 /about 斜杠命令，您的 Chat 应用可以回复一条私信，说明您的 Chat 应用的用途以及如何使用它。
  • 通知或发送仅与一位用户相关的信息。例如，通知用户已向其分配任务，或提醒他们完成该任务。
  • 发送错误消息。例如，如果用户省略了斜杠命令所需的参数文本，Chat 应用可以发送私信来说明错误并帮助用户设置命令格式。

当 Chat 应用发送私信时，该消息会显示一个标签，告知用户只有自己才能看到该消息：

Cymbal Labs Chat 应用的私信。该消息指出，Chat 应用由 Cymbal Labs 创建，并分享了一个指向文档的链接以及用于与支持团队联系的链接。
图 1：当 Chat 应用发送私信时，用户会看到一条带有 Only visible to you 标签的消息。

前提条件

Node.js

注意：本指南中的 Node.js 代码示例可作为 Google Cloud Functions 函数运行。

Python

注意：本指南中的 Python 代码示例使用 Python 3.10 作为 Google Cloud Functions 函数运行。

Apps 脚本

  • 一个 Chat 应用。如需构建 Chat 应用，请按照此quickstart操作。
  • 如需以不公开方式响应斜杠命令（为 Chat 应用配置的斜杠命令）。如需构建斜杠命令，请参阅响应斜杠命令。
  • 如需使用 messages.create() 方法发送私信，您必须使用应用身份验证。

发送私信

如需以 Chat 应用的形式私下发送消息，您可以在创建消息时在消息中指定 privateMessageViewer 字段。您可以像创建任何消息一样创建私信：响应用户互动，或对 Message 资源异步调用 Google Chat API 的 create() 方法。如需了解发送短信或卡片消息的步骤，请参阅发送消息。

以下示例展示了内容为 Hello private world! 的私密短信的 JSON：

{
    "text": "Hello private world!",
    "privateMessageViewer": "USER"
}

在此示例中，USER 表示可以查看消息的 Chat 用户，格式为 User 资源。如果要响应用户互动，您可以指定互动事件中的 User 对象。如需查看示例，请参阅以下部分：以私密方式响应斜杠命令。

否则，如需为私信指定查看者，您可以使用 User 资源的 name 字段：

{
    "text": "Hello private world!",
    "privateMessageViewer": {
      "name": "users/USER_ID"
    }
}

在此示例中，您使用 name 字段在 Google Chat 中指定查看者的 User 资源名称。将 USER_ID 替换为用户的唯一 ID，例如 12345678987654321 或 hao@cymbalgroup.com。

如需详细了解如何指定用户，请参阅识别并指定 Google Chat 用户。

以私密方式响应斜杠命令

以下代码展示了一个 Chat 应用示例，该应用通过私信响应斜杠命令。

Chat 应用会处理 MESSAGE 互动事件，并对 /help 斜杠命令进行回复，并发送一条私密短信来说明具体的使用方法：

Node.js 

/**
* Responds to a MESSAGE event in Google Chat.
*
* @param {!Object} req Request sent from Google Chat app
* @param {!Object} res Response to send back
*
* @return {!Object} respond to slash command
*/
exports.onMessage = function onMessage(req, res) {
  if (req.method === 'GET' || !req.body.message) {
    return res.send('Hello! This function is meant to be used in Google Chat app.');
  }

  const event = req.body;

  // Checks for the presence of event.message.slashCommand.
  // If the slash command is "/help", responds with a private text message.
  if (event.message.slashCommand) {
    switch (event.message.slashCommand.commandId) {
      case '1':  // /help
        return res.json({
          privateMessageViewer: event.user,
          text: 'This Chat app was created by Cymbal Labs. To get help with this app, <https://cymbalgroup.com/docs|see our documentation> or <https://cymbalgroup.com/support|contact our support team>.'
        });
    }
  }

  // If the Chat app doesn't detect a slash command, it responds
  // with a private text message
  return res.json({
    privateMessageViewer: event.user,
    text: 'Try a slash command.'
  });
};

Apps 脚本

/**
* Responds to a MESSAGE event in Google Chat.
*
* @param {Object} event the event object from Google Chat
*/
function onMessage(event) {
  if (event.message.slashCommand) {
    switch (event.message.slashCommand.commandId) {
      case 1: // Responds to /help
        return {
          "privateMessageViewer": event.user,
          "text": "This Chat app was created by Cymbal Labs. To get help with this app, <https://cymbalgroup.com/docs|see our documentation> or <https://cymbalgroup.com/support|contact our support team>."
        };
    }
  }
  else {
    return { "text": "Try a slash command.", "privateMessageViewer": event.user };
  }
}

Python 

from typing import Any, Mapping

import flask
import functions_framework

@functions_framework.http
def main(req: flask.Request) -> Mapping[str, Any]:
  """Responds to a MESSAGE event in Google Chat.

  Args:
      req (flask.Request): the event object from Chat API.

  Returns:
      Mapping[str, Any]: open a Dialog in response to a card's button click.
  """
  if req.method == 'GET':
    return 'Hello! This function must be called from Google Chat.'

  request = req.get_json(silent=True)

  # Checks for the presence of event.message.slashCommand.
  # If the slash command is "/help", responds with a private text message.
  if request.get('message', {}).get('slashCommand'):
    command_id = request.get('message', {}).get('slashCommand').get('commandId')
    if command_id == '1':  # /help
      return {
          'privateMessageViewer': request.get('user'),
          'text': (
              'This Chat app was created by Cymbal Labs. To get help with this'
              ' app, <https://cymbalgroup.com/docs|see our documentation> or'
              ' <https://cymbalgroup.com/support|contact our support team>.'
          ),
      }

  return {
      'privateMessageViewer': request.get('user'),
      'text': 'Try a slash command.',
  }

限制

如需发送私信，私信不得包含或使用以下内容：

  • 附件。
  • 配件操作。
  • 部分私密消息。例如，Chat 应用不能发送包含文字和卡片的消息，其中文字仅对一位用户可见，但卡片对聊天室中的所有人可见。
  • 用户身份验证。只有聊天应用可以发送私信，因此您的 Chat 应用无法以用户身份进行身份验证，因此无法发送私信。

更新或删除私信

如需更新或删除 Google Chat 消息，您必须调用 Chat API。您无法更改私信的查看者，也无法将私信设为公开。因此，当您更新私信时，必须在 API 调用中省略 privateMessageViewer 字段（该字段仅输出）。

如需更新私信，请参阅更新消息。 如需删除私信，请参阅删除消息。