Method: spaces.messages.create

在 Google Chat 聊天室中创建消息。如需查看示例,请参阅发送消息。

支持以下类型的身份验证:

  • 具有以下授权范围的应用身份验证:
    • https://www.googleapis.com/auth/chat.bot
  • 使用以下授权范围之一进行用户身份验证:
    • https://www.googleapis.com/auth/chat.messages.create
    • https://www.googleapis.com/auth/chat.messages
    • https://www.googleapis.com/auth/chat.import(仅限导入模式聊天室)

Chat 会根据您在请求中使用的身份验证类型,以不同的方式对消息发送者进行归因。

下图展示了当您使用应用身份验证时,Chat 如何对消息进行归因。Chat 会将 Chat 应用显示为消息发送者。消息内容可以包含文本 (text)、卡片 (cardsV2) 和辅助 widget (accessoryWidgets)。

消息已通过应用身份验证发送

下图展示了当您使用用户身份验证时,Chat 如何归因消息。Chat 会将用户显示为消息发送者,并通过显示 Chat 应用的名称来表明该应用是消息的来源。消息内容只能包含文本 (text)。

通过用户身份验证发送的消息

消息大小上限(包括消息内容)为 32,000 字节。

对于 Webhook 请求,响应不包含完整消息。除了请求中的信息之外,响应中仅填充了 name 和 thread.name 字段。

HTTP 请求

POST https://chat.googleapis.com/v1/{parent=spaces/*}/messages

网址采用 gRPC 转码语法。

路径参数

参数
parent

string

必需。要在其中创建消息的聊天室的资源名称。

格式:spaces/{space}

查询参数

参数
threadKey
(deprecated)

string

可选。已弃用:请改用 thread.thread_key。会话串的 ID。最多支持 4000 个字符。如需发起或添加到消息串,请创建消息并指定 threadKey 或 thread.name。如需查看用法示例,请参阅发起或回复消息串。

requestId

string

可选。此请求的唯一 ID。建议使用随机 UUID。指定请求 ID 可使请求具有幂等性,从而确保具有相同请求 ID 的多个相同请求只会导致创建一条消息。具有相同请求 ID 的后续请求会返回现有消息,而不会更新消息,即使请求的详细信息与当前状态不同也是如此。

如需有效使用此字段,请执行以下操作:

  • 确保后续请求与原始请求完全相同,并使用相同的身份验证凭证。
  • 如果已使用提供的请求 ID 创建了消息,则请求会返回该消息。请注意,返回的消息可能未完全填充;API 会回显请求中的消息,并填充系统分配的资源名称。如需检索消息的最新元数据,请调用 messages.get。
  • 如果对其他经过身份验证的用户重复使用现有请求 ID,则会导致错误。
messageReplyOption

enum (MessageReplyOption)

可选。指定消息是发起话题还是回复话题。仅在已命名的聊天室中受支持。

响应用户互动时,系统会忽略此字段。对于消息串中的互动,系统会在同一消息串中创建回复。否则,回复将作为新会话创建。

messageId

string

可选。消息的自定义 ID。让 Chat 应用无需在消息的资源名称(在消息 name 字段中表示)中存储系统分配的 ID,即可获取、更新或删除消息。

此字段的值必须满足以下要求:

  • 以 client- 开头。例如,client-custom-name 是有效的自定义 ID,但 custom-name 不是。
  • 最多包含 63 个字符,且只能包含小写字母、数字和连字符。
  • 在聊天室内是唯一的。Chat 应用无法为不同的消息使用相同的自定义 ID。

如需了解详情,请参阅为消息命名。

createMessageNotificationOptions

object (CreateMessageNotificationOptions)

可选。控制消息发布时的通知行为。如需了解详情,请参阅强制显示通知或发送静默消息。

请求正文

请求正文包含一个 Message 实例。

响应正文

如果成功,响应正文将包含一个新创建的 Message 实例。

授权范围

需要以下 OAuth 范围之一:

  • https://www.googleapis.com/auth/chat.bot
  • https://www.googleapis.com/auth/chat.import
  • https://www.googleapis.com/auth/chat.messages
  • https://www.googleapis.com/auth/chat.messages.create

如需了解详情,请参阅授权指南。

MessageReplyOption

指定如何回复消息。未来可能会添加更多状态。

枚举
MESSAGE_REPLY_OPTION_UNSPECIFIED 默认值。发起新对话串。使用此选项会忽略包含的所有 thread ID 或 threadKey。
REPLY_MESSAGE_FALLBACK_TO_NEW_THREAD 创建邮件作为对 thread ID 或 threadKey 指定会话的回复。如果失败,该消息会启动一个新消息串。
REPLY_MESSAGE_OR_FAIL 创建邮件作为对 thread ID 或 threadKey 指定会话的回复。如果使用新的 threadKey,则会创建一个新线程。如果消息创建失败,系统会返回 NOT_FOUND 错误。

CreateMessageNotificationOptions

消息发布时的通知行为选项。

JSON 表示法
{
  "notificationType": enum (NotificationType)
}
字段
notificationType

enum (NotificationType)

消息的通知类型。

NotificationType

消息的通知类型选项。

枚举
NOTIFICATION_TYPE_NONE 默认行为。通知行为与人类用户使用 Chat 界面发送消息时类似:系统不会向人类发送者发送通知。
NOTIFICATION_TYPE_INCLUDE_HUMAN_CREATOR

系统会向消息创建者用户(例如,其身份验证信息用于创建消息的用户)发送通知(推送通知、邮件通知等),并将消息标记为未读。

这不会覆盖聊天室的现有用户通知设置。例如,如果用户选择不接收某个聊天室的通知,那么即使设置了此选项,他们也不会收到通知。

需要用户身份验证。

NOTIFICATION_TYPE_FORCE_NOTIFY

强制通知收件人。这会绕过用户的聊天室通知设置和 Chat 勿扰设置。此选项不会绕过设备级“勿扰”设置。

需要应用身份验证。

NOTIFICATION_TYPE_SILENT

不通知收件人,也不将邮件标记为未读。这与用户将对话静音或启用 Chat 勿扰类似。

需要应用身份验证。