LiveChatMessages

liveChatMessage 資源代表 YouTube 直播聊天室中的聊天訊息。資源可包含多種訊息的詳細資料，包括新發布的訊息或粉絲贊助活動。

直播功能預設為啟用，且在直播活動期間提供使用。(活動結束後，該活動的即時通訊功能就會停用)。

方法

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

list
列出特定對話的聊天室訊息。 立即試用。
streamList
啟用伺服器串流連線，以低延遲接收特定聊天室的即時通訊訊息。 立即試用。
插入
在聊天室新增訊息或民調。立即試用。
transition
轉換即時訊息的狀態。 立即試用。
刪除
刪除即時通訊訊息。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
    },
    "pollDetails": {
      "metadata": {
        "options": {
          "optionText": string,
          "tally": string,
        },
        "questionText": string,
        "status": enum
      },
    },
    "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
訊息的類型。這項屬性一律會存在，其值會決定資源中顯示的欄位。

這項屬性的有效值如下：
  • chatEndedEvent - 即時通訊已結束，之後無法再插入訊息。直播結束後，系統會自動執行這項作業。如果是頻道預設的廣播，系統不會傳送這類訊息。
  • messageDeletedEvent – 訊息已由版主刪除。author 欄位包含版主詳細資料。這個活動沒有任何顯示內容。
  • sponsorOnlyModeEndedEvent - 聊天室不再處於贊助者專屬模式，因此非贊助者現在也能傳送訊息。這個活動沒有任何顯示內容。
  • sponsorOnlyModeStartedEvent - 聊天室已進入僅限贊助者模式，只有贊助者才能傳送訊息。這個活動沒有顯示內容。
  • newSponsorEvent – 新使用者贊助了擁有聊天室的頻道。author 欄位包含新贊助者的詳細資料。
  • memberMilestoneChatEvent：使用者已傳送會員里程碑訊息。
  • superChatEvent：使用者已購買超級留言。
  • superStickerEvent：使用者購買了超級貼圖。
  • textMessageEvent：使用者傳送了簡訊。
  • tombstone - 墓碑表示訊息曾存在於這個 ID 和發布時間，但後來已遭刪除。系統不會在刪除訊息時傳送這類訊息，而是顯示這類訊息，表示刪除前訊息所在的位置。這類訊息只會包含 snippet.liveChatId、snippet.type 和 snippet.publishedAt 欄位。
  • userBannedEvent：使用者遭到管理員停權。author 欄位包含版主詳細資料。
  • membershipGiftingEvent - 使用者為其他觀眾購買會籍。
  • giftMembershipReceivedEvent：使用者已收到贈送的會籍。
  • pollDetails - 使用者已建立即時意見調查。
snippet.liveChatId string
可專屬識別與訊息相關聯的即時通訊 ID。與廣播相關聯的即時通訊 ID 會在 liveBroadcast 資源的 snippet.liveChatId 屬性中傳回。
snippet.authorChannelId string
撰寫訊息的使用者 ID。這個欄位只會填入下列訊息類型：
  • 如果郵件類型為 textMessageEvent，屬性值會識別撰寫郵件的使用者。
  • 如果訊息類型為 fanFundingEvent，屬性值會識別資助廣播的使用者。
  • 如果郵件類型為 messageDeletedEvent，屬性值會指出刪除郵件的版主。
  • 如果訊息類型為 newSponsorEvent，屬性值會識別剛成為贊助者的使用者。
  • 如果郵件類型為 memberMilestoneChatEvent，屬性值會識別傳送郵件的成員。
  • 如果訊息類型為 userBannedEvent，屬性值會指出禁止使用者發言的版主。
  • 如果訊息類型為 membershipGiftingEvent，屬性值會識別購買會員禮物的使用者。
  • 如果訊息類型為 giftMembershipReceivedEvent，則屬性值會識別收到禮物會員方案的使用者。
  • 如果訊息類型為 pollEvent，屬性值會識別建立即時投票的使用者。
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 資源將不再傳回 Fan Funding 事件的詳細資料。

這個物件包含贊助活動的詳細資料。只有在訊息類型為 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
購買金額，以購買幣別的百萬分之一表示。舉例來說，如果購買金額為一美元，則 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
購買金額，以購買幣別的百萬分之一表示。舉例來說，如果購買金額為一美元，則 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.tally string
即時意見調查選項的票數。只有在頻道擁有者授權 API 要求時，才會顯示票數。
snippet.pollDetails.metadata.questionText string
即時意見調查問題的文字。
snippet.pollDetails.metadata.status enum
即時投票活動的狀態。這個屬性的有效值如下：
  • unknown
  • active
  • closed
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
這個值表示作者是否為即時通訊的版主。