LiveChatMessages

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

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

Methods

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

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

האובייקט הזה מכיל פרטים על אירוע המימון. הוא מופיע רק אם סוג ההודעה הוא 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 של הודעת הטקסט המקורית. לדוגמה, אם ל-textMessageEvent יש ערך מאפיין id של 123, וההודעה הזו נמחקת בהמשך, הערך של snippet.messageDeletedDetails.deletedMessageId יהיה 123 עבור ההודעה הזו.

אם אתם שומרים במטמון הודעות צ'אט אחרי שאתם מאחזרים אותן, אתם יכולים להשתמש בערך של המאפיין הזה כדי לזהות את ההודעה שכבר לא צריכה להיות מוצגת.
snippet.userBannedDetails object
האובייקט הזה מכיל פרטים על משתמש שנחסם מ-Chat. הוא מכיל גם פרטים על ההשעיה עצמה. אפשר להרחיק משתמשים מצ'אט באופן קבוע או זמני.
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
סוג ההרחקה. הערכים התקינים של המאפיין הזה הם:
  • permanent
  • זמני
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
האובייקט הזה מכיל פרטים על האירוע New Member Announcement. השדה הזה מוגדר רק אם הסוג הוא 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. (אפשר לעיין באזור שאפשר להרחיב כדי לראות את פרטי הרכישה של Super Chat). ברשימה הזו, רמת החברות עם סכום הרכישה הנמוך ביותר היא רמה 1, רמת החברות עם סכום הרכישה הנמוך הבא היא רמה 2 וכן הלאה.
snippet.superStickerDetails object
האובייקט הזה מכיל פרטים על אירוע של Super Sticker. הוא מופיע רק אם סוג ההודעה הוא 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
סכום הרכישה, במיקרו של מטבע הרכישה. לדוגמה, אם סכום הרכישה הוא דולר אחד, ערך המאפיין snippet.amountMicros הוא 1000000.
snippet.superStickerDetails.currency string
המטבע שבו בוצעה הרכישה. הערך הוא קוד מטבע לפי תקן ISO 4217.
snippet.superStickerDetails.amountDisplayString string
מחרוזת, כמו $1.00, שמכילה את סכום הרכישה והמטבע. המחרוזת מיועדת להצגה למשתמש.
snippet.superStickerDetails.tier unsigned integer
הרמה של ההודעה בתשלום. שימו לב שבמשאב superChatEvent, המאפיין snippet.messageType מכיל את הערך הזה.

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

שכבות הסופר צ'אט, שכוללות גם סופר סטיקרים, מתועדות במרכז העזרה של YouTube. (אפשר לעיין באזור שאפשר להרחיב כדי לראות את פרטי הרכישה של Super Chat). ברשימה הזו, רמת החברות עם סכום הרכישה הנמוך ביותר היא רמה 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
הסטטוס של אירוע הסקר בשידור חי. הערכים התקינים של המאפיין הזה הם:
  • 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
הערך הזה מציין אם המחבר הוא מנחה של הצ'אט בשידור חי.