LiveChatMessages

A 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
    },
    "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
    },
    "giftEventDetails": {
      "giftMetadata": {
        "jewelsAmount": integer,
        "giftName": string,
        "giftUrl": string,
        "giftDuration": object,
        "seconds": integer,
        "nanos": integer,
        "hasVisualEffect": boolean,
        "comboCount": integer,
        "altText": string,
        "language": 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。 注意：对于 giftEvents，可以重复使用同一 ID 来更新连击数。
snippet	object `snippet` 对象包含有关聊天消息的核心详细信息。
snippet.type	string 消息的类型。此属性始终存在，其值决定了资源中存在的字段。 此属性的有效值为： chatEndedEvent - 聊天已结束，此消息之后无法再插入任何消息。这种情况会在直播结束后不久自然发生。对于频道默认直播中的实时聊天，系统不会发送此类消息。 sponsorOnlyModeEndedEvent - 聊天不再处于仅限赞助者模式，这意味着非赞助者用户现在可以发送消息。此事件没有任何显示内容。 sponsorOnlyModeStartedEvent - 聊天已进入仅限赞助者模式，这意味着只有赞助者才能发送消息。此事件没有任何显示内容。 newSponsorEvent - 有新用户赞助了拥有实时聊天的频道。author 字段包含新赞助者的详细信息。 memberMilestoneChatEvent - 有用户发送了会员里程碑留言。 superChatEvent - 有用户购买了超级留言。 superStickerEvent - 有用户购买了超级贴纸。 textMessageEvent - 有用户发送了文本消息。 tombstone - 墓碑表示消息曾经存在，具有此 ID 和发布时间，但后来已被删除。它不是在删除消息时发送的，而是显示出来，以表明消息在删除之前的位置。在此类消息中，仅存在 snippet.liveChatId、snippet.type 和 snippet.publishedAt 字段。 userBannedEvent - 有用户被管理员禁用了。author 字段包含管理员的详细信息。 membershipGiftingEvent - 有用户为其他观看者购买了会员资格。 giftMembershipReceivedEvent - 有用户收到了赠送的会员资格。 pollDetails - 有用户创建了实时投票。 giftEvent - 有用户兑换了宝石以获取礼物。
snippet.liveChatId	string 用于唯一标识与消息关联的实时聊天的 ID。与直播关联的实时聊天 ID 会在 liveBroadcast 资源的 snippet.liveChatId 属性中返回。
snippet.authorChannelId	string 消息的作者的用户 ID。此字段仅针对以下消息类型填充： 如果消息类型为 textMessageEvent，则属性值标识编写消息的用户。 如果消息类型为 fanFundingEvent，则属性值标识赞助直播的用户。 如果消息类型为 newSponsorEvent，则属性值标识刚刚成为赞助者的用户。 如果消息类型为 memberMilestoneChatEvent，则属性值标识发送消息的会员。 如果消息类型为 userBannedEvent，则属性值标识禁用用户的管理员。 如果消息类型为 membershipGiftingEvent，则属性值标识购买会员资格赠送的用户。 如果消息类型为 giftMembershipReceivedEvent，则属性值标识收到赠送的会员资格的用户。 如果消息类型为 pollEvent，则属性值标识创建实时投票的用户。 如果消息类型为 giftEvent，则属性值标识发送礼物的用户。
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.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 禁令的类型。此属性的有效值为： permanent temporary
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。此 ID 与关联的会员资格赠送消息的 snippet.authorChannelId 匹配。
snippet.giftMembershipReceivedDetails.associatedMembershipGiftingMessageId	string 与此会员资格赠礼相关的会员赠送消息的 ID。此 ID 将始终引用 type 为 membershipGiftingEvent 的消息。
snippet.giftEventDetails	object 此对象包含有关礼物事件的详细信息。仅当 message type 为 giftEvent 时，此对象才会存在。
snippet.giftEventDetails.giftMetadata	object 有关礼物事件的详细信息。
snippet.giftEventDetails.giftMetadata.jewelsAmount	integer 兑换礼物所用的宝石数量。
snippet.giftEventDetails.giftMetadata.giftName	string 礼物的名称。
snippet.giftEventDetails.giftMetadata.giftUrl	string 礼物资源的网址。
snippet.giftEventDetails.giftMetadata.giftDuration	object 显示礼物网址的持续时间。
snippet.giftEventDetails.giftMetadata.giftDuration.seconds	integer 显示礼物网址的秒数。
snippet.giftEventDetails.giftMetadata.giftDuration.nanos	integer 显示礼物网址的纳秒数。
snippet.giftEventDetails.giftMetadata.hasVisualEffect	boolean 礼物是否具有视觉效果。
snippet.giftEventDetails.giftMetadata.comboCount	integer 礼物的连击数；如果不是连击，则为 0。
snippet.giftEventDetails.giftMetadata.altText	string 用于描述礼物的文本字符串。
snippet.giftEventDetails.giftMetadata.language	string altText 属性值的语言。
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 此值指明作者是否为实时聊天的管理员。