本頁面由 Cloud Translation API 翻譯而成。

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` 這個值表示作者是否為直播聊天的版主。