מקור מידע מסוג liveChatMessage מייצג הודעה בצ'אט בשידור חי ב-YouTube. המשאב יכול להכיל פרטים על כמה סוגים של הודעות, כולל הודעת טקסט חדשה שפורסמה או אירוע של מימון על ידי מעריצים.
התכונה של הצ'אט בשידור חי מופעלת כברירת מחדל בשידורים חיים, והיא זמינה כל עוד האירוע בשידור חי פעיל. (אחרי שהאירוע מסתיים, אי אפשר יותר להשתמש בצ'אט בשידור חי לאירוע הזה).
Methods
ה-API תומך בשיטות הבאות למשאבי liveChatMessages:
- list
- מציג רשימה של הודעות בצ'אט בשידור חי בצ'אט ספציפי. כדאי לנסות עכשיו.
- streamList
- מפעיל חיבור לסטרימינג בשרת כדי לקבל הודעות בצ'אט בשידור חי לצ'אט ספציפי עם זמן אחזור קצר. כדאי לנסות עכשיו.
- insert
- הוספת הודעה או סקר לצ'אט בשידור חי. כדאי לנסות עכשיו.
- מעבר
- מעבר בין מצבים של הודעה בשידור חי. כדאי לנסות עכשיו.
- מחיקה
- מחיקת הודעה בצ'אט. הבקשה ל-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
},
"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
},
"giftDetails": {
"jewelsAmount": integer,
"giftName": string,
"giftUrl": string,
"giftDuration": object,
"seconds": integer,
"nanos": integer,
"hasVisualEffect": boolean,
"comboCount": integer,
"altText": string,
"language": 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 מקצה כדי לזהות את ההודעה באופן ייחודי. הערה: ב-giftEvents, אפשר להשתמש שוב באותו מזהה כדי לעדכן את מספר המתנות ברצף. |
snippet |
objectהאובייקט snippet מכיל פרטים בסיסיים על ההודעה בצ'אט. |
snippet.type |
stringסוג ההודעה. המאפיין הזה תמיד קיים, והערך שלו קובע אילו שדות קיימים במשאב. הערכים התקינים של המאפיין הזה הם:
|
snippet.liveChatId |
stringהמזהה שמזהה באופן ייחודי את הצ'אט בשידור חי שההודעה משויכת אליו. מזהה הצ'אט בשידור חי שמשויך לשידור מוחזר במאפיין snippet.liveChatId של המשאב liveBroadcast. |
snippet.authorChannelId |
stringהמזהה של המשתמש שכתב את ההודעה. השדה הזה מתמלא רק עבור סוגי ההודעות הבאים:
|
snippet.publishedAt |
datetimeהתאריך והשעה שבהם ההודעה פורסמה במקור. הערך מצוין בפורמט ISO 8601 ( YYYY-MM-DDThh:mm:ss.sZ). |
snippet.hasDisplayContent |
booleanמציין אם ההודעה כוללת תוכן שצריך להציג למשתמשים. |
snippet.displayMessage |
stringמכיל מחרוזת שמוצגת למשתמשים. השדה הזה לא קיים אם סוג ההודעה הוא chatEndedEvent או tombstone. |
snippet.fanFundingEventDetails |
objectהערה: האובייקט הזה ונכסי הילדים שלו יצאו משימוש. החל מ-28 בפברואר 2017, משאבי liveChatMessage לא יחזירו יותר פרטים על אירועי מימון על ידי מעריצים.האובייקט הזה מכיל פרטים על אירוע המימון. הוא מופיע רק אם סוג ההודעה הוא fanFundingEvent. |
snippet.fanFundingEventDetails.amountMicros |
unsigned longהערה: המאפיין הזה הוצא משימוש. סכום הקרן. |
snippet.fanFundingEventDetails.currency |
stringהערה: המאפיין הזה הוצא משימוש. המטבע שבו בוצעה הקרן. |
snippet.fanFundingEventDetails.amountDisplayString |
stringהערה: המאפיין הזה הוצא משימוש. מחרוזת שעברה עיבוד ומציגה למשתמש את סכום הכסף והמטבע. |
snippet.fanFundingEventDetails.userComment |
stringהערה: המאפיין הזה הוצא משימוש. התגובה שהמשתמש הוסיף לאירוע הזה של מימון מעריצים. |
snippet.textMessageDetails |
objectהאובייקט הזה מכיל פרטים על הודעת SMS. הוא מופיע רק אם סוג ההודעה הוא textMessageEvent. |
snippet.textMessageDetails.messageText |
stringההודעה של המשתמש. |
snippet.userBannedDetails |
objectהאובייקט הזה מכיל פרטים על משתמש שהוצא מהצ'אט. הוא גם מכיל פרטים על החסימה עצמה. אפשר לחסום משתמשים בצ'אט באופן קבוע או זמני. |
snippet.userBannedDetails.bannedUserDetails |
objectהאובייקט הזה מכיל מידע על המשתמש שהוחרם. |
snippet.userBannedDetails.bannedUserDetails.channelId |
stringמזהה הערוץ ב-YouTube של המשתמש שנחסם. |
snippet.userBannedDetails.bannedUserDetails.channelUrl |
stringכתובת ה-URL של ערוץ 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מזהה ייחודי של תמונת הסטיקר. חשוב לשים לב שהתמונה מוצגת כחלק מההודעה של הסופר סטיקר רק כשמשתמשים צופים בחלון הצ'אט ב-YouTube. עם זאת, כתובת ה-URL של התמונה לא זמינה באמצעות ה-API. לעיון בלבד, אתם יכולים למצוא בקובץ ה-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 מכיל את הערך הזה.הסיווג מבוסס על סכום הכסף שהוצא על רכישת ההודעה. הסכום גם קובע את הצבע שבו ההודעה תודגש בממשק המשתמש של הצ'אט בשידור חי, את אורך ההודעה המקסימלי ואת משך הזמן שבו ההודעה תוצמד לטיקר. שכבות הסופר צ'אט, שכוללות גם סופר סטיקרים, מתועדות במרכז העזרה של 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הסטטוס של אירוע הסקר בשידור חי. הערכים התקינים של המאפיין הזה הם:
|
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המזהה של המשתמש שרכש את החברות במועדון במתנה. ההגדרה הזו תואמת ל snippet.authorChannelId של ההודעה המשויכת למתנת החברות במועדון. |
snippet.giftMembershipReceivedDetails.associatedMembershipGiftingMessageId |
stringהמזהה של ההודעה על החברות במועדון במתנה שקשורה לחברות הזו. המזהה הזה תמיד יתייחס להודעה שה- type שלה הוא membershipGiftingEvent. |
snippet.giftDetails |
objectהאובייקט הזה מכיל פרטים על אירוע של מתנה. הוא מופיע רק אם message type הוא giftEvent. |
snippet.giftDetails.jewelsAmount |
integerמספר היהלומים שהצופים השתמשו בהם כדי לשלוח את המתנה. |
snippet.giftDetails.giftName |
stringשם המתנה. |
snippet.giftDetails.giftUrl |
stringכתובת ה-URL של נכס המתנה. |
snippet.giftDetails.giftDuration |
objectמשך הזמן שבו תוצג כתובת ה-URL של המתנה. |
snippet.giftDetails.giftDuration.seconds |
integerמספר השניות שבהן כתובת ה-URL של המתנה תוצג. |
snippet.giftDetails.giftDuration.nanos |
integerמספר הננו-שניות שבהן תוצג כתובת ה-URL של המתנה. |
snippet.giftDetails.hasVisualEffect |
booleanהאם המתנה כוללת אפקט חזותי. |
snippet.giftDetails.comboCount |
integerמספר המתנות בקומבו. אם המתנה לא חלק מקומבו, הערך הוא 0. |
snippet.giftDetails.altText |
stringמחרוזת טקסט שמתארת את המתנה. |
snippet.giftDetails.language |
stringהשפה של ערך המאפיין altText. |
authorDetails |
objectהאובייקט authorDetails מכיל פרטים נוספים על המשתמש שפרסם את ההודעה הזו. |
authorDetails.channelId |
stringמזהה ערוץ YouTube של המחבר. |
authorDetails.channelUrl |
stringכתובת ה-URL של ערוץ YouTube של היוצר. |
authorDetails.displayName |
stringהשם המוצג של ערוץ YouTube של היוצר. |
authorDetails.profileImageUrl |
stringכתובת ה-URL של האווטאר בערוץ YouTube של המחבר. |
authorDetails.isVerified |
booleanהערך הזה מציין אם הזהות של היוצר אומתה על ידי YouTube. |
authorDetails.isChatOwner |
booleanהערך הזה מציין אם המחבר הוא הבעלים של הצ'אט בשידור חי. |
authorDetails.isChatSponsor |
booleanהערך הזה מציין אם המחבר הוא ספונסר של הצ'אט בשידור חי. |
authorDetails.isChatModerator |
booleanהערך הזה מציין אם המחבר הוא מנהל תגובות בצ'אט בשידור חי. |