LiveChatMessages

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

直播功能預設為啟用，且在直播活動期間可供使用。(活動結束後，該活動的聊天室就會關閉)。

方法

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

list

列出特定聊天室的聊天室訊息。 立即試用。

插入

在聊天室中新增訊息或民意調查。立即試用。

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 物件包含 Chat 訊息的核心詳細資料。
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 資源將不再傳回粉絲贊助活動的詳細資料。 這個物件包含贊助活動的詳細資料。只有在訊息類型為 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 屬性包含這個值。 等級取決於購買訊息所花費的金額。這項設定也會決定在聊天室 UI 中用來醒目顯示訊息的顏色、訊息長度上限，以及訊息在資訊列中置頂的時間長度。 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 屬性包含這個值。 等級取決於購買訊息所花費的金額。這項設定也會決定在聊天室 UI 中用來醒目顯示訊息的顏色、訊息長度上限，以及訊息在資訊列中置頂的時間長度。 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 這個值表示作者是否為直播聊天的版主。