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 此值指示作者是否为实时聊天的管理员。