LiveChatMessages

Eine liveChatMessage-Ressource stellt eine Chatnachricht in einem YouTube-Livechat dar. Die Ressource kann Details zu verschiedenen Arten von Nachrichten enthalten, z. B. zu einer neu geposteten Textnachricht oder einer Fan-Finanzierungsveranstaltung.

Die Livechat-Funktion ist standardmäßig für Livestreams aktiviert und während der Liveveranstaltung verfügbar. Nach dem Ende der Veranstaltung ist der Livechat für diese Veranstaltung nicht mehr verfügbar.

Methoden

Die API unterstützt die folgenden Methoden für liveChatMessages-Ressourcen:

list
Listet Livechat-Nachrichten für einen bestimmten Chat auf. Hier kannst du die Funktion ausprobieren.
streamList
Ermöglicht eine Server-Streaming-Verbindung zum Empfangen von Livechat-Nachrichten für einen bestimmten Chat mit geringer Latenz. Hier kannst du die Funktion ausprobieren.
insert
Fügt einem Livechat eine Nachricht oder eine Umfrage hinzu. Hier kannst du die Funktion ausprobieren.
transition
Ändert den Status einer Livebenachrichtigung. Hier kannst du die Funktion ausprobieren.
Delete
Löscht eine Chatnachricht. Die API-Anfrage muss vom Kanalinhaber oder einem Moderator des Livechats autorisiert werden. Hier kannst du die Funktion ausprobieren.

Ressourcendarstellung

Die folgende JSON-Struktur zeigt das Format einer liveChatMessages-Ressource:

{
  "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
  },
}

Attribute

In der folgenden Tabelle werden die Attribute definiert, die in dieser Ressource enthalten sind:

Attribute
kind string
Gibt den Typ der API-Ressource an. Der Wert ist youtube#liveChatMessage.
etag etag
Das ETag dieser Ressource.
id string
Die ID, die YouTube zur eindeutigen Identifizierung der Nachricht zuweist.
snippet object
Das snippet-Objekt enthält die wichtigsten Details zur Chatnachricht.
snippet.type string
Der Typ der Nachricht. Diese Eigenschaft ist immer vorhanden und ihr Wert bestimmt, welche Felder in der Ressource vorhanden sind.

Gültige Werte für diese Eigenschaft sind:
  • chatEndedEvent: Der Chat wurde beendet und nach dieser Nachricht können keine weiteren Nachrichten mehr eingefügt werden. Das passiert automatisch einige Zeit nach dem Ende einer Übertragung. Diese Art von Nachricht wird nicht für Livechats in der Standardübertragung eines Kanals gesendet.
  • messageDeletedEvent – Eine Nachricht wurde von einem Moderator gelöscht. Das Feld author enthält die Details des Moderators. Für diesen Termin gibt es keine Inhalte, die angezeigt werden können.
  • sponsorOnlyModeEndedEvent: Der Chat ist nicht mehr im Modus „Nur für Sponsoren“. Das bedeutet, dass Nutzer, die keine Sponsoren sind, jetzt Nachrichten senden können. Für diesen Termin gibt es keine Inhalte, die angezeigt werden können.
  • sponsorOnlyModeStartedEvent: Der Chat befindet sich im „Nur-Unterstützer“-Modus. Das bedeutet, dass nur Unterstützer Nachrichten senden können. Für diesen Termin gibt es keine Inhalte, die angezeigt werden können.
  • newSponsorEvent – Ein neuer Nutzer hat den Kanal, zu dem der Livechat gehört, gesponsert. Die Felder author enthalten die Details des neuen Sponsors.
  • memberMilestoneChatEvent: Ein Nutzer hat eine Chatnachricht für treue Mitglieder gesendet.
  • superChatEvent: Ein Nutzer hat einen Super Chat gekauft.
  • superStickerEvent: Ein Nutzer hat einen Super Sticker gekauft.
  • textMessageEvent: Ein Nutzer hat eine SMS gesendet.
  • tombstone: Ein Tombstone bedeutet, dass eine Nachricht mit dieser ID und Veröffentlichungszeit vorhanden war, aber inzwischen gelöscht wurde. Sie wird nicht beim Löschen einer Nachricht gesendet, sondern zeigt an, wo sich die Nachricht vor dem Löschen befand. Bei diesem Nachrichtentyp sind nur die Felder snippet.liveChatId, snippet.type und snippet.publishedAt vorhanden.
  • userBannedEvent: Ein Nutzer wurde von einem Moderator gesperrt. Das Feld author enthält die Details des Moderators.
  • membershipGiftingEvent: Ein Nutzer hat Mitgliedschaften für andere Zuschauer gekauft.
  • giftMembershipReceivedEvent: Ein Nutzer hat eine geschenkte Mitgliedschaft erhalten.
  • pollDetails: Ein Nutzer hat eine Liveumfrage erstellt.
