此页面由 Cloud Translation API 翻译。

LiveChatMessages

liveChatMessage 资源表示 YouTube 实时聊天中的聊天消息。该资源可以包含有关多种类型消息的详细信息，包括新发布的短信或粉丝赞助活动。

直播聊天功能默认为直播启用，并在直播活动期间可用。（活动结束后，该活动将无法再使用实时聊天功能。）

方法

该 API 支持对 liveChatMessages 资源使用以下方法：

list: 列出特定聊天的实时聊天消息。立即试用。
insert: 向实时聊天添加消息或投票。立即试用。
transition: 转换实时消息的状态。立即试用。
delete: 删除聊天消息。API 请求必须由频道所有者或实时聊天室管理员授权。立即试用。

资源表示法

以下 JSON 结构显示了 liveChatMessages 资源的格式：

{
  "kind": "youtube#liveChatMessage",
  "etag": etag,
  "id": string,
  "snippet": {
    "type": string,
    "liveChatId": string,
    "authorChannelId": string,
    "publishedAt": datetime,
    "hasDisplayContent": boolean,
    "displayMessage": string,
    "fanFundingEventDetails": {
      "amountMicros": unsigned long,
      "currency": string,
      "amountDisplayString": string,
      "userComment": string
    },
    "textMessageDetails": {
      "messageText": string
    },
    "messageDeletedDetails": {
      "deletedMessageId": string
    },
    "userBannedDetails": {
      "bannedUserDetails": {
        "channelId": string,
        "channelUrl": string,
        "displayName": string,
        "profileImageUrl": string
      },
      "banType": string,
      "banDurationSeconds": unsigned long
    },
    "memberMilestoneChatDetails": {
      "userComment": string,
      "memberMonth": unsigned integer,
      "memberLevelName": string
    },
    "newSponsorDetails": {
      "memberLevelName": string,
      "isUpgrade": bool
    },
    "superChatDetails": {
      "amountMicros": unsigned long,
      "currency": string,
      "amountDisplayString": string,
      "userComment": string,
      "tier": unsigned integer
    },
    "superStickerDetails": {
      "superStickerMetadata": {
        "stickerId": string,
        "altText": string,
        "language": string
      },
      "amountMicros": unsigned long,
      "currency": string,
      "amountDisplayString": string,
      "tier": unsigned integer
    },
    "pollDetails": {
      "metadata": {
        "options": {
          "optionText": string,
          "tally": string,
        },
        "questionText": string,
        "status": enum
      },
    },
    "membershipGiftingDetails": {
      "giftMembershipsCount": integer,
      "giftMembershipsLevelName": string
    },
    "giftMembershipReceivedDetails": {
      "memberLevelName": string,
      "gifterChannelId": string,
      "associatedMembershipGiftingMessageId": string
    },
  },
  "authorDetails": {
    "channelId": string,
    "channelUrl": string,
    "displayName": string,
    "profileImageUrl": string,
    "isVerified": boolean,
    "isChatOwner": boolean,
    "isChatSponsor": boolean,
    "isChatModerator": boolean
  },
}

属性

下表定义了此资源中显示的属性：

