本页介绍如何以 Google Chat 应用的形式创建和发送私信。
私信是只有指定 Chat 用户才能看到的 Chat 应用消息。您可以在与多人的聊天室中使用私信,让他们可以与 Chat 应用进行私密互动。例如,您的 Chat 应用可以私密地发送消息以执行以下任一操作:
- 响应斜杠命令。例如,如果用户在聊天室中调用您的 Chat 应用的
/about
斜杠命令,您的 Chat 应用可以回复一条私信,说明您的 Chat 应用的用途以及如何使用它。 - 通知或发送仅与一位用户相关的信息。例如,通知用户已向其分配任务,或提醒他们完成该任务。
- 发送错误消息。例如,如果用户省略了斜杠命令所需的参数文本,Chat 应用可以发送私信来说明错误并帮助用户设置命令格式。
当 Chat 应用发送私信时,该消息会显示一个标签,告知用户只有自己才能看到该消息:
前提条件
Node.js
- 一个启用了并配置了 Google Chat API 的 Google Cloud 项目。如需了解相关步骤,请参阅构建 Google Chat 应用。
- 如需以不公开方式响应斜杠命令(为 Chat 应用配置的斜杠命令)。如需构建斜杠命令,请参阅响应斜杠命令。
- 如需使用
messages.create()
方法发送私信,您必须使用应用身份验证。
注意:本指南中的 Node.js 代码示例可作为 Google Cloud Functions 函数运行。
Python
- 一个启用了并配置了 Google Chat API 的 Google Cloud 项目。如需了解相关步骤,请参阅构建 Google Chat 应用。
- 如需以不公开方式响应斜杠命令(为 Chat 应用配置的斜杠命令)。如需构建斜杠命令,请参阅响应斜杠命令。
- 如需使用
messages.create()
方法发送私信,您必须使用应用身份验证。
注意:本指南中的 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
字段(该字段仅输出)。
如需更新私信,请参阅更新消息。 如需删除私信,请参阅删除消息。