snippet.liveChatId string
Die ID, die den Livechat, mit dem die Nachricht verknüpft ist, eindeutig identifiziert. Die mit einer Übertragung verknüpfte Livechat-ID wird in der snippet.liveChatId-Eigenschaft der liveBroadcast-Ressource zurückgegeben.
snippet.authorChannelId string
Die ID des Nutzers, der die Nachricht verfasst hat. Dieses Feld wird nur für die folgenden Nachrichtentypen ausgefüllt:
  • Wenn der Nachrichtentyp textMessageEvent ist, gibt der Eigenschaftswert den Nutzer an, der die Nachricht geschrieben hat.
  • Wenn der Nachrichtentyp fanFundingEvent ist, gibt der Attributwert den Nutzer an, der die Übertragung finanziert hat.
  • Wenn der Nachrichtentyp messageDeletedEvent ist, gibt der Eigenschaftswert den Moderator an, der die Nachricht gelöscht hat.
  • Wenn der Nachrichtentyp newSponsorEvent ist, gibt der Attributwert den Nutzer an, der gerade Sponsor geworden ist.
  • Wenn der Nachrichtentyp memberMilestoneChatEvent ist, gibt der Property-Wert das Mitglied an, das die Nachricht gesendet hat.
  • Wenn der Nachrichtentyp userBannedEvent ist, gibt der Attributwert den Moderator an, der den Nutzer gesperrt hat.
  • Wenn der Nachrichtentyp membershipGiftingEvent ist, gibt der Attributwert den Nutzer an, der das Geschenkabo gekauft hat.
  • Wenn der Nachrichtentyp giftMembershipReceivedEvent ist, gibt der Attributwert den Nutzer an, der die geschenkte Mitgliedschaft erhalten hat.
  • Wenn der Nachrichtentyp pollEvent ist, gibt der Eigenschaftswert den Nutzer an, der eine Live-Umfrage erstellt hat.
snippet.publishedAt datetime
Das Datum und die Uhrzeit, zu der die Nachricht ursprünglich veröffentlicht wurde. Der Wert wird im ISO 8601-Format (YYYY-MM-DDThh:mm:ss.sZ) angegeben.
snippet.hasDisplayContent boolean
Gibt an, ob die Nachricht Anzeigeelemente enthält, die Nutzern präsentiert werden sollten.
snippet.displayMessage string
Enthält einen String, der Nutzern angezeigt wird. Dieses Feld ist nicht vorhanden, wenn der Nachrichtentyp chatEndedEvent oder tombstone ist.
snippet.fanFundingEventDetails object
Hinweis: Dieses Objekt und seine untergeordneten Attribute wurden eingestellt. Ab dem 28. Februar 2017 werden in liveChatMessage-Ressourcen keine Details mehr zu Fan-Funding-Ereignissen zurückgegeben.

Dieses Objekt enthält Details zum Funding-Ereignis. Ist nur vorhanden, wenn der Nachrichtentyp fanFundingEvent ist.
snippet.fanFundingEventDetails.amountMicros unsigned long
Hinweis: Diese Eigenschaft wurde eingestellt.

Der Betrag des Fonds.
snippet.fanFundingEventDetails.currency string
Hinweis: Diese Eigenschaft wurde eingestellt.

Die Währung, in der der Fonds erstellt wurde.
snippet.fanFundingEventDetails.amountDisplayString string
Hinweis: Diese Property wurde eingestellt.

Ein gerenderter String, in dem dem Nutzer der Betrag und die Währung des Guthabens angezeigt werden.
snippet.fanFundingEventDetails.userComment string
Hinweis: Diese Property wurde eingestellt.

