LiveChatMessages: list

Listet Live-Chat-Nachrichten für einen bestimmten Chat auf.

Wenn du deine erste Anfrage zum Abrufen von Chatnachrichten sendest, gibt die API je nach Länge des Verlaufs einen Teil oder den gesamten Chatverlauf zurück. Die Nachrichten in der Antwort sind von der ältesten zur neuesten sortiert.
  • Der nextPageToken in der Antwort enthält ein Token, mit dem in deiner nächsten Anfrage die nächste Gruppe von Ergebnissen identifiziert wird, die dein API-Client abrufen soll.
  • Die Property pollingIntervalMillis gibt an, wie lange dein API-Client warten soll, bevor er weitere Ergebnisse anfordert.
Wenn du weitere Ergebnisse anforderst, legst du den Parameter pageToken auf den Wert nextPageToken fest. Der API-Server gibt dann weitere Chatnachrichten zurück, sofern verfügbar. Auch in dieser Ergebnismenge sind die Nachrichten von der ältesten zur neuesten sortiert.

Kontingent:Ein Aufruf dieser Methode kostet 5 Kontingenteinheiten.

Gängige Anwendungsfälle

Anfrage

HTTP-Anfrage

GET https://www.googleapis.com/youtube/v3/liveChat/messages

Parameter

In der folgenden Tabelle sind die Parameter aufgeführt, die von dieser Abfrage unterstützt werden. Alle aufgeführten Parameter sind Abfrageparameter.

Parameter
Erforderliche Parameter
liveChatId string
Der liveChatId Parameter gibt die ID des Chats an, dessen Nachrichten zurückgegeben werden. Die Live-Chat-ID, die mit einer Übertragung verknüpft ist, wird in der Property snippet.liveChatId der Ressource liveBroadcast zurückgegeben.
part string
Der Parameter part gibt die Teile der Ressource liveChatMessage an, die in der API-Antwort enthalten sein sollen. Unterstützte Werte sind id, snippet und authorDetails.
Optionale Parameter
hl string
Mit dem Parameter hl wird die API angewiesen, einen lokalisierten String für die Währungsanzeige für eine bestimmte Anwendungssprache abzurufen, die von der YouTube-Website unterstützt wird. Auf Deutsch wird die Währung beispielsweise als $1.50 angezeigt, auf Englisch als 1,50$.

Der Parameterwert muss ein Sprachcode sein, der in der Liste enthalten ist, die von der Methode i18nLanguages.list zurückgegeben wird.
maxResults unsigned integer

Der maxResults Parameter gibt die maximale Anzahl von Nachrichten an, die in der Ergebnismenge zurückgegeben werden sollen. Zulässige Werte sind 200 bis 2000 (einschließlich). Der Standardwert ist 500.

Die erste Anfrage ohne Fortsetzungstoken enthält nur die neuesten Nachrichten. Dieser Wert kann kleiner als maxResults sein, falls angegeben.

Die API ruft keine Nachrichten ab, die älter sind als die, die von der ersten Anfrage ohne Fortsetzungstoken zurückgegeben wurden.
pageToken string
Der Parameter pageToken gibt eine bestimmte Seite in der Ergebnismenge an, die zurückgegeben werden soll. In einer API-Antwort identifiziert die Property nextPageToken andere Seiten, die abgerufen werden können.
profileImageSize unsigned integer
Der Parameter profileImageSize gibt die Größe der Nutzerprofilbilder an, die in der Ergebnismenge zurückgegeben werden sollen. Die Bilder sind quadratisch. Der Standardwert ist 88. Die Bilder sind also 88 × 88 Pixel groß. Zulässige Werte liegen im Bereich von 16 bis 720 (einschließlich).

Anfragetext

Gib beim Aufrufen dieser Methode keinen Anfragetext an.

Antwort

Bei Erfolg gibt diese Methode einen Antworttext mit der folgenden Struktur zurück:

{
  "kind": "youtube#liveChatMessageListResponse",
  "etag": etag,
  "nextPageToken": string,
  "pollingIntervalMillis": unsigned integer,
  "offlineAt": datetime,
  "pageInfo": {
    "totalResults": integer,
    "resultsPerPage": integer
  },
  "items": [
    liveChatMessage Resource
  ],
  "activePollItem": liveChatMessage Resource
}

Attribute

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

Attribute
kind string
Identifiziert den Typ der API-Ressource. Der Wert ist youtube#liveChatMessageListResponse.
etag etag
Das ETag dieser Ressource.
nextPageToken string
Das Token, das als Wert des Parameters pageToken verwendet werden kann, um die nächste Seite in der Ergebnismenge abzurufen.
pollingIntervalMillis unsigned integer
Die Zeit in Millisekunden, die der Client warten soll, bevor er noch einmal nach neuen Live-Chat-Nachrichten sucht.
offlineAt datetime
Datum und Uhrzeit, zu der der zugrunde liegende Livestream offline gegangen ist. Diese Property ist nur vorhanden, wenn der Stream bereits offline ist. Der Wert wird im ISO 8601-Format (YYYY-MM-DDThh:mm:ss.sZ) angegeben.
pageInfo object
Das Objekt pageInfo enthält Paging-Informationen für die Ergebnismenge.
pageInfo.totalResults integer
Die Gesamtzahl der Ergebnisse in der Ergebnismenge.
pageInfo.resultsPerPage integer
Die Anzahl der Ergebnisse in der API-Antwort.
items[] list
Eine Liste von Nachrichten. Jeder Eintrag in der Liste ist eine Ressource vom Typ liveChatMessage.
activePollItem object
Die Umfragedaten in der Nachricht. Jede Umfrage ist eine Ressource vom Typ liveChatMessage mit dem Typ pollEvent, die eine aktive Umfrage darstellt. Pro Chat kann nur eine Umfrage vorhanden sein.

Fehler

In der folgenden Tabelle sind die Fehlermeldungen aufgeführt, die die API als Antwort auf einen Aufruf dieser Methode zurückgeben kann. Weitere Informationen findest du in der Dokumentation zu Fehlermeldungen.

Fehlertyp Fehlerdetails Beschreibung
forbidden (403) forbidden Du hast nicht die erforderlichen Berechtigungen, um Nachrichten für den angegebenen Live-Chat abzurufen.
forbidden (403) liveChatDisabled Der Live-Chat ist für die angegebene Übertragung nicht aktiviert.
forbidden (403) liveChatEnded Der angegebene Live-Chat ist nicht mehr aktiv.
notFound (404) liveChatNotFound Der Live-Chat, den du abrufen möchtest, wurde nicht gefunden. Prüfe den Wert des Parameters liveChatId der Anfrage, um sicherzustellen, dass er korrekt ist.
rateLimitExceeded rateLimitExceeded Die Anfrage wurde zu schnell nach der vorherigen Anfrage gesendet. Dieser Fehler tritt auf, wenn API-Anfragen zum Abrufen von Nachrichten häufiger gesendet werden als die Aktualisierungsraten von YouTube. Dadurch wird unnötig Bandbreite verbraucht.

Testen!

Mit dem APIs Explorer kannst du diese API aufrufen und die API-Anfrage und -Antwort ansehen.