本指南介绍了如何使用 Google Chat API 的 Message 资源上的 create() 方法执行以下任一操作：
- 发送包含文本、卡片和互动式微件的消息。
- 向特定 Chat 用户私下发送消息。
- 发起或回复消息串。
- 为消息命名，以便您可以在其他 Chat API 请求中指定该消息。
消息大小上限（包括任何文本或卡片）为 32,000 字节。 如需发送超出此大小的消息，您的 Chat 应用必须改为发送多条消息。
除了调用 Chat API 创建消息之外，Chat 应用还可以创建和发送消息来回复用户互动，例如在用户将 Chat 应用添加到聊天室后发布欢迎消息。在响应互动时，Chat 应用可以使用其他类型的消息传递功能，包括互动式对话框和链接预览界面。如需回复用户，Chat 应用会同步返回消息，而无需调用 Chat API。如需了解如何发送消息来响应互动，请参阅接收和响应与 Google Chat 应用的互动。
Chat 如何显示和归因使用 Chat API 创建的消息
您可以使用应用身份验证和用户身份验证调用 create() 方法。Chat 会根据您使用的身份验证类型以不同的方式对消息发送者进行归因。
当您以 Chat 应用身份进行身份验证时，Chat 应用会发送消息。
App。当您以用户身份进行身份验证时，Chat 应用会代表用户发送消息。Chat 还会通过显示 Chat 应用的名称，将 Chat 应用归因于消息。
身份验证类型还决定了您可以在消息中包含哪些消息功能和界面。通过应用身份验证，Chat 应用可以发送包含富文本、卡片式界面和互动式 widget 的消息。通过用户身份验证，您可以发送短信或创建包含卡片的消息，如创建和更新互动式卡片中所述。
如需详细了解 Chat API 提供的消息功能，请参阅 Google Chat 消息概览。
本指南介绍了如何使用这两种身份验证类型通过 Chat API 发送消息。
前提条件
Node.js
- 可访问 Google Chat 的 Google Workspace 商务版或企业版账号。
- 设置环境：
- 创建 Google Cloud 项目。
- 配置 OAuth 权限请求页面。
- 启用并配置 Google Chat API，为您的 Chat 应用设置名称、图标和说明。
- 安装 Node.js Cloud 客户端库。
- 根据您希望在 Google Chat API 请求中进行身份验证的方式，创建访问凭据：
- 如需以 Chat 用户身份进行身份验证，请创建 OAuth 客户端 ID 凭证，并将凭证作为名为
credentials.json的 JSON 文件保存到本地目录。 - 如需以 Chat 应用身份进行身份验证，请创建服务账号凭证，并将凭证保存为名为
credentials.json的 JSON 文件。
- 如需以 Chat 用户身份进行身份验证，请创建 OAuth 客户端 ID 凭证，并将凭证作为名为
- 根据您是要以用户身份还是以 Chat 应用身份进行身份验证， 选择授权范围。
- Google Chat 聊天室，其中经过身份验证的用户或调用 Chat 应用是成员。如需以 Chat 应用身份进行身份验证，请将 Chat 应用添加到聊天室。
Python
- 可访问 Google Chat 的 Google Workspace 商务版或企业版账号。
- 设置环境：
- 创建 Google Cloud 项目。
- 配置 OAuth 权限请求页面。
- 启用并配置 Google Chat API，为您的 Chat 应用设置名称、图标和说明。
- 安装 Python Cloud 客户端库。
- 根据您希望在 Google Chat API 请求中进行身份验证的方式，创建访问凭据：
- 如需以 Chat 用户身份进行身份验证，请创建 OAuth 客户端 ID 凭证，并将凭证作为名为
credentials.json的 JSON 文件保存到本地目录。 - 如需以 Chat 应用身份进行身份验证，请创建服务账号凭证，并将凭证保存为名为
credentials.json的 JSON 文件。
- 如需以 Chat 用户身份进行身份验证，请创建 OAuth 客户端 ID 凭证，并将凭证作为名为
- 根据您是要以用户身份还是以 Chat 应用身份进行身份验证， 选择授权范围。
- Google Chat 聊天室，其中经过身份验证的用户或调用 Chat 应用是成员。如需以 Chat 应用身份进行身份验证，请将 Chat 应用添加到聊天室。
Java
- 可访问 Google Chat 的 Google Workspace 商务版或企业版账号。
- 设置环境：
- 创建 Google Cloud 项目。
- 配置 OAuth 权限请求页面。
- 启用并配置 Google Chat API，为您的 Chat 应用设置名称、图标和说明。
- 安装 Java Cloud 客户端库。
- 根据您希望在 Google Chat API 请求中进行身份验证的方式，创建访问凭据：
- 如需以 Chat 用户身份进行身份验证，请创建 OAuth 客户端 ID 凭证，并将凭证作为名为
credentials.json的 JSON 文件保存到本地目录。 - 如需以 Chat 应用身份进行身份验证，请创建服务账号凭证，并将凭证保存为名为
credentials.json的 JSON 文件。
- 如需以 Chat 用户身份进行身份验证，请创建 OAuth 客户端 ID 凭证，并将凭证作为名为
- 根据您是要以用户身份还是以 Chat 应用身份进行身份验证， 选择授权范围。
- Google Chat 聊天室，其中经过身份验证的用户或调用 Chat 应用是成员。如需以 Chat 应用身份进行身份验证，请将 Chat 应用添加到聊天室。
Apps 脚本
- 可访问 Google Chat 的 Google Workspace 商务版或企业版账号。
- 设置环境：
- 创建 Google Cloud 项目。
- 配置 OAuth 权限请求页面。
- 启用并配置 Google Chat API，为您的 Chat 应用设置名称、图标和说明。
- 创建独立的 Apps 脚本项目，并启用高级 Chat 服务。
- 在本指南中，您必须使用用户或应用身份验证。如需以 Chat 应用身份进行身份验证，请创建服务账号凭证。如需了解相关步骤，请参阅以 Google Chat 应用身份进行身份验证和授权。
- 根据您是要以用户身份还是以 Chat 应用身份进行身份验证， 选择授权范围。
- Google Chat 聊天室，其中经过身份验证的用户或调用 Chat 应用是成员。如需以 Chat 应用身份进行身份验证，请将 Chat 应用添加到聊天室。
以 Chat 应用身份发送消息
本部分介绍了如何使用应用身份验证发送包含文本、卡片和互动式配件 widget 的消息。
如需使用应用身份验证调用 CreateMessage() 方法，您必须在请求中指定以下字段：
chat.bot授权范围。- 您要在其中发布消息的
Space资源。Chat 应用必须是聊天室的成员。 - 要创建的
Message资源。如需定义消息内容，您可以添加富文本 (text)、一个或多个卡片界面 (cardsV2)，或同时添加这两者。
您还可以选择性地添加以下内容：
elements字段，用于向消息添加引用。accessoryWidgets字段，用于在消息底部添加互动按钮。privateMessageViewer字段，用于私下向指定用户发送消息。messageId字段，可让您为消息命名，以便在其他 API 请求中使用。thread.threadKey和messageReplyOption字段，用于发起或回复话题。如果聊天室不使用话题，则系统会忽略此字段。
以下代码展示了一个示例，说明 Chat 应用如何以 Chat 应用身份发布包含文本、卡片和可点击按钮的消息：
Node.js
Python
Java
Apps 脚本
如需运行此示例，请将 SPACE_NAME 替换为聊天室的 name 字段中的 ID。您可以通过调用 ListSpaces() 方法或从聊天室的网址中获取该 ID。
在消息底部添加互动式微件
在本指南的第一个代码示例中，Chat 应用消息在消息底部显示一个可点击的按钮，称为辅助 widget。辅助微件会显示在消息中的任何文本或卡片之后。您可以使用这些 widget 提示用户以多种方式与您的消息互动，包括：
- 对消息的准确性或满意度进行评分。
- 举报消息或 Chat 应用存在的问题。
- 打开指向相关内容（例如文档）的链接。
- 在特定时间段内忽略或暂停来自 Chat 应用的类似消息。
如需添加辅助 widget，请在请求正文中添加 accessoryWidgets[] 字段，并指定要添加的一个或多个 widget。
下图显示了一个 Chat 应用，该应用在短信中附加了辅助 widget，以便用户对 Chat 应用的使用体验进行评分。
以下示例展示了创建包含两个辅助按钮的短信的请求正文。当用户点击按钮时，相应的函数（例如 doUpvote）会处理互动：
{
text: "Rate your experience with this Chat app.",
accessoryWidgets: [{ buttonList: { buttons: [{
icon: { material_icon: {
name: "thumb_up"
}},
color: { red: 0, blue: 255, green: 0 },
onClick: { action: {
function: "doUpvote"
}}
}, {
icon: { material_icon: {
name: "thumb_down"
}},
color: { red: 0, blue: 255, green: 0 },
onClick: { action: {
function: "doDownvote"
}}
}]}}]
}
私下发送消息
Chat 应用可以私下发送消息，以便该消息仅对聊天室中的特定用户可见。当 Chat 应用发送私信时，消息会显示一个标签，通知用户该消息仅对他们可见。
如需使用 Chat API 私下发送消息，请在请求正文中指定 privateMessageViewer 字段。如需指定用户，请将值设置为表示 Chat 用户的 User 资源。您还可以使用 User 资源的 name 字段，如以下示例所示：
{
text: "Hello private world!",
privateMessageViewer: {
name: "users/USER_ID"
}
}
如需使用此示例，请将 USER_ID 替换为用户的唯一 ID，例如 12345678987654321 或 hao@cymbalgroup.com。如需详细了解如何指定用户，请参阅识别和指定 Google Chat 用户。
如需私下发送消息，您必须在请求中省略以下内容：
发送强制通知或静默消息
Chat 应用发送消息时，可以使用以下选项之一通知用户：
- 强制发送通知：Chat 始终会向收件人发送推送通知，无论其通知设置或“勿扰”(DND) 状态如何。在 Chat 中，该消息会触发收件人名单或首页列表中的加粗和置顶行为，并显示一个标志。
- 发送静默消息：Chat 会禁止向接收者发送推送通知。在 Chat 中，该消息不会在收件人的名单或首页列表中触发加粗或置顶行为，也不会显示标记。如果静音消息是对话中的最后一条消息，其内容不会显示在首页摘要中。
无论是强制消息还是静默消息，这些消息都包含一个视觉指示器，用于通知收件人特殊通知行为。
强制通知和静默消息仅适用于使用应用身份验证的 Chat 应用。
强制通知和静默消息具有以下限制：
- 外部用户：强制通知和静默消息不适用于聊天室中的外部用户（访客）。外部用户会根据自己的设置接收通知。
- 提及：静默消息不支持提及用户。如果您在静默消息中提及某人，系统会将其视为纯文本。
- 消息串：您无法使用静默消息发起或回复消息串。
- 聊天室类型：私信 (DM) 或由没有 Google Workspace 账号的用户拥有的聊天室不支持强制通知和静默消息。
- 电子邮件通知：静默消息不会触发电子邮件通知。 强制通知的消息只有在提及特定用户时才会触发邮件通知。
如需强制发送通知或发送静默消息，请在请求中添加 createMessageNotificationOptions 字段，并将 notificationType 设置为以下值之一：
| 值 | 行为 |
|---|---|
NOTIFICATION_TYPE_FORCE_NOTIFY |
强制发送通知。 |
NOTIFICATION_TYPE_SILENT |
静默发送消息。 |
以下示例展示了发送包含强制通知的消息的请求的 JSON 正文：
{
"text": "Critical update: the server is down!",
"createMessageNotificationOptions": {
"notificationType": "NOTIFICATION_TYPE_FORCE_NOTIFY"
}
}
代表用户发送短信
本部分介绍了如何使用用户身份验证代表用户发送消息。通过用户身份验证，您可以代表用户发送短信或创建包含卡片的消息。如需详细了解如何代表用户发送卡片，请参阅创建和更新互动式卡片。
如需使用用户身份验证调用 CreateMessage() 方法，您必须在请求中指定以下字段：
- 支持对此方法进行用户身份验证的授权范围。以下示例使用
chat.messages.create范围。 - 您要在其中发布消息的
Space资源。经过身份验证的用户必须是聊天室的成员。 - 要创建的
Message资源。如需定义消息的内容，您必须添加text字段。
您还可以选择性地添加以下内容：
createMessageNotificationOptions字段，用于强制发送通知或静默发送消息。messageId字段，可让您为消息命名，以便在其他 API 请求中使用。thread.threadKey和messageReplyOption字段，用于发起或回复话题。如果聊天室不使用话题，则系统会忽略此字段。
以下代码示例展示了 Chat 应用如何代表经过身份验证的用户在给定聊天室中发送短信：
Node.js
Python
Java
Apps 脚本
如需运行此示例，请将 SPACE_NAME 替换为聊天室的 name 字段中的 ID。您可以通过调用 ListSpaces() 方法或从聊天室的网址中获取该 ID。
发起或回复消息串
对于使用话题的聊天室，您可以指定新消息是发起话题还是回复现有话题。
默认情况下，您使用 Chat API 创建的消息会启动新话题。为了帮助您识别会话并在稍后回复，您可以在请求中指定会话键：
- 在请求正文中，指定
thread.threadKey字段。 - 指定查询参数
messageReplyOption，以确定在键已存在时会发生什么情况。
如需创建回复现有会话的消息，请执行以下操作：
以下代码示例展示了 Chat 应用如何代表经过身份验证的用户发送文本消息，以发起或回复由给定聊天室的键标识的给定会话：
Node.js
Python
Java
Apps 脚本
如需运行此示例，请替换以下内容：
THREAD_KEY：聊天室中现有的会话键，或者要创建新会话时，为会话指定一个唯一名称。SPACE_NAME：聊天室的name字段中的 ID。您可以通过调用ListSpaces()方法或从聊天室的网址中获取该 ID。
为消息命名
如需在未来的 API 调用中检索或指定消息，您可以通过在请求中设置 messageId 字段来为消息命名。通过为消息命名，您可以指定消息，而无需存储消息资源名称中系统分配的 ID（在 name 字段中表示）。
例如，如需使用 get() 方法检索消息，您可以使用资源名称指定要检索的消息。资源名称的格式为 spaces/{space}/messages/{message}，其中 {message} 表示系统分配的 ID 或您在创建消息时设置的自定义名称。
如需为消息命名，请在创建消息时在 messageId 字段中指定自定义 ID。messageId 字段用于设置 Message 资源的 clientAssignedMessageId 字段的值。
您只能在创建消息时为其命名。您无法为现有消息命名或修改其自定义 ID。自定义 ID 必须满足以下要求：
- 以
client-开头。例如，client-custom-name是有效的自定义 ID，但custom-name不是。 - 最多包含 63 个字符，且只能包含小写字母、数字和连字符。
- 在聊天室内是唯一的。Chat 应用无法为不同的消息使用相同的自定义 ID。
以下代码示例展示了 Chat 应用如何代表经过身份验证的用户向指定聊天室发送带有 ID 的短信：
Node.js
Python
Java
Apps 脚本
如需运行此示例，请替换以下内容：
SPACE_NAME：聊天室的name字段中的 ID。您可以通过调用ListSpaces()方法或从聊天室的网址中获取该 ID。MESSAGE-ID：以custom-开头的消息名称。必须与 Chat 应用在指定聊天室中创建的所有其他消息名称不同。
引用消息
您可以通过在请求中调用 CreateMessage()（rpc、rest）并设置 quotedMessageMetadata（rpc、rest）来引用其他消息。
您可以引用消息串或主聊天中的消息，但不能引用其他消息串中的消息。
以下代码展示了如何创建引用另一条消息的消息：
Node.js
import {createClientWithUserCredentials} from './authentication-utils.js';
const USER_AUTH_OAUTH_SCOPES = ['https://www.googleapis.com/auth/chat.messages.create'];
// This sample shows how to create a message that quotes another message.
async function main() {
// Create a client
const chatClient = await createClientWithUserCredentials(USER_AUTH_OAUTH_SCOPES);
// Initialize request argument(s)
const request = {
// TODO(developer): Replace SPACE_NAME .
parent: 'spaces/SPACE_NAME',
message: {
text: 'I am responding to a quoted message!',
// quotedMessageMetadata lets Chat apps respond to a message by quoting it.
quotedMessageMetadata: {
// TODO(developer): Replace QUOTED_MESSAGE_NAME
// and QUOTED_MESSAGE_LAST_UPDATE_TIME.
name: 'QUOTED_MESSAGE_NAME',
lastUpdateTime: 'QUOTED_MESSAGE_LAST_UPDATE_TIME'
}
}
};
// Make the request
const response = await chatClient.createMessage(request);
// Handle the response
console.log(response);
}
main().catch(console.error);
Python
from authentication_utils import create_client_with_user_credentials
from google.apps import chat_v1 as google_chat
from google.protobuf.timestamp_pb2 import Timestamp
SCOPES = ['https://www.googleapis.com/auth/chat.messages.create']
# This sample shows how to create a message that quotes another message.
def create_message_quote_message():
'''Creates a message that quotes another message.'''
# Create a client
client = create_client_with_user_credentials(SCOPES)
# Create a timestamp from the RFC-3339 string.
# TODO(developer): Replace QUOTED_MESSAGE_LAST_UPDATE_TIME.
last_update_time = Timestamp()
last_update_time.FromJsonString('QUOTED_MESSAGE_LAST_UPDATE_TIME')
# Initialize request argument(s)
request = google_chat.CreateMessageRequest(
# TODO(developer): Replace SPACE_NAME.
parent='spaces/SPACE_NAME',
# Create the message.
message = google_chat.Message(
text='I am responding to a quoted message!',
# quotedMessageMetadata lets Chat apps respond to a message by quoting it.
quoted_message_metadata=google_chat.QuotedMessageMetadata(
name='QUOTED_MESSAGE_NAME',
last_update_time=last_update_time
)
)
)
# Make the request
response = client.create_message(request)
# Handle the response
print(response)
create_message_quote_message()
Java
import com.google.chat.v1.ChatServiceClient;
import com.google.chat.v1.CreateMessageRequest;
import com.google.chat.v1.Message;
import com.google.chat.v1.QuotedMessageMetadata;
import com.google.protobuf.util.Timestamps;
import com.google.workspace.api.chat.samples.utils.AuthenticationUtils;
import java.text.ParseException;
// This sample shows how to create a message that quotes another message.
public class CreateMessageQuoteMessage {
public static void main(String[] args) throws Exception, ParseException {
// Create a client.
ChatServiceClient chatClient = AuthenticationUtils.createClientWithUserCredentials();
// Initialize request argument(s).
// TODO(developer): Replace SPACE_NAME, QUOTED_MESSAGE_NAME,
// and QUOTED_MESSAGE_LAST_UPDATE_TIME here.
String parent = "spaces/SPACE_NAME";
String quotedMessageName = "QUOTED_MESSAGE_NAME";
String lastUpdateTime = "QUOTED_MESSAGE_LAST_UPDATE_TIME";
QuotedMessageMetadata quotedMessageMetadata =
QuotedMessageMetadata.newBuilder()
.setName(quotedMessageName)
.setLastUpdateTime(Timestamps.parse(lastUpdateTime))
.build();
Message message = Message.newBuilder()
.setText("I am responding to a quoted message!")
.setQuotedMessageMetadata(quotedMessageMetadata)
.build();
CreateMessageRequest request =
CreateMessageRequest.newBuilder()
.setParent(parent)
.setMessage(message)
.build();
// Make the request.
Message response = chatClient.createMessage(request);
// Handle the response.
System.out.println(response);
}
}
Apps 脚本
/**
* Creates a message that quotes another message.
*
* Relies on the OAuth2 scope 'https://www.googleapis.com/auth/chat.messages.create'
* referenced in the manifest file (appsscript.json).
*/
function createMessageQuoteMessage() {
// Initialize request argument(s)
// TODO(developer): Replace SPACE_NAME here.
const parent = 'spaces/SPACE_NAME';
const message = {
// The text content of the message.
text: 'I am responding to a quoted message!',
// quotedMessageMetadata lets Chat apps respond to a message by quoting it.
//
// TODO(developer): Replace QUOTED_MESSAGE_NAME
// and QUOTED_MESSAGE_LAST_UPDATE_TIME .
quotedMessageMetadata: {
name: 'QUOTED_MESSAGE_NAME',
lastUpdateTime: 'QUOTED_MESSAGE_LAST_UPDATE_TIME',
}
};
// Make the request
const response = Chat.Spaces.Messages.create(message, parent);
// Handle the response
console.log(response);
}
如需运行此示例，请替换以下内容：
SPACE_NAME：聊天室的name字段中的 ID。您可以通过调用ListSpaces()（rpc、rest）方法或从聊天室的网址中获取该 ID。QUOTED_MESSAGE_NAME：要引用的消息的消息资源name（rpc、rest），格式为spaces/{space}/messages/{message}。QUOTED_MESSAGE_LAST_UPDATE_TIME：您要引用的消息的最后更新时间。如果消息从未修改过，则对应于createTime（rpc、rest）。如果消息已修改，则对应于lastUpdateTime（rpc、rest）。
问题排查
当 Google Chat 应用或卡片返回错误时，Chat 界面会显示一条消息，提示“出了点问题”。或“无法处理您的请求。”有时，Chat 界面不会显示任何出错提示，但 Chat 应用或卡片会产生意外结果；例如，卡片消息可能不会显示。
虽然 Chat 界面中可能不会显示出错提示，但如果为 Chat 应用启用了日志记录，则系统会提供描述性出错提示和日志数据，以帮助您修复错误。如需查看、调试和修复错误方面的帮助，请参阅排查和修复 Google Chat 错误。
相关主题
- 使用卡片制作工具为 Chat 应用设计和预览 JSON 卡片消息。
- 设置邮件格式。
- 获取有关消息的详细信息。
- 列出聊天室中的消息。
- 更新消息。
- 删除消息。
- 在 Google Chat 聊天消息中识别用户。
- 使用传入网络钩子向 Google Chat 发送消息。