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

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` 購買金額，以交易貨幣的百萬分之一表示。舉例來說，如果購買金額是 $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.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` 這個值會指出作者是否為聊天室的管理員。