Auf dieser Seite wird erläutert, wie Google Chat-Apps Ereignisse in Google Chat empfangen und darauf reagieren können.
Ein Google Chat-Ereignis stellt eine Aktivität oder Änderung in Chat dar, z. B. eine neue Nachricht in einem Gruppenbereich. Ihre Chat-App kann Ereignisse verwenden, um zu verstehen, was passiert ist, und um Maßnahmen zu ergreifen oder auf sinnvolle Weise für Ihre Nutzer zu reagieren.
Hier einige Beispiele für die Verwendung von Ereignissen:
- Neue Nachrichten in einem Gruppenbereich beobachten und darauf reagieren, z. B. nach Schlüsselwörtern oder ‑sätzen suchen.
- Nutzern eine Willkommensnachricht senden, wenn sie dem Gruppenbereich beitreten, um die Richtlinien für den Gruppenbereich zu erläutern oder Tipps zur effektiven Verwendung der Chat-App zu geben.
- Chat-Aktivitäten verfolgen und analysieren. Sie können beispielsweise einen monatlichen Bericht über neue Mitglieder oder die Nachrichten senden, die die meisten Reaktionen oder Antworten erhalten.
- Über Messaging-Plattformen hinweg kommunizieren. Nutzer können beispielsweise Nachrichten von Nutzern auf einer anderen Messaging-Plattform senden und empfangen, ohne Chat zu verlassen.
Funktionsweise von Ereignissen
Wenn in Google Chat etwas passiert, wird eine Google Chat API-Ressource erstellt, aktualisiert oder gelöscht. Chat verwendet Ereignisse, um Ihrer Chat-App Informationen zum Typ der aufgetretenen Aktivität und zur betroffenen Chat API-Ressource zu senden.
Message Ressource erstellt wird.
Chat erstellt dann ein Ereignis, das Daten zur neuen
Nachricht enthält.Chat kategorisiert Ereignisse nach Typ. Ereignistypen helfen Ihnen, nur die benötigten Informationen zu filtern und zu erhalten, und ermöglichen es Ihnen, ähnliche Aktivitäten auf dieselbe Weise zu verarbeiten.
In der folgenden Tabelle wird beschrieben, wie sich eine Aktivität in Chat auf eine zugehörige Chat API-Ressource auswirkt und welchen Ereignistyp Ihre Chat-App erhält:
| Aktivität | Chat API-Ressource | Ereignistyp |
|---|---|---|
| Ein Nutzer postet eine Nachricht in einem Chat-Gruppenbereich | Eine Message-Ressource wird erstellt. |
Neue Nachricht |
| Ein Nutzer wird zum Administrator eines Gruppenbereichs. | Eine Membership-Ressource wird aktualisiert. |
Aktualisierte Mitgliedschaft |
| Ein Nutzer reagiert auf eine Nachricht. | Eine Reaction-Ressource wird erstellt. |
Neue Reaktion |
| Ein Nutzer verlässt einen Gruppenbereich. | Eine Membership-Ressource wird gelöscht. |
Gelöschte Mitgliedschaft |
Ereignisse von Google Chat erhalten
Ihre Chat-App kann Ereignisse auf eine der folgenden Arten erhalten:
- Ereignisse mit der Google Workspace Events API abonnieren, um Ereignisse zu erhalten, sobald sie auftreten.
- Mit der Chat API nach aktuellen Ereignissen suchen.
In der folgenden Tabelle werden die Unterschiede und Gründe für das Abfragen oder Abonnieren von Ereignissen erläutert:
| Ereignisse abonnieren | Nach Ereignissen suchen | |
|---|---|---|
| Anwendungsfälle |
|
|
| API | Google Workspace Events API | Chat API |
| Quelle der Ereignisse | Gruppenbereiche, Nutzer und Google Workspace-Organisationen ( Developer Preview) | Nur Gruppenbereiche |
| Unterstützte Ereignisse |
Eine Liste der unterstützten Ereignistypen finden Sie in der Dokumentation zur Google Workspace Events API unter Ereignistypen zum Erstellen von Abos. |
Eine Liste der unterstützten Ereignistypen finden Sie in der Referenzdokumentation zur Chat API unter der Ressource spaceEvents.
|
| Ereignisformat | Eine Google Cloud Pub/Sub-Nachricht, die gemäß der CloudEvent-Spezifikation formatiert ist. Weitere Informationen finden Sie unter Struktur von Google Workspace-Ereignissen. |
Eine Chat API-Ressource
(
spaces.spaceEvent)
|
| Ereignisdaten | Base64-codierter String mit oder ohne Ressourcendaten. Beispielnutzlasten finden Sie unter Ereignisdaten. | JSON-Nutzlast mit Ressourcendaten. Einige Ereignistypen enthalten nur bestimmte Ressourcenfelder. Beispielnutzlasten finden Sie in der Referenzdokumentation. |
Beispiel: Ereignisse zu Mitgliedschaften in einem Gruppenbereich abfragen oder abonnieren
In diesem Beispiel möchte eine Chat-App Informationen zu Änderungen an Mitgliedern eines Chat-Gruppenbereichs erhalten. Im Gruppenbereich treten die folgenden Mitgliedschaftsaktivitäten auf:
- Ein Nutzer tritt dem Gruppenbereich bei, wodurch eine
Membership-Ressource erstellt und ein Ereignis für ein neues Mitglied ausgelöst wird. - Ein Nutzer wird zum Administrator eines Gruppenbereichs, wodurch die
Membership-Ressource für den Nutzer aktualisiert und ein Ereignis für ein aktualisiertes Mitglied ausgelöst wird. - Ein Nutzer verlässt den Gruppenbereich, wodurch die
Membership-Ressource für den Nutzer gelöscht und ein Ereignis für ein gelöschtes Mitglied ausgelöst wird.
Mitgliedschaftsereignisse abonnieren
Um Ereignisse in Echtzeit zu erhalten, ruft die
Chat-App die Google Workspace Events API
subscriptions.create()
Methode auf, um den Gruppenbereich für alle Arten von Mitgliedschaftsereignissen zu abonnieren. Nachdem das Abo erstellt wurde, kann die Chat-App Mitgliedschaftsereignisse empfangen.
In Abbildung 2 hat die Chat-App ein aktives Abo für den Gruppenbereich. Die App erhält also ein Ereignis, wenn sich eine Mitgliedschaft im Gruppenbereich ändert. Die Chat-App kann dann in Echtzeit auf eine der Aktivitäten reagieren, z. B. eine private Willkommensnachricht an das Mitglied senden, das dem Gruppenbereich beigetreten ist.
Informationen zum Erstellen von Abos mit der Google Workspace Events API, finden Sie in der Dokumentation zur Google Workspace Events API.
Nach aktuellen Mitgliedschaftsereignissen suchen
Anstatt die Mitgliedschaftsereignisse zu erhalten, sobald sie auftreten, kann eine Chat-App die Chat API aufrufen, um eine Liste der letzten Gruppenbereich-Ereignisse abzurufen, die mit Mitgliedschaftsaktivitäten zusammenhängen.
In Abbildung 3 ruft eine Chat-App die Chat API
spaces.spaceEvents.list()
Methode auf, nachdem alle Mitgliedschaftsaktivitäten stattgefunden haben, und filtert die Abfrage
nach neuen, aktualisierten und gelöschten Mitgliedschaftsereignissen. Die Chat API gibt eine Liste von spaceEvent-Ressourcen zurück, die die einzelnen Mitgliedschaftsänderungen darstellen.
Die Chat-App kann dann basierend auf der letzten Aktivität reagieren, z. B. eine wöchentliche Nachricht mit einer Zusammenfassung der Mitgliedschaftsaktivitäten des Gruppenbereichs in den letzten 7 Tagen posten.
Informationen zum Abfragen von Ereignissen mit der Chat API finden Sie unter Ereignisse aus einem Google Chat-Gruppenbereich auflisten.
Einschränkungen und Zustellungsverhalten
Allgemeine Beschränkungen
- Um Mitgliedschaftsereignisse zu erhalten, muss der Nutzer oder die Chat-App direkt Mitglied des Gruppenbereichs sein. Wenn sie einem Gruppenbereich indirekt über eine Google-Gruppe hinzugefügt, aktualisiert oder entfernt wurden, werden diese Mitgliedschaftsereignisse nicht an das Abo gesendet. Informationen zur Funktionsweise von Google-Gruppenmitgliedschaften finden Sie unter Google-Gruppe einem Gruppenbereich hinzufügen.
Nutzerabos
-
Bei Abos für Nutzer werden Ereignisse zu neuen Mitgliedern in Direktnachrichten oder unbenannten Gruppenchats (
google.workspace.chat.membership.v1.created), erst ausgelöst, nachdem die erste Nachricht gepostet wurde.
Kundenabos ( Developer Preview)
Für Kundenabos gelten die folgenden Einschränkungen:
- Die Google Workspace-Organisation muss mindestens eine Enterprise-SKU-Lizenz haben. Hinweis: Diese Anforderung wird während der Developer Preview Program-Phase nicht streng durchgesetzt, wird aber in Zukunft eingeführt (die Ankündigung erfolgt separat).
- Eine Chat-App kann nur ein Kundenabo für eine bestimmte Google Workspace-Organisation erstellen. Eine Google Workspace-Organisation kann insgesamt bis zu fünf Kundenabos haben (die von verschiedenen Chat-Apps erstellt wurden).
Für Kundenabos gelten für die Ereignisübermittlung die folgenden allgemeinen Regeln:
- Gruppenbereich-Ereignisse: Werden nur gesendet, wenn das Ereignis in einem Gruppenbereich auftritt, der von Ihrer Google Workspace-Organisation verwaltet wird.
- Nutzerereignisse: Werden nur gesendet, wenn das Ereignis für einen Nutzer auftritt, der zu Ihrer Google Workspace-Organisation gehört.
Die einzige Ausnahme von diesen Regeln sind Mitgliedschaftsereignisse. Ihr Abo kann Mitgliedschaftsereignisse sowohl von Gruppenbereichen, die von Ihrer Organisation verwaltet werden, als auch von Gruppenbereichen, die von externen Organisationen verwaltet werden, empfangen. Die Zustellung hängt jedoch davon ab, welche Organisation den Gruppenbereich verwaltet:
Von Ihrer Google Workspace-Organisation verwaltete Gruppenbereiche
Wenn eine Mitgliedschaftsänderung in einem Gruppenbereich auftritt, der von der Google Workspace-Organisation verwaltet wird, wird sie als Gruppenbereich-Ereignis gesendet.
Der Ressourcenname eines Gruppenbereich-Ereignisses hat das folgende Format:
spaces/{spaceId}/spaceEvents/{spaceEventId}
Von externen Organisationen verwaltete Gruppenbereiche
Wenn sich die Mitgliedschaft eines Nutzers, der von Ihrer Google Workspace-Organisation verwaltet wird, in einem Gruppenbereich ändert, der von einer externen Organisation verwaltet wird (z. B. ein externer benannter Gruppenbereich oder eine Direktnachricht, die von einem externen Nutzer erstellt wurde), empfängt Ihr Abo dieses Ereignis als Nutzerereignis.
Der Ressourcenname eines Nutzerereignisses hat das folgende Format:
users/{userId}/userEvents/{userEventId}
Weitere Informationen
- Übersicht über die Google Workspace Events API
- Abo erstellen
- Details zu einem Google Chat-Gruppenbereich-Ereignis abrufen
- Ereignisse aus einem Google Chat-Gruppenbereich auflisten