Der Kommentar, den der Nutzer diesem Fan-Funding-Ereignis hinzugefügt hat.
snippet.textMessageDetails object
Dieses Objekt enthält Details zur SMS. Ist nur vorhanden, wenn der Nachrichtentyp textMessageEvent ist.
snippet.textMessageDetails.messageText string
Die Nachricht des Nutzers.
snippet.messageDeletedDetails object
Dieses Objekt enthält Details zu einer Nachricht, die von einem Chatmoderator oder vom Inhaber des Kanals der Liveübertragung gelöscht wurde. Ist nur vorhanden, wenn der Nachrichtentyp messageDeletedEvent ist.
snippet.messageDeletedDetails.deletedMessageId string
Die ID, die die gelöschte Nachricht eindeutig identifiziert. Der Wert entspricht dem Eigenschaftswert id der ursprünglichen SMS. Wenn beispielsweise eine textMessageEvent den id-Attributwert 123 hat und diese Nachricht später gelöscht wird, ist der snippet.messageDeletedDetails.deletedMessageId-Wert für diese Nachricht 123.

Wenn Sie Chatnachrichten nach dem Abrufen im Cache speichern, verwenden Sie den Wert dieses Attributs, um die Nachricht zu identifizieren, die nicht mehr angezeigt werden soll.
snippet.userBannedDetails object
Dieses Objekt enthält Details zu einem Nutzer, der aus dem Chat ausgeschlossen wurde. Sie enthält auch Details zum Ausschluss selbst. Nutzer können dauerhaft oder vorübergehend aus einem Chat ausgeschlossen werden.
snippet.userBannedDetails.bannedUserDetails object
Dieses Objekt enthält Informationen zum gesperrten Nutzer.
snippet.userBannedDetails.bannedUserDetails.channelId string
Die YouTube-Kanal-ID des gesperrten Nutzers.
snippet.userBannedDetails.bannedUserDetails.channelUrl string
Die URL des YouTube-Kanals des gesperrten Nutzers.
snippet.userBannedDetails.bannedUserDetails.displayName string
Der Anzeigename des YouTube-Kanals des gesperrten Nutzers.
snippet.userBannedDetails.bannedUserDetails.profileImageUrl string
Der Avatar des YouTube-Kanals des gesperrten Nutzers.
snippet.userBannedDetails.banType string
Die Art des Ausschlusses. Gültige Werte für diese Eigenschaft sind:
  • dauerhaft
  • Übergangslösung
snippet.userBannedDetails.banDurationSeconds unsigned long
Die Dauer des Ausschlusses. Diese Property ist nur vorhanden, wenn der Wert der Property snippet.userBannedDetails.banType temporary ist.
snippet.memberMilestoneChatDetails object
Dieses Objekt enthält Details zu einem Member Milestone event (Meilensteinereignis für Mitglieder). Ist nur vorhanden, wenn der Nachrichtentyp memberMilestoneChatEvent ist.
snippet.memberMilestoneChatDetails.userComment string
Der Kommentar, den das Mitglied dieser Chatnachricht für treue Mitglieder hinzugefügt hat. Dieses Feld ist für Nachrichten ohne Kommentar des Mitglieds leer.
snippet.memberMilestoneChatDetails.memberMonth unsigned integer
Die Gesamtzahl der Monate (aufgerundet), in denen der Zuschauer Mitglied war und dadurch diese Chatnachricht für treue Mitglieder erhalten hat. Das ist die gleiche Anzahl an Monaten, die YouTube-Nutzern angezeigt wird.
snippet.memberMilestoneChatDetails.memberLevelName string
Der Name der Mitgliedschaftsstufe, in der der Zuschauer Mitglied ist. Die Namen der Mitgliedschaftsstufen werden vom YouTube-Kanal festgelegt, der die Mitgliedschaft anbietet. In einigen Fällen wird dieses Feld nicht ausgefüllt.
snippet.newSponsorDetails object
Dieses Objekt enthält Details zum Ereignis „New Member Announcement“ (Ankündigung neuer Mitglieder). Wird nur festgelegt, wenn der Typ newSponsorEvent ist. „Mitglied“ ist der Begriff für „Sponsor“.
snippet.newSponsorDetails.memberLevelName string
Der Name der Mitgliedschaftsstufe, in der der Zuschauer Mitglied ist. Die Namen der Mitgliedschaftsstufen werden vom YouTube-Kanal festgelegt, der die Mitgliedschaft anbietet. In einigen Fällen ist dieses Feld nicht ausgefüllt.
snippet.newSponsorDetails.isUpgrade bool
Gibt an, ob der Zuschauer gerade von einer niedrigeren Stufe aufgestiegen ist. Bei Zuschauern, die zum Zeitpunkt des Kaufs keine Mitglieder waren, ist der Feldwert false.
snippet.superChatDetails object
Dieses Objekt enthält Details zu einem Super Chat-Ereignis. Ist nur vorhanden, wenn der Nachrichtentyp superChatEvent ist.
snippet.superChatDetails.amountMicros unsigned long
Der Kaufbetrag in Mikroeinheiten der Kaufwährung. Wenn der Kaufbetrag beispielsweise 1 $ beträgt, ist der Wert des Attributs snippet.amountMicros gleich 1000000.
snippet.superChatDetails.currency string
Die Währung, in der der Kauf erfolgte. Der Wert ist ein ISO 4217-Währungscode.
snippet.superChatDetails.amountDisplayString string
Ein String wie $1.00, der den Kaufbetrag und die Währung enthält. Der String ist für die Anzeige für den Nutzer vorgesehen.
snippet.superChatDetails.userComment string
Der Kommentar, den der Nutzer diesem Super Chat-Ereignis hinzugefügt hat.
snippet.superChatDetails.tier unsigned integer
Die Stufe für die kostenpflichtige Nachricht. In einer superChatEvent-Ressource enthält das Attribut snippet.messageType diesen Wert.

