LiveChatMessages

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

根據預設，系統會為現場直播啟用聊天室功能，並在現場直播活動期間使用。(活動結束後，該活動就無法再使用即時通訊功能)。

方法

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

list

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

插入

在聊天室中新增訊息。立即試用。

刪除

刪除即時通訊訊息。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
    },
    "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：使用者收到贈送的會籍。
snippet.liveChatId	string 此為專屬 ID，可明確識別與訊息相關聯的聊天室。與廣播相關聯的聊天室 ID 會在 liveBroadcast 資源的 snippet.liveChatId 屬性中傳回。
snippet.authorChannelId	string 撰寫訊息的使用者 ID。這個欄位只會填入下列訊息類型： 如果訊息類型為 textMessageEvent，這個值可識別撰寫訊息的使用者。 如果訊息類型為 fanFundingEvent，這個值可用於識別出該廣播節目的使用者。 如果訊息類型為 messageDeletedEvent，則屬性值可識別刪除訊息的管理員。 如果訊息類型為 newSponsorEvent，這個值可識別剛成為贊助商的使用者。 如果訊息類型為 memberMilestoneChatEvent，則屬性值可識別傳送訊息的成員。 如果訊息類型為 userBannedEvent，屬性值可識別停權使用者的管理員。 如果訊息類型為 membershipGiftingEvent，這個值可識別購買會籍贈禮的使用者。 如果訊息類型為 giftMembershipReceivedEvent，這個值可識別收到贈送會籍的使用者。
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 購買金額，以交易貨幣的百萬分之一表示。舉例來說，如果購買金額是一美元，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 購買金額，以交易貨幣的百萬分之一表示。舉例來說，如果購買金額是一美元，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.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 這個值會指出作者是否為聊天室的管理員。