LiveChatMessages

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

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

方法

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

list

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

插入

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

删除

删除聊天消息。该 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.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 此值用于指明作者是否为实时聊天的管理员。