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,
          "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 資源不會再傳回粉絲贊助活動的詳細資料。 這個物件包含贊助活動的詳細資料。只有在訊息類型為 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 不能提供圖片網址。如要瞭解哪些貼圖 ID 與超級貼圖相關，請參閱這份 CSV 檔案。
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 這個值會指出作者是否為聊天室管理員。