LiveChatMessages

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

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

方法

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

list

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

insert

在实时聊天中添加消息。立即试用。

删除

删除聊天消息。该 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
    },
    "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 – 用户收到了会员资格赠礼。
snippet.liveChatId	string 唯一标识与消息相关联的实时聊天的 ID。与广播相关联的实时聊天 ID 会在 liveBroadcast 资源的 snippet.liveChatId 属性中返回。
snippet.authorChannelId	string 编写消息的用户的 ID。只有以下类型的消息才会填充此字段： 如果消息类型为 textMessageEvent，则属性值用于标识撰写消息的用户。 如果消息类型为 fanFundingEvent，则属性值会标识资助广播的用户。 如果消息类型为 messageDeletedEvent，则属性值会标识删除消息的管理员。 如果消息类型为 newSponsorEvent，则属性值会标识刚刚成为赞助者的用户。 如果消息类型为 memberMilestoneChatEvent，则属性值会标识发送消息的成员。 如果消息类型为 userBannedEvent，则属性值用于标识封禁用户的管理员。 如果消息类型为 membershipGiftingEvent，则属性值会标识进行了会员资格赠礼购买的用户。 如果消息类型为 giftMembershipReceivedEvent，则属性值会标识收到了会员资格赠礼的用户。
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 黑名单的类型。此属性的有效值包括： 永久 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.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 此值用于指明作者是否为实时聊天的管理员。