Die Stufe basiert auf dem Betrag, der für den Kauf der Mitteilung ausgegeben wurde. Außerdem wird dadurch die Farbe bestimmt, mit der die Nachricht in der Benutzeroberfläche des Livechats hervorgehoben wird, die maximale Nachrichtenlänge und die Zeit, die die Nachricht im Ticker angepinnt ist.

Die Super Chat-Stufen sind in der YouTube-Hilfe dokumentiert. Weitere Informationen findest du im aufklappbaren Abschnitt zu Super Chat-Kaufdetails. In dieser Liste ist die Stufe mit dem niedrigsten Kaufbetrag Stufe 1, die mit dem nächstniedrigsten Betrag Stufe 2 usw.
snippet.superStickerDetails object
Dieses Objekt enthält Details zu einem Super Sticker-Ereignis. Ist nur vorhanden, wenn der Nachrichtentyp superStickerEvent ist.
snippet.superStickerDetails.superStickerMetadata object
Details zum Super Sticker.
snippet.superStickerDetails.superStickerMetadata.stickerId string
Eine eindeutige ID, die das Stickerbild identifiziert. Das Bild wird nur als Teil der Super Sticker-Nachricht angezeigt, wenn Nutzer das Chatfenster auf YouTube aufrufen. Die Bild-URL ist jedoch nicht über die API verfügbar. In dieser CSV-Datei findest du eine Übersicht, welche Sticker-IDs zu welchen Super Stickern gehören.
snippet.superStickerDetails.superStickerMetadata.altText string
Ein Textstring, der den Sticker beschreibt. Das Feld snippet.superStickerDetails.superStickerMetadata.language gibt die Sprache des Textes an. Legen Sie beim Aufrufen der liveChatMessages.list-Methode den Wert des Parameters hl auf die ausgewählte Sprache für den Text fest.
snippet.superStickerDetails.superStickerMetadata.language string
Die Sprache des snippet.superStickerDetails.superStickerMetadata.altText-Attributwerts.
snippet.superStickerDetails.amountMicros unsigned long
Der Kaufbetrag in Mikroeinheiten der Kaufwährung. Wenn der Kaufbetrag beispielsweise 1 $ beträgt, ist der Wert des Attributs snippet.amountMicros gleich 1000000.
snippet.superStickerDetails.currency string
Die Währung, in der der Kauf erfolgte. Der Wert ist ein ISO 4217-Währungscode.
snippet.superStickerDetails.amountDisplayString string
Ein String wie $1.00, der den Kaufbetrag und die Währung enthält. Der String ist für die Anzeige für den Nutzer vorgesehen.
snippet.superStickerDetails.tier unsigned integer
Die Stufe für die kostenpflichtige Nachricht. In einer superChatEvent-Ressource enthält das Attribut snippet.messageType diesen Wert.

Die Stufe basiert auf dem Betrag, der für den Kauf der Mitteilung ausgegeben wurde. Außerdem wird dadurch die Farbe bestimmt, mit der die Nachricht in der Livechat-Benutzeroberfläche hervorgehoben wird, die maximale Nachrichtenlänge und die Zeit, die die Nachricht im Ticker angepinnt ist.

