A superChatEvent
resource represents a Super Chat message purchased by a fan during a YouTube live stream. In the YouTube live chat stream, Super Chats stand out from other messages in two ways:
- Super Chats are highlighted with a color.
- Super Chats stay pinned in the ticker for a set period of time.
The color of the Super Chat, the period of time it stays pinned in the ticker, and the maximum message length are all determined by the purchase amount. See the YouTube Help Center to learn more about Super Chats.
Methods
The API supports the following methods for superChatEvents
resources:
- list
- List Super Chat events from a channel's live streams in the previous 30 days. Try it now.
Resource representation
The following JSON structure shows the format of a superChatEvent
resource:
{ "kind": "youtube#superChatEvent", "etag": etag, "id": string, "snippet": { "channelId": string, "supporterDetails": { "channelId": string, "channelUrl": string, "displayName": string, "profileImageUrl": string }, "commentText": string, "createdAt": datetime, "amountMicros": unsigned long, "currency": string, "displayString": string, "messageType": unsigned integer, "isSuperStickerEvent": boolean, "superStickerMetadata": { "stickerId": string, "altText": string, "language": string } } }
Properties
The following table defines the properties that appear in this resource:
Properties | |
---|---|
kind |
string Identifies the API resource's type. The value will be youtube#superChatEvent . |
etag |
etag The Etag of this resource. |
id |
string The ID that YouTube assigns to uniquely identify the Super Chat event. |
snippet |
object The snippet object contains basic details about the Super Chat event. |
snippet.channelId |
string The YouTube channel ID that identifies the channel that broadcast the live stream associated with the Super Chat event. |
snippet.supporterDetails |
object Details about the supporter's channel. |
snippet.supporterDetails.channelId |
string The supporter's YouTube channel ID. |
snippet.supporterDetails.channelUrl |
string The URL of the supporter's channel. |
snippet.supporterDetails.displayName |
string The display name of the supporter's channel. |
snippet.supporterDetails.profileImageUrl |
string The avatar URL for the supporter's channel. |
snippet.commentText |
string The text content of the supporter's comment. |
snippet.createdAt |
datetime The date and time when the Super Chat was purchased. The value is specified in ISO 8601 ( YYYY-MM-DDThh:mm:ss.sZ ) format. |
snippet.amountMicros |
unsigned long The purchase amount, in micros of the purchase currency. For example, if the purchase amount is one dollar, the snippet.amountMicros property value is 1000000 . |
snippet.currency |
string The currency in which the purchase was made. The value is an ISO 4217 currency code. |
snippet.displayString |
string A string, like $1.00 , that shows the purchase amount and currency. The display string is formatted based on the conventions for the language specified by the hl request parameter. By default, display strings are formatted as they would be in English. For example, by default, a string is formatted as $1.00 rather than $1,00 . |
snippet.messageType |
unsigned integer The tier for the paid message. Note that when a liveChatMessage resource identifies a Super Chat message, the snippet.superChatDetails.tier property contains this value.The tier is based on the amount of money spent to purchase the message. It also determines the color used to highlight the message in the live chat UI, the maximum message length, and the amount of time that the message is pinned the ticker. The Super Chat tiers are documented in the YouTube Help Center. (See the expandable section about Super Chat purchase details.) In that list, the tier with the lowest purchase amount is tier 1, the next lowest amount is tier 2, and so forth. |
snippet.isSuperStickerEvent |
boolean Indicates whether the resource is a Super Sticker, which is a particular type of Super Chat message that has an associated image. If this field's value is true , then the superStickerMetadata field will contain information that can be used to display the image. |
snippet.superStickerMetadata |
object Details about the Super Sticker. This object is only returned if the snippet.isSuperStickerEvent field's value is true . |
snippet.superStickerMetadata.stickerId |
string A unique ID that identifies the sticker image. Note that the image is only displayed as part of the Super Sticker message when users view the chat window on YouTube. However, the image URL is not available via the API. For reference only, you can find which Sticker IDs relate to which Super Stickers in this CSV file. |
snippet.superStickerMetadata.altText |
string A text string that describes the sticker. The snippet.superStickerMetadata.language field identifies the language of the text. When calling the superChatEvents.list method, set the hl parameter value to the desired language for the text. |
snippet.superStickerMetadata.language |
string The language of the snippet.superStickerMetadata.altText property value. If the Super Sticker also displays any text, that text is also in this language. |