LiveChatMessages

Eine liveChatMessage-Ressource steht für eine Chatnachricht in einem YouTube-Live-Chat. Die Ressource kann Details zu verschiedenen Arten von Nachrichten enthalten, z. B. zu einer neu geposteten Textnachricht oder einem Fan-Funding-Event.

Die Live-Chat-Funktion ist standardmäßig für Live-Übertragungen aktiviert und während der Live-Veranstaltung verfügbar. (Nach Ende der Veranstaltung ist der Live-Chat für diese Veranstaltung nicht mehr verfügbar.)

Methoden

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

list
Listet Livechatnachrichten für einen bestimmten Chat auf. Hier kannst du die Funktion ausprobieren.
streamList
Ermöglicht eine Server-Streaming-Verbindung, um Live-Chatnachrichten für einen bestimmten Chat mit geringer Latenz zu empfangen. Hier kannst du die Funktion ausprobieren.
insert
Fügt einem Live-Chat eine Nachricht oder eine Umfrage hinzu. Hier kannst du die Funktion ausprobieren.
transition
Ändert den Status einer Live-Nachricht. Hier kannst du die Funktion ausprobieren.
Delete
Löscht eine Chatnachricht. Die API-Anfrage muss vom Kanalinhaber oder einem Moderator des Live-Chats 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
    },
    "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
  },
}

Attribute

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

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 der Nachricht zur eindeutigen Identifizierung zuweist.
Hinweis: Bei giftEvents kann dieselbe ID wiederverwendet werden, um die Anzahl der Combos zu aktualisieren.
snippet object
Das snippet-Objekt enthält wichtige Details zur Chatnachricht.
snippet.type string
Der Typ der Nachricht. Dieses Attribut ist immer vorhanden und sein Wert bestimmt, welche Felder in der Ressource vorhanden sind.

Gültige Werte für dieses Attribut 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 Live-Chats in der Standardübertragung eines Kanals gesendet.
  • sponsorOnlyModeEndedEvent: Der Chat ist nicht mehr im Modus „Nur für VIPs“. Das bedeutet, dass Nutzer, die keine VIPs sind, jetzt Nachrichten senden können. Für dieses Ereignis gibt es keine Anzeigeinhalte.
  • sponsorOnlyModeStartedEvent: Der Chat befindet sich im „Nur-Unterstützer“-Modus. Das bedeutet, dass nur Unterstützer Nachrichten senden können. Für dieses Ereignis gibt es keine Inhalte, die angezeigt werden können.
  • newSponsorEvent: Ein neuer Nutzer ist Kanalmitglied des Kanals geworden, zu dem der Livechat gehört. 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 Nachricht gesendet.
  • tombstone: Ein Tombstone bedeutet, dass eine Nachricht mit dieser ID und Veröffentlichungszeit existierte, 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. Nur die Felder snippet.liveChatId, snippet.type und snippet.publishedAt sind in dieser Art von Nachricht 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.
  • giftEvent: Ein Nutzer hat Juwelen gegen ein Geschenk eingelöst.
snippet.liveChatId string
Die ID, die den Livechat, mit dem die Nachricht verknüpft ist, eindeutig identifiziert. Die mit einer Übertragung verknüpfte Live-Chat-ID wird in der Property snippet.liveChatId der Ressource liveBroadcast 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 Attributwert 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 newSponsorEvent ist, gibt der Attributwert den Nutzer an, der gerade Sponsor geworden ist.
  • Wenn der Nachrichtentyp memberMilestoneChatEvent ist, gibt der Attributwert 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 Verschenken einer Mitgliedschaft 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 Attributwert den Nutzer an, der eine Live-Umfrage erstellt hat.
  • Wenn der Nachrichtentyp giftEvent ist, gibt der Attributwert den Nutzer an, der das Geschenk gesendet 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 Inhalte enthält, die Nutzern angezeigt werden sollen.
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 Properties werden nicht mehr unterstützt. Ab dem 28. Februar 2017 werden von liveChatMessage-Ressourcen keine Details zu Fan-Funding-Ereignissen mehr zurückgegeben.

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

Der Betrag des Fonds.
snippet.fanFundingEventDetails.currency string
Hinweis: Diese Property wurde verworfen.

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

Ein gerenderter String, der dem Nutzer den Betrag und die Währung des Guthabens anzeigt.
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 Nachricht. Sie ist nur vorhanden, wenn der Nachrichtentyp textMessageEvent ist.
snippet.textMessageDetails.messageText string
Die Nachricht des Nutzers.
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 gesperrt 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 der Sperre. Gültige Werte für dieses Attribut sind:
  • dauerhaft
  • Übergangslösung
snippet.userBannedDetails.banDurationSeconds unsigned long
Die Dauer der Sperre. 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 Meilenstein-Ereignis für Mitglieder. Es 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), die der Zuschauer Mitglied ist und die ihm diese Chatnachricht für treue Mitglieder eingebracht hat. Das ist dieselbe Anzahl an Monaten, die YouTube-Nutzern angezeigt wird.
snippet.memberMilestoneChatDetails.memberLevelName string
Der Name der Stufe, auf der der Zuschauer Mitglied ist. Die Namen der Stufen werden vom YouTube-Kanal festgelegt, der die Mitgliedschaft anbietet. In einigen Situationen ist dieses Feld nicht ausgefüllt.
snippet.newSponsorDetails object
Dieses Objekt enthält Details zum Ereignis „New Member Announcement“ (Ankündigung neuer Mitglieder). Dies wird nur festgelegt, wenn der Typ newSponsorEvent ist. „Mitglied“ ist der Begriff für „Sponsor“.
snippet.newSponsorDetails.memberLevelName string
Der Name der Stufe, auf der der Zuschauer Mitglied ist. Die Namen der Stufen 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. Für Zuschauer, 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. Es ist nur vorhanden, wenn der Nachrichtentyp superChatEvent ist.
snippet.superChatDetails.amountMicros unsigned long
Der Kaufbetrag in Mikros 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 getätigt wurde. Der Wert ist ein Währungscode gemäß ISO 4217.
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 zu 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 die Property snippet.messageType diesen Wert.

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

