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.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 实时投票活动的状态。此属性的有效值包括:
|
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 此值用于指明作者是否为实时聊天的管理员。 |