LiveChatMessages

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

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

方法

对于 liveChatMessages 资源，该 API 支持以下方法：

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,
          "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 - 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.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 此值用于指明作者是否为实时聊天管理员。