LiveChatMessages

משאב liveChatMessage מייצג הודעת צ'אט בצ'אט בשידור חי ב-YouTube. המשאב יכול להכיל פרטים על כמה סוגים של הודעות, כולל הודעות טקסט שפורסמו לאחרונה או אירוע של מימון על ידי מעריצים.

התכונה 'צ'אט בשידור חי' מופעלת כברירת מחדל בשידורים חיים, והיא זמינה כל עוד האירוע בשידור חי פעיל. (אחרי סיום האירוע, הצ'אט בשידור חי לא יהיה זמין יותר באותו אירוע).

Methods

ה-API תומך בשיטות הבאות למשאבי liveChatMessages:

list
הצגת הודעות בצ'אט בשידור חי של צ'אט ספציפי. כדאי לנסות עכשיו.
insert
הוספת הודעה או סקר לצ'אט בשידור חי. כדאי לנסות עכשיו.
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 מקצה כדי לזהות את ההודעה באופן ייחודי.
snippet object
האובייקט snippet מכיל פרטים מרכזיים על הודעת הצ'אט.
snippet.type string
סוג ההודעה. המאפיין הזה תמיד קיים, והערך שלו קובע אילו שדות יהיו נוכחים במשאב.

הערכים החוקיים למאפיין הזה הם:
  • chatEndedEvent – הצ'אט הסתיים ואי אפשר להוסיף הודעות אחרי ההודעה הזו. זה יקרה באופן טבעי זמן מה אחרי סיום השידור. הודעות מהסוג הזה לא נשלחות לצ'אטים בשידור חי בשידור ברירת המחדל של הערוץ.
  • messageDeletedEvent – הודעה נמחקה על ידי מנהל/ת. השדה author מכיל את הפרטים של מנהל התגובות. לאירוע הזה אין תוכן להצגה.
  • sponsorOnlyModeEndedEvent – הצ'אט כבר לא במצב 'לתורמים בלבד', כלומר משתמשים שאינם תורמים יכולים לשלוח הודעות. לאירוע הזה אין תוכן להצגה.
  • sponsorOnlyModeStartedEvent – הצ'אט עבר למצב 'נותני חסות בלבד', כלומר רק נותני חסות יכולים לשלוח הודעות. לאירוע הזה אין תוכן להצגה.
  • newSponsorEvent – משתמש חדש חסם את הערוץ שבבעלותו הצ'אט בשידור חי. השדות author מכילים את פרטי המפרסם החדש.
  • memberMilestoneChatEvent – משתמש שלח הודעת צ'אט לחברי מועדון שהגיעו לציון דרך.
  • superChatEvent – משתמש רכש סופר צ'אט.
  • superStickerEvent – משתמש קנה Super Sticker.
  • textMessageEvent – משתמש שלח הודעת טקסט.
  • tombstone – סטטוס 'מצבת זיכרון' מציין שהודעה הייתה קיימת בעבר עם המזהה הזה ושעת הפרסום הזו, אבל היא נמחקה מאז. הוא לא נשלח כשמוחקים הודעה, אלא מוצג כדי לציין את המיקום שבו ההודעה הייתה לפני המחיקה. רק השדות snippet.liveChatId,‏ snippet.type ו-snippet.publishedAt נמצאים בהודעות מהסוג הזה.
  • userBannedEvent – משתמש הושעה על ידי מנהל. השדה author מכיל את הפרטים של מנהל התגובות.
  • membershipGiftingEvent – משתמש רכש חברות במועדון בשביל צופים אחרים.
  • giftMembershipReceivedEvent – משתמש קיבל חברות במועדון במתנה.
  • pollDetails – משתמש יצר סקר בשידור חי.
snippet.liveChatId string
המזהה הייחודי של הצ'אט בשידור חי שאליו משויכת ההודעה. מזהה הצ'אט בשידור חי שמשויך לשידור מוחזר במאפיין snippet.liveChatId של המשאב liveBroadcast.
snippet.authorChannelId string
המזהה של המשתמש שכתב את ההודעה. השדה הזה מתמלא רק בסוגי ההודעות הבאים:
  • אם סוג ההודעה הוא 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
הערה: האובייקט הזה ונכסי הצאצאים שלו הוצאו משימוש. החל מ-28 בפברואר 2017, המשאבים מסוג liveChatMessage לא יחזירו יותר פרטים על אירועי מימון על ידי מעריצים.

האובייקט הזה מכיל פרטים על אירוע המימון. השדה הזה מופיע רק אם message type הוא fanFundingEvent.
snippet.fanFundingEventDetails.amountMicros unsigned long
הערה: המאפיין הזה הוצא משימוש.

הסכום של הקרן.
snippet.fanFundingEventDetails.currency string
הערה: המאפיין הזה יצא משימוש.

המטבע שבו בוצע ההפקד.
snippet.fanFundingEventDetails.amountDisplayString string
הערה: המאפיין הזה הוצא משימוש.