Die Super Chat-Stufen, die auch Super Sticker umfassen, sind in der YouTube-Hilfe dokumentiert. Weitere Informationen findest du im aufklappbaren Abschnitt zu Super Chat-Kaufdetails. In dieser Liste ist die Stufe mit dem niedrigsten Kaufbetrag Stufe 1, die mit dem nächstniedrigsten Betrag Stufe 2 usw.
snippet.pollDetails object
Dieses Objekt enthält Details zu einem Umfrageereignis. Ist nur vorhanden, wenn der Nachrichtentyp pollEvent ist.
snippet.pollDetails.metadata object
Details zum Umfrageereignis.
snippet.pollDetails.metadata.options object
Die Optionen in der Live-Umfrage.
snippet.pollDetails.metadata.options.optionText string
Der Text der Option für die Live-Umfrage.
snippet.pollDetails.metadata.options.tally string
Die Anzahl der Stimmen für die Liveumfrage-Option. Die Anzahl ist nur vorhanden, wenn die API-Anfrage vom Kanalinhaber autorisiert wurde.
snippet.pollDetails.metadata.questionText string
Der Text der Frage in der Live-Umfrage.
snippet.pollDetails.metadata.status enum
Der Status des Live-Umfrage-Events. Gültige Werte für diese Eigenschaft sind:
  • unknown
  • active
  • closed
snippet.membershipGiftingDetails object
Dieses Objekt enthält Details zu einem Ereignis, bei dem eine Mitgliedschaft verschenkt wurde. Sie ist nur vorhanden, wenn message type membershipGiftingEvent ist.
snippet.membershipGiftingDetails.giftMembershipsCount integer
Die Anzahl der vom Nutzer gekauften Geschenkabos.
snippet.membershipGiftingDetails.giftMembershipsLevelName string
Der Name der Stufe der vom Nutzer gekauften verschenkten Mitgliedschaften. Die Namen der Mitgliedschaftsstufen werden vom YouTube-Kanal festgelegt, der die Mitgliedschaft anbietet. In einigen Fällen ist dieses Feld nicht ausgefüllt.
snippet.giftMembershipReceivedDetails object
Dieses Objekt enthält Details zu einem Ereignis vom Typ „Geschenkte Mitgliedschaft erhalten“. Sie ist nur vorhanden, wenn message type giftMembershipReceivedEvent ist.
snippet.giftMembershipReceivedDetails.memberLevelName string
Der Name der Mitgliedschaftsstufe, in der der Zuschauer Mitglied ist. Das entspricht dem snippet.membershipGiftingDetails.giftMembershipsLevelName der zugehörigen Nachricht zum Verschenken von Mitgliedschaften. Die Namen der Mitgliedschaftsstufen werden vom YouTube-Kanal festgelegt, der die Mitgliedschaft anbietet. In einigen Fällen ist dieses Feld nicht ausgefüllt.
snippet.giftMembershipReceivedDetails.gifterChannelId string
Die ID des Nutzers, der die Mitgliedschaft verschenkt hat. Das entspricht dem snippet.authorChannelId der zugehörigen Nachricht zum Verschenken von Mitgliedschaften.
snippet.giftMembershipReceivedDetails.associatedMembershipGiftingMessageId string
Die ID der Nachricht zum Verschenken von Mitgliedschaften, die sich auf diese geschenkte Mitgliedschaft bezieht. Diese ID bezieht sich immer auf eine Nachricht, deren type membershipGiftingEvent ist.
authorDetails object
Das authorDetails-Objekt enthält zusätzliche Details zum Nutzer, der diese Nachricht gepostet hat.
authorDetails.channelId string
Die YouTube-Kanal-ID des Autors.
authorDetails.channelUrl string
Die URL des YouTube-Kanals des Autors.
authorDetails.displayName string
Der Anzeigename des YouTube-Kanals des Autors.
authorDetails.profileImageUrl string
Die Avatar-URL des YouTube-Kanals des Autors.
authorDetails.isVerified boolean
Dieser Wert gibt an, ob die Identität des Autors von YouTube bestätigt wurde.
authorDetails.isChatOwner boolean
Dieser Wert gibt an, ob der Autor der Inhaber des Livechats ist.
authorDetails.isChatSponsor boolean
Dieser Wert gibt an, ob der Autor ein Sponsor des Livechats ist.
authorDetails.isChatModerator boolean
Dieser Wert gibt an, ob der Autor ein Moderator des Livechats ist.