本頁面由 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,
          "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` 這個值會指出作者是否為聊天室管理員。