מחרוזת שעברה עיבוד שמוצגים בה למשתמש סכום הקרן והמטבע.
snippet.fanFundingEventDetails.userComment string
הערה: המאפיין הזה הוצא משימוש.

התגובה שהמשתמש הוסיף לאירוע הזה של מימון על ידי מעריצים.
snippet.textMessageDetails object
האובייקט הזה מכיל פרטים על הודעת הטקסט. השדה הזה מופיע רק אם message type הוא textMessageEvent.
snippet.textMessageDetails.messageText string
ההודעה של המשתמש.
snippet.messageDeletedDetails object
האובייקט הזה מכיל פרטים על הודעה שנמחקה על ידי מנהל התגובות בצ'אט או על ידי הבעלים של ערוץ השידור החי. השדה הזה מופיע רק אם message type הוא messageDeletedEvent.
snippet.messageDeletedDetails.deletedMessageId string
המזהה הייחודי של ההודעה שנמחקה. הערך זהה לערך של המאפיין id בהודעת הטקסט המקורית. לדוגמה, אם ל-textMessageEvent יש ערך של id במאפיין id, וההודעה הזו נמחקת לאחר מכן, הערך של snippet.messageDeletedDetails.deletedMessageId יהיה 123 עבור ההודעה הזו.

אם אתם שומרים בזיכרון את הודעות הצ'אט אחרי שאתם מאחזרים אותן, אתם יכולים להשתמש בערך של המאפיין הזה כדי לזהות את ההודעה שאתם לא רוצים להציג יותר.123
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
האובייקט הזה מכיל פרטים על אירוע של נקודת ציון של חבר. השדה הזה מופיע רק אם message type הוא 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
האובייקט הזה מכיל פרטים על אירוע Super Chat. השדה הזה מופיע רק אם message type הוא superChatEvent.
snippet.superChatDetails.amountMicros unsigned long
סכום הרכישה, ב-micros של מטבע הרכישה. לדוגמה, אם סכום הרכישה הוא דולר אחד, הערך של המאפיין 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. (אפשר לעיין בקטע הניתן להרחבה בנושא פרטי רכישה של Super Chat). ברשימה הזו, הרמה עם סכום הרכישה הנמוך ביותר היא רמה 1, הסכום הנמוך הבא הוא רמה 2 וכן הלאה.
snippet.superStickerDetails object
האובייקט הזה מכיל פרטים על אירוע Super Sticker. השדה הזה מופיע רק אם message type הוא superStickerEvent.
snippet.superStickerDetails.superStickerMetadata object
פרטים על Super Sticker.
snippet.superStickerDetails.superStickerMetadata.stickerId string
מזהה ייחודי שמזהה את התמונה של המדבקה. חשוב לזכור שהתמונה מוצגת כחלק מההודעה עם ה-Super Sticker רק כשהמשתמשים צופים בחלון הצ'אט ב-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
סכום הרכישה, ב-micros של מטבע הרכישה. לדוגמה, אם סכום הרכישה הוא דולר אחד, הערך של המאפיין snippet.amountMicros הוא 1000000.
snippet.superStickerDetails.currency string
המטבע שבו בוצעה הרכישה. הערך הוא קוד מטבע לפי תקן ISO 4217.
snippet.superStickerDetails.amountDisplayString string
מחרוזת, כמו $1.00, שמכילה את סכום הרכישה ואת המטבע. המחרוזת מיועדת להצגה למשתמש.
snippet.superStickerDetails.tier unsigned integer
הרמה של ההודעה בתשלום. שימו לב שבמשאב superChatEvent, המאפיין snippet.messageType מכיל את הערך הזה.

הרמה מבוססת על סכום הכסף שהוצאתם לרכישת ההודעה. הוא גם קובע את הצבע שבו ההודעה תודגש בממשק המשתמש של הצ'אט בשידור חי, את האורך המקסימלי של ההודעה ואת משך הזמן שבו ההודעה תהיה מוצמדת לבורסה.

רמות הסופר צ'אט, שכוללות גם את התכונה Super Stickers, מתועדות במרכז העזרה של YouTube. (אפשר לעיין בקטע הניתן להרחבה בנושא פרטי רכישה של Super Chat). ברשימה הזו, הרמה עם סכום הרכישה הנמוך ביותר היא רמה 1, הסכום הנמוך הבא הוא רמה 2 וכן הלאה.
snippet.pollDetails object
האובייקט הזה מכיל פרטים על אירוע של סקר. השדה הזה מופיע רק אם message type הוא 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
המזהה של המשתמש שביצע את הרכישה של החברות במתנה. השדה הזה תואם ל-snippet.authorChannelId של הודעת החברות במועדון במתנה המשויכת.
snippet.giftMembershipReceivedDetails.associatedMembershipGiftingMessageId string
המזהה של הודעת מתנת החברות שמשויכת לחברות במועדון במתנה הזו. המזהה הזה תמיד יתייחס להודעה שהערך של type בה הוא membershipGiftingEvent.
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
הערך הזה מציין אם המחבר הוא מנחה של הצ'אט בשידור חי.