liveChatMessage
资源表示 YouTube 实时聊天中的聊天消息。该资源可能包含有关多种类型消息的详细信息,包括新发布的短信或粉丝资助活动。
实时聊天功能默认为直播启用,在直播活动进行期间可用。(活动结束后,就无法再进行实时聊天)。
方法
对于 liveChatMessages
资源,该 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 消息的类型。此属性始终存在,并且其值决定了资源中存在哪些字段。 此属性的有效值包括:
|
snippet.liveChatId |
string 唯一标识与消息相关联的实时聊天的 ID。与直播关联的实时聊天 ID 会在 liveBroadcast 资源的 snippet.liveChatId 属性中返回。 |
snippet.authorChannelId |
string 撰写消息的用户的 ID。只有以下类型的消息时,系统才会填充此字段:
|
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.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 此值用于指明作者是否为实时聊天的管理员。 |