SuperChatEvents

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.