属性
`kind`	`string` 用于标识 API 资源的类型。该值将为 `youtube#liveChatMessage`。
`etag`	`etag` 此资源的 ETag。
`id`	`string` 由 YouTube 分配的 ID，用于唯一标识消息。
`snippet`	`object` `snippet` 对象包含有关聊天消息的核心详细信息。
`snippet.type`	`string` 消息的类型。此属性始终存在，其值决定了资源中存在哪些字段。此属性的有效值如下： `chatEndedEvent` - 聊天已结束，无法再在此消息后插入其他消息。在直播结束后不久，这种情况就会自然发生。系统不会针对频道的默认直播发送此类消息。 `messageDeletedEvent` - 消息已被管理员删除。`author` 字段包含管理员的详细信息。此活动没有任何显示内容。 `sponsorOnlyModeEndedEvent` - 聊天不再处于赞助者专享模式，这意味着非赞助者用户现在可以发送消息。此活动没有任何显示内容。 `sponsorOnlyModeStartedEvent` - 聊天已进入赞助者专享模式，这意味着只有赞助者可以发送消息。此活动没有显示内容。 `newSponsorEvent` - 有新用户赞助了拥有实时聊天的频道。`author` 字段包含新赞助商的详细信息。 `memberMilestoneChatEvent` - 用户发送了会员里程碑留言。 `superChatEvent` - 用户购买了超级留言。 `superStickerEvent` - 用户购买了超级贴纸。 `textMessageEvent` - 用户发送了短信。 `tombstone` - 墓碑表示消息曾经存在，具有此 ID 和发布时间，但已被删除。系统不会在删除消息时发送此消息，而是会显示此消息来指明消息在被删除之前的位置。此类消息中只有 `snippet.liveChatId`、`snippet.type` 和 `snippet.publishedAt` 字段。 `userBannedEvent` - 用户已被管理员禁用。`author` 字段包含管理员的详细信息。 `membershipGiftingEvent` - 用户为其他观看者购买了会员资格。 `giftMembershipReceivedEvent` - 用户收到了会员资格赠礼。 `pollDetails` - 用户创建了实时投票活动。
`snippet.liveChatId`	`string` 用于唯一标识与消息关联的实时聊天会话的 ID。与直播关联的实时聊天 ID 会在 `liveBroadcast` 资源的 `snippet.liveChatId` 属性中返回。
`snippet.authorChannelId`	`string` 创建消息的用户的 ID。只有以下消息类型才会填充此字段：如果消息类型为 `textMessageEvent`，则属性值用于标识撰写消息的用户。如果消息类型为 `fanFundingEvent`，则该属性值用于标识资助了直播的用户。如果消息类型为 `messageDeletedEvent`，则该属性值用于标识删除了消息的管理员。如果消息类型为 `newSponsorEvent`，则该属性值用于标识刚刚成为赞助商的用户。如果消息类型为 `memberMilestoneChatEvent`，则该属性值用于标识发送消息的成员。如果消息类型为 `userBannedEvent`，则该属性值用于标识禁止用户的管理员。如果消息类型为 `membershipGiftingEvent`，则该属性值用于标识购买会员赠礼的用户。如果消息类型为 `giftMembershipReceivedEvent`，则该属性值用于标识收到会员资格赠礼的用户。如果消息类型为 `pollEvent`，则属性值用于标识创建了实时投票的用户。
`snippet.publishedAt`	`datetime` 消息最初发布的日期和时间。该值采用 ISO 8601 (`YYYY-MM-DDThh:mm:ss.sZ`) 格式指定。
`snippet.hasDisplayContent`	`boolean` 指明消息是否包含应向用户显示的显示内容。
`snippet.displayMessage`	`string` 包含要向用户显示的字符串。如果消息类型为 `chatEndedEvent` 或 `tombstone`，则此字段不存在。
`snippet.fanFundingEventDetails`	`object` 注意：此对象及其子属性已废弃。自 2017 年 2 月 28 日起，`liveChatMessage` 资源将不再返回粉丝赞助活动的详细信息。此对象包含有关赞助活动的详细信息。只有当消息类型为 `fanFundingEvent` 时，此字段才会存在。
`snippet.fanFundingEventDetails.amountMicros`	`unsigned long` 注意：此属性已废弃。基金金额。
`snippet.fanFundingEventDetails.currency`	`string` 注意：此属性已废弃。资金的币种。
`snippet.fanFundingEventDetails.amountDisplayString`	`string` 注意：此属性已废弃。一个呈现的字符串，用于向用户显示资金金额和币种。
`snippet.fanFundingEventDetails.userComment`	`string` 注意：此属性已废弃。用户对此粉丝赞助活动添加的评论。
`snippet.textMessageDetails`	`object` 此对象包含有关短信的详细信息。只有当消息类型为 `textMessageEvent` 时，此字段才会存在。
`snippet.textMessageDetails.messageText`	`string` 用户的消息。
`snippet.messageDeletedDetails`	`object` 此对象包含聊天管理员或直播频道所有者删除的消息的详细信息。只有当消息类型为 `messageDeletedEvent` 时，此字段才会存在。
`snippet.messageDeletedDetails.deletedMessageId`	`string` 唯一标识已删除消息的 ID。此值与原始文本消息的 `id` 属性值相同。例如，如果 `textMessageEvent` 的 `id` 属性值为 `123`，并且该消息随后被删除，则该消息的 `snippet.messageDeletedDetails.deletedMessageId` 值将为 `123`。如果您在检索聊天消息后将其缓存，请使用此属性的值来识别不应再显示的消息。
`snippet.userBannedDetails`	`object` 此对象包含被禁止参与聊天的用户的详细信息。其中还包含有关禁播本身的详细信息。您可以永久或暂时禁止用户参与聊天。
`snippet.userBannedDetails.bannedUserDetails`	`object` 此对象包含被禁用户的相关信息。
`snippet.userBannedDetails.bannedUserDetails.channelId`	`string` 被禁用户的 YouTube 频道 ID。
`snippet.userBannedDetails.bannedUserDetails.channelUrl`	`string` 被禁用户的 YouTube 频道的网址。
`snippet.userBannedDetails.bannedUserDetails.displayName`	`string` 被禁用户的 YouTube 频道的显示名称。
`snippet.userBannedDetails.bannedUserDetails.profileImageUrl`	`string` 被禁用户的 YouTube 频道的头像。
`snippet.userBannedDetails.banType`	`string` 禁播类型。此属性的有效值如下：永久临时
`snippet.userBannedDetails.banDurationSeconds`	`unsigned long` 禁播时长。只有当 `snippet.userBannedDetails.banType` 属性值为 `temporary` 时，此属性才会存在。
`snippet.memberMilestoneChatDetails`	`object` 此对象包含有关会员里程碑事件的详细信息。只有当消息类型为 `memberMilestoneChatEvent` 时，此字段才会存在。
`snippet.memberMilestoneChatDetails.userComment`	`string` 会员在此会员里程碑聊天中添加的评论。如果成员未对消息添加评论，此字段为空。
`snippet.memberMilestoneChatDetails.memberMonth`	`unsigned integer` 观看者获得此会员里程碑留言的会员资格所对应的总月数（向上取整）。此时长与向 YouTube 用户显示的时长相同。
`snippet.memberMilestoneChatDetails.memberLevelName`	`string` 观看者所属的等级的名称。级别名称由提供会员服务的 YouTube 频道定义。在某些情况下，此字段不会填充。
`snippet.newSponsorDetails`	`object` 此对象包含有关“新会员公告”事件的详细信息。只有在类型为 `newSponsorEvent` 时，才会设置此字段。“会员”是指“赞助商”。
`snippet.newSponsorDetails.memberLevelName`	`string` 观看者所属的等级的名称。级别名称由提供会员服务的 YouTube 频道定义。在某些情况下，此字段不会填充。
`snippet.newSponsorDetails.isUpgrade`	`bool` 表示观看者是否刚刚从较低级别升级。对于购买时不是会员的观看者，此字段的值为 `false`。
`snippet.superChatDetails`	`object` 此对象包含有关超级留言事件的详细信息。只有当消息类型为 `superChatEvent` 时，此字段才会存在。
`snippet.superChatDetails.amountMicros`	`unsigned long` 购买金额，以购买币种的微单位表示。例如，如果购买金额为 1 美元，则 `snippet.amountMicros` 属性值为 `1000000`。
`snippet.superChatDetails.currency`	`string` 购买交易时所用的币种。值为 ISO 4217 货币代码。
`snippet.superChatDetails.amountDisplayString`	`string` 一个字符串（例如 `$1.00`），其中包含购买金额和币种。该字符串旨在向用户显示。
`snippet.superChatDetails.userComment`	`string` 用户对此超级留言活动添加的评论。
`snippet.superChatDetails.tier`	`unsigned integer` 付费消息的层级。请注意，在 `superChatEvent` 资源中，`snippet.messageType` 属性包含此值。层级取决于购买消息所花费的金额。它还决定了在实时聊天界面中突出显示消息时所用的颜色、消息的最大长度，以及消息在信息流中置顶的时间。 YouTube 帮助中心中记录了超级留言层级。（请参阅有关超级留言购买详情的可展开部分。）在该列表中，购买金额最低的层级为第 1 层级，金额次低的层级为第 2 层级，以此类推。
`snippet.superStickerDetails`	`object` 此对象包含有关超级贴纸事件的详细信息。只有当消息类型为 `superStickerEvent` 时，此字段才会存在。
`snippet.superStickerDetails.superStickerMetadata`	`object` 超级贴纸的详细信息。
`snippet.superStickerDetails.superStickerMetadata.stickerId`	`string` 用于标识贴纸图片的唯一 ID。请注意，只有当用户在 YouTube 上查看聊天窗口时，系统才会在超级贴纸消息中显示图片。不过，无法使用该 API 获取图片网址。您可以在此 CSV 文件中查看哪些贴纸 ID 与哪些超级贴纸相关（仅供参考）。
`snippet.superStickerDetails.superStickerMetadata.altText`	`string` 用于描述贴纸的文本字符串。`snippet.superStickerDetails.superStickerMetadata.language` 字段用于标识文本的语言。调用 `liveChatMessages.list` 方法时，将 hl 参数值设置为所选文本的语言。
`snippet.superStickerDetails.superStickerMetadata.language`	`string` `snippet.superStickerDetails.superStickerMetadata.altText` 属性值的语言。
`snippet.superStickerDetails.amountMicros`	`unsigned long` 购买金额，以购买币种的微单位表示。例如，如果购买金额为 1 美元，则 `snippet.amountMicros` 属性值为 `1000000`。
`snippet.superStickerDetails.currency`	`string` 购买交易时所用的币种。值为 ISO 4217 货币代码。
`snippet.superStickerDetails.amountDisplayString`	`string` 一个字符串（例如 `$1.00`），其中包含购买金额和币种。该字符串旨在向用户显示。
`snippet.superStickerDetails.tier`	`unsigned integer` 付费消息的层级。请注意，在 `superChatEvent` 资源中，`snippet.messageType` 属性包含此值。层级取决于购买消息所花费的金额。它还决定了在实时聊天界面中突出显示消息时所用的颜色、消息的最大长度，以及消息在信息流中置顶显示的时长。 YouTube 帮助中心中记录了超级留言层级（也适用于超级贴纸）。（请参阅有关超级留言购买详情的可展开部分。）在该列表中，购买金额最低的层级为第 1 层级，金额次低的层级为第 2 层级，以此类推。
`snippet.pollDetails`	`object` 此对象包含有关投票活动的详细信息。只有当消息类型为 `pollEvent` 时，此字段才会存在。
`snippet.pollDetails.metadata`	`object` 有关投票事件的详细信息。
`snippet.pollDetails.metadata.options`	`object` 实时投票中的选项。
`snippet.pollDetails.metadata.options.optionText`	`string` 实时投票选项的文本。
`snippet.pollDetails.metadata.options.tally`	`string` 实时投票选项的统计结果。只有在频道所有者授权 API 请求的情况下，才会显示统计信息。
`snippet.pollDetails.metadata.questionText`	`string` 实时投票问题的文本。
`snippet.pollDetails.metadata.status`	`enum` 实时投票活动的状态。此属性的有效值如下： `unknown` `active` `closed`
`snippet.membershipGiftingDetails`	`object` 此对象包含有关会员赠礼活动的详细信息。仅当 `message type` 为 `membershipGiftingEvent` 时才会存在。
`snippet.membershipGiftingDetails.giftMembershipsCount`	`integer` 用户购买的会员礼品数量。
`snippet.membershipGiftingDetails.giftMembershipsLevelName`	`string` 用户购买的会员礼品等级的名称。级别名称由提供会员服务的 YouTube 频道定义。在某些情况下，此字段不会填充。
`snippet.giftMembershipReceivedDetails`	`object` 此对象包含有关“收到会员资格赠礼”事件的详细信息。仅当 `message type` 为 `giftMembershipReceivedEvent` 时才会存在。
`snippet.giftMembershipReceivedDetails.memberLevelName`	`string` 观看者所属的等级的名称。此值与关联的会员赠送消息的 `snippet.membershipGiftingDetails.giftMembershipsLevelName` 相匹配。级别名称由提供会员服务的 YouTube 频道定义。在某些情况下，此字段不会填充。
`snippet.giftMembershipReceivedDetails.gifterChannelId`	`string` 购买会员赠礼的用户的 ID。此值与关联的会员赠送消息的 `snippet.authorChannelId` 相匹配。
`snippet.giftMembershipReceivedDetails.associatedMembershipGiftingMessageId`	`string` 与此会员赠礼相关的会员赠礼消息的 ID。此 ID 始终会引用 `type` 为 `membershipGiftingEvent` 的消息。
`authorDetails`	`object` `authorDetails` 对象包含与发布此消息的用户相关的其他详细信息。
`authorDetails.channelId`	`string` 作者的 YouTube 频道 ID。
`authorDetails.channelUrl`	`string` 作者的 YouTube 频道的网址。
`authorDetails.displayName`	`string` 作者 YouTube 频道的显示名称。
`authorDetails.profileImageUrl`	`string` 作者 YouTube 频道的头像网址。
`authorDetails.isVerified`	`boolean` 此值表示 YouTube 是否已验证作者的身份。
`authorDetails.isChatOwner`	`boolean` 此值指示作者是否为实时聊天对话的所有者。
`authorDetails.isChatSponsor`	`boolean` 此值指示作者是否为实时聊天的赞助商。
`authorDetails.isChatModerator`	`boolean` 此值指示作者是否为实时聊天的管理员。