LiveChatMessages: list

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

Wenn Sie Ihre erste Anfrage zum Abrufen von Chatnachrichten stellen, gibt die API je nach Länge des Chatverlaufs einen Teil oder den gesamten Chatverlauf zurück. Die Nachrichten in der Antwort sind von alt nach neu sortiert.
  • Das nextPageToken in der Antwort enthält ein Token, mit dem im nächsten Request die nächste Gruppe von Ergebnissen identifiziert wird, die Ihr API-Client abrufen soll.
  • Das Attribut pollingIntervalMillis gibt an, wie lange Ihr API-Client warten soll, bevor er zusätzliche Ergebnisse anfordert.
Wenn Sie zusätzliche Ergebnisse anfordern, legen Sie den Parameter pageToken auf den Wert nextPageToken fest. Der API-Server gibt dann zusätzliche Chatnachrichten zurück, sofern verfügbar. Auch in dieser Ergebnismenge sind die Nachrichten von alt nach neu sortiert.

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 Parameter liveChatId gibt die ID des Chats an, dessen Nachrichten zurückgegeben werden. Die mit einer Übertragung verknüpfte Livechat-ID wird in der snippet.liveChatId-Eigenschaft der liveBroadcast-Ressource zurückgegeben.
part string
Mit dem Parameter part werden die liveChatMessage-Ressourcenteile angegeben, 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 Währungsanzeigestring 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 Französisch 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 Parameter maxResults gibt die maximale Anzahl von Nachrichten an, die im Ergebnissatz zurückgegeben werden sollen. Zulässige Werte sind 200 bis einschließlich 2000. Der Standardwert ist 500.
pageToken string
Der Parameter pageToken gibt eine bestimmte Seite im Ergebnissatz an, die zurückgegeben werden soll. In einer API-Antwort gibt die Eigenschaft nextPageToken andere Seiten an, die abgerufen werden könnten.
profileImageSize unsigned integer
Der Parameter profileImageSize gibt die Größe der Profilbilder der Nutzer an, die im Ergebnissatz zurückgegeben werden sollen. Die Bilder sind quadratisch. Der Standardwert ist 88, d. h. Bilder werden mit einer Größe von 88 × 88 Pixeln angezeigt. Zulässige Werte liegen im Bereich von 16 bis einschließlich 720.

Anfragetext

Geben Sie 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 werden die Attribute definiert, die in dieser Ressource enthalten sind:

Attribute
kind string
Gibt den Typ der API-Ressource an. 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 wieder nach neuen Live-Chatnachrichten 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 pageInfo-Objekt enthält Paging-Informationen für das Ergebnis-Set.
pageInfo.totalResults integer
Die Gesamtzahl der Ergebnisse im Ergebnissatz.
pageInfo.resultsPerPage integer
Die Anzahl der in der API-Antwort enthaltenen Ergebnisse.
items[] list
Eine Liste von Nachrichten. Jedes Element in der Liste ist eine liveChatMessage-Ressource.
activePollItem object
Die Umfragedaten in der Nachricht. Jede Umfrage ist eine liveChatMessage-Ressource vom Typ pollEvent, die eine aktive Umfrage darstellt. Pro Chat kann es nur eine Umfrage geben.

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 finden Sie in der Dokumentation zur Fehlermeldung.

Fehlertyp Fehlerdetails Beschreibung
forbidden (403) forbidden Sie haben nicht die erforderlichen Berechtigungen, um Nachrichten für den angegebenen Livechat abzurufen.
forbidden (403) liveChatDisabled Für die angegebene Übertragung ist der Livechat nicht aktiviert.
forbidden (403) liveChatEnded Der angegebene Livechat ist nicht mehr aktiv.
notFound (404) liveChatNotFound Der Livechat, den Sie abrufen möchten, wurde nicht gefunden. Prüfen Sie 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 verschwendet.

Testen!

Verwenden Sie APIs Explorer, um diese API aufzurufen und die API-Anfrage und -Antwort zu sehen.