Die Super Chat-Stufen sind in der YouTube-Hilfe dokumentiert. (Weitere Informationen findest du im maximierbaren Abschnitt zu Super Chat-Kaufdetails.) In dieser Liste ist die Stufe mit dem niedrigsten Kaufbetrag Stufe 1, der nächsthöhere Betrag ist Stufe 2 usw.
snippet.superStickerDetails object
Dieses Objekt enthält Details zu einem Super Sticker-Ereignis. Sie 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 dann 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 kannst du nachsehen, 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 hl-Parameterwert 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 Mikros der Kaufwährung. Wenn der Kaufbetrag beispielsweise 1 € beträgt, ist der Wert des Attributs snippet.amountMicros 1000000.
snippet.superStickerDetails.currency string
Die Währung, in der der Kauf getätigt wurde. 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 Nachricht ausgegeben wurde. Außerdem wird dadurch die Farbe bestimmt, mit der die Nachricht im Live-Chat hervorgehoben wird, sowie die maximale Nachrichtenlänge und die Zeit, die die Nachricht im Ticker angepinnt bleibt.

Die Super Chat-Stufen, die auch Super Sticker abdecken, sind in der YouTube-Hilfe dokumentiert. (Weitere Informationen findest du im maximierbaren Abschnitt zu Super Chat-Kaufdetails.) In dieser Liste ist die Stufe mit dem niedrigsten Kaufbetrag Stufe 1, der nächsthöhere Betrag ist Stufe 2 usw.
snippet.pollDetails object
Dieses Objekt enthält Details zu einem Umfrageereignis. Es ist nur vorhanden, wenn der Nachrichtentyp pollEvent ist.
snippet.pollDetails.metadata object
Details zum Umfrageereignis.
snippet.pollDetails.metadata.options object
Die Optionen in der Liveumfrage.
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 Option der Liveumfrage. Die Anzahl der Stimmen 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-Umfrageereignisses. Gültige Werte für dieses Attribut sind:
  • unknown
  • active
  • closed
snippet.membershipGiftingDetails object
Dieses Objekt enthält Details zu einem Ereignis, bei dem Mitgliedschaften verschenkt werden. Sie ist nur vorhanden, wenn der message type membershipGiftingEvent ist.
snippet.membershipGiftingDetails.giftMembershipsCount integer
Die Anzahl der vom Nutzer gekauften verschenkten Mitgliedschaften.
snippet.membershipGiftingDetails.giftMembershipsLevelName string
Der Name der Stufe der vom Nutzer gekauften Geschenkmitgliedschaften. Die Namen der Stufen werden vom YouTube-Kanal definiert, 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, bei dem eine geschenkte Mitgliedschaft erhalten wurde. Es ist nur vorhanden, wenn der message type giftMembershipReceivedEvent ist.
snippet.giftMembershipReceivedDetails.memberLevelName string
Der Name der Stufe, auf der der Zuschauer Mitglied ist. Diese entspricht der snippet.membershipGiftingDetails.giftMembershipsLevelName der zugehörigen Nachricht zum Verschenken einer Mitgliedschaft. Die Namen der Stufen 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 das Verschenken einer Mitgliedschaft gekauft hat. Das entspricht der snippet.authorChannelId der zugehörigen Nachricht zum Verschenken einer Mitgliedschaft.
snippet.giftMembershipReceivedDetails.associatedMembershipGiftingMessageId string
Die ID der Nachricht zum Verschenken einer Mitgliedschaft, die sich auf diese geschenkte Mitgliedschaft bezieht. Diese ID bezieht sich immer auf eine Nachricht, deren type membershipGiftingEvent ist.
snippet.giftDetails object
Dieses Objekt enthält Details zu einem Geschenkereignis. Es ist nur vorhanden, wenn der message type giftEvent ist.
snippet.giftDetails.jewelsAmount integer
Die Anzahl der Juwelen, die für das Geschenk eingelöst wurden.
snippet.giftDetails.giftName string
Der Name des Geschenks.
snippet.giftDetails.giftUrl string
Die URL des Geschenk-Assets.
snippet.giftDetails.giftDuration object
Die Dauer, für die die Geschenk-URL angezeigt wird.
snippet.giftDetails.giftDuration.seconds integer
Die Anzahl der Sekunden, die die Geschenk-URL angezeigt wird.
snippet.giftDetails.giftDuration.nanos integer
Die Anzahl der Nanosekunden, die die Geschenk-URL angezeigt wird.
snippet.giftDetails.hasVisualEffect boolean
Gibt an, ob das Geschenk einen visuellen Effekt hat.
snippet.giftDetails.comboCount integer
Die Anzahl der Kombos des Geschenks; 0, wenn es sich nicht um eine Kombo handelt.
snippet.giftDetails.altText string
Ein Textstring, der das Geschenk beschreibt.
snippet.giftDetails.language string
Die Sprache des altText-Attributwerts.
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 Live-Chats ist.
authorDetails.isChatSponsor boolean
Dieser Wert gibt an, ob der Autor ein Sponsor des Live-Chats ist.
authorDetails.isChatModerator boolean
Dieser Wert gibt an, ob der Autor ein Moderator des Live-Chats ist.