SuperChatEvents

superChatEvent 資源代表粉絲在 YouTube 直播期間購買的超級留言訊息。在 YouTube 直播聊天室中，超級留言有別於其他訊息，有下列兩種方式：

  • 超級留言會標上顏色。
  • 超級留言會在即時留言板中持續顯示一段時間。

超級留言的顏色、持續顯示的時間與訊息長度上限取決於購買金額。如要進一步瞭解超級留言，請造訪 YouTube 說明中心。

方法

這個 API 支援下列 superChatEvents 資源方法：

list
列出頻道過去 30 天內頻道的超級留言活動。 立即試用。

資源表示法

下列 JSON 結構顯示了 superChatEvent 資源的格式：

{
  "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
    }
  }
}

屬性

下表列出顯示在這項資源中的屬性：

屬性
kind string
識別 API 資源的類型。值為 youtube#superChatEvent。
etag etag
這項資源的 Etag。
id string
YouTube 指派給超級留言活動的專屬 ID。
snippet object
snippet 物件包含超級留言活動的基本詳細資料。
snippet.channelId string
YouTube 頻道 ID，可用於識別播送與超級留言活動相關直播的頻道。
snippet.supporterDetails object
有關支持者頻道的詳細資料。
snippet.supporterDetails.channelId string
支持者的 YouTube 頻道 ID。
snippet.supporterDetails.channelUrl string
支持者頻道的網址。
snippet.supporterDetails.displayName string
支持者頻道的顯示名稱。
snippet.supporterDetails.profileImageUrl string
支持者頻道的顯示圖片網址。
snippet.commentText string
支持者留言的文字內容。
snippet.createdAt datetime
使用者購買超級留言的日期和時間。這個值以 ISO 8601 (YYYY-MM-DDThh:mm:ss.sZ) 格式指定。
snippet.amountMicros unsigned long
購買金額，以交易貨幣的百萬分之一表示。舉例來說，如果購買金額是 $1 美元，snippet.amountMicros 屬性值就是 1000000。
snippet.currency string
交易所使用的貨幣。這個值是 ISO 4217 貨幣代碼。
snippet.displayString string
顯示購買金額和貨幣的字串，例如 $1.00。顯示字串的格式取決於 hl 要求參數指定的語言慣例。根據預設，顯示字串的格式為英文。例如，字串預設採用 $1.00 格式，而非 $1,00。
snippet.messageType unsigned integer
付費訊息的級別。請注意，如果 liveChatMessage 資源識別出超級留言訊息，snippet.superChatDetails.tier 屬性就會包含這個值。

層級是根據購買訊息的金額而定。也會決定聊天室 UI 中用來醒目顯示訊息的顏色、訊息長度上限，以及訊息置頂時間。

如要查看超級留言的等級，請造訪 YouTube 說明中心。(可展開有關超級留言購買詳情的可展開部分)。在這份清單中，購買金額最低的層級為第 1 層，次低者為第 2 級，依此類推。
snippet.isSuperStickerEvent boolean
表示資源是否為超級貼圖，這是含有相關圖片的特定超級留言訊息類型。如果這個欄位值為 true，則 superStickerMetadata 欄位會包含可用於顯示圖片的資訊。
snippet.superStickerMetadata object
超級貼圖的詳細資料。只有在 snippet.isSuperStickerEvent 欄位的值為 true 時，才會傳回這個物件。
snippet.superStickerMetadata.stickerId string
識別貼圖圖片的專屬 ID。請注意，當使用者在 YouTube 上查看聊天室視窗時，該圖片只會顯示在超級貼圖訊息中。不過，您無法透過 API 取得圖片網址。如有需要，您可以參閱這個 CSV 檔案，瞭解與超級貼圖相關的貼圖 ID。
snippet.superStickerMetadata.altText string
描述貼圖的文字字串。snippet.superStickerMetadata.language 欄位會識別文字的語言。呼叫 superChatEvents.list 方法時，將 hl 參數值設為文字的所需語言。
snippet.superStickerMetadata.language string
snippet.superStickerMetadata.altText 屬性值的語言。如果超級貼圖也顯示任何文字，則這些文字也會以這個語言顯示。