LiveChatMessages

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

直播聊天功能默认针对直播启用，并且在直播活动有效期间可用。（活动结束后，该活动将不再支持实时聊天。）

方法

该 API 支持以下针对 liveChatMessages 资源的方法：

list

列出特定聊天中的实时聊天消息。 立即试用。

streamList

启用服务器流式传输连接，以低延迟接收特定聊天的实时聊天消息。 立即试用。

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 此值表示作者是否为实时聊天的版主。