liveChatMessage
資源代表 YouTube 聊天室中的即時通訊訊息。資源中可能包含多種訊息的詳細資料,包括最新發布的簡訊或粉絲贊助活動。
根據預設,系統會為現場直播啟用聊天室功能,並在現場直播活動期間使用。(活動結束後,該活動就無法再使用即時通訊功能)。
方法
這個 API 支援下列 liveChatMessages
資源方法:
資源表示法
下列 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 訊息的類型。這個屬性一律會存在,其值會決定資源中顯示的欄位。 此屬性的有效值如下:
|
snippet.liveChatId |
string 此為專屬 ID,可明確識別與訊息相關聯的聊天室。與廣播相關聯的聊天室 ID 會在 liveBroadcast 資源的 snippet.liveChatId 屬性中傳回。 |
snippet.authorChannelId |
string 撰寫訊息的使用者 ID。這個欄位只會填入下列訊息類型:
|
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 即時意見調查活動的狀態。這個屬性的有效值如下:
|
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 這個值會指出作者是否為聊天室的管理員。 |