Auf dieser Seite wird beschrieben, wie Google Chat-Apps Ereignisse in Google Chat empfangen und darauf reagieren können.
Ein Google Chat-Ereignis steht für eine Aktivität oder Änderung in Chat, z. B. eine neue Nachricht in einem Gruppenbereich. Ihre Chat-App kann Ereignisse verwenden, um zu verstehen, was passiert ist, und entsprechend reagieren.
Hier einige Beispiele für die Verwendung von Ereignissen:
- Neue Nachrichten in einem Gruppenbereich im Blick behalten und darauf reagieren, z. B. nach Schlüsselwörtern oder ‑formulierungen suchen.
- Senden Sie Nutzern, die dem Gruppenbereich beitreten, eine Willkommensnachricht, in der Sie die Richtlinien für den Gruppenbereich erläutern oder Tipps zur effektiven Nutzung der Chat App 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 So können Nutzer beispielsweise Nachrichten von Nutzern auf einer anderen Messaging-Plattform senden und empfangen, ohne Chat zu verlassen.
So funktionieren Ereignisse
Immer wenn etwas in Google Chat passiert, wird eine Google Chat API-Ressource erstellt, aktualisiert oder gelöscht. Chat verwendet Ereignisse, um Ihrer Chat-App Informationen zum Typ der 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. Mit Ereignistypen können Sie filtern und nur die Informationen erhalten, die Sie benötigen. Außerdem können Sie ähnliche Aktivitäten auf dieselbe Weise verarbeiten.
In der folgenden Tabelle sehen Sie, wie sich eine Aktivität in Chat auf eine zugehörige Chat API-Ressource auswirkt und welche Art von Ereignis Ihre Chat-App empfängt:
| Aktivität | Chat API-Ressource | Ereignistyp |
|---|---|---|
| Ein Nutzer postet eine Nachricht in einem Google Chat-Bereich. | Eine Message-Ressource wird erstellt. |
Neue Nachricht |
| Ein Nutzer wird 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 empfangen
Damit Ihre Chat-App Ereignisse empfangen kann, haben Sie folgende Möglichkeiten:
- Abonnieren Sie Ereignisse über die Google Workspace Events API, um Ereignisse zu empfangen, sobald sie eintreten.
- Rufen Sie die Chat API auf, um nach aktuellen Ereignissen zu suchen.
In der folgenden Tabelle werden die Unterschiede und Gründe für das Abfragen oder Abonnieren von Ereignissen erläutert:
| Ereignisse abonnieren | Ereignisse abfragen | |
|---|---|---|
| Anwendungsfälle |
|
|
| API | Google Workspace Events API | Chat API |
| Quelle von Ereignissen | Spaces, Nutzer und Google Workspace-Organisationen (-Entwicklervorschau) | Nur Gruppenbereiche |
| Unterstützte Ereignisse |
Eine Liste der unterstützten Ereignistypen finden Sie in der Google Workspace Events API-Dokumentation unter Ereignistypen zum Erstellen von Abos. |
Eine Liste der unterstützten Ereignistypen finden Sie in der Ressource spaceEvents in der Referenzdokumentation zur Chat API.
|
| 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. Beispiel-Nutzlasten finden Sie in der Referenzdokumentation. |
Beispiel: Ereignisse zu Mitgliedschaften in einem Space abfragen oder abonnieren
In diesem Beispiel möchte eine Chat-App Informationen zu Änderungen an Mitgliedern eines Chat-Gruppenbereichs erhalten. Im Bereich finden die folgenden Mitgliedschaftsaktivitäten statt:
- Ein Nutzer tritt dem Gruppenbereich bei. Dadurch wird eine
Membership-Ressource erstellt und ein Ereignis für ein neues Mitglied ausgelöst. - Ein Nutzer wird zum Bereichsmanager. Dadurch wird die
Membership-Ressource für den Nutzer aktualisiert und ein aktualisiertes Mitgliedereignis wird ausgelöst. - Ein Nutzer verlässt den Bereich. Dadurch wird die
Membership-Ressource für den Nutzer gelöscht und ein Ereignis zum Löschen eines Mitglieds wird ausgelöst.
Mitgliedschaftsereignisse abonnieren
Um Ereignisse in Echtzeit zu empfangen, ruft die Chat-App die Methode subscriptions.create() der Google Workspace Events API auf, um den Bereich 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 die Mitgliedschaft im Gruppenbereich ändert. Die Chat-App kann dann in Echtzeit auf die 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.
Neueste Mitgliedschaftsereignisse abfragen
Anstatt die Mitgliedschaftsereignisse zu empfangen, sobald sie eintreten, kann eine Chat-App die Chat API aufrufen, um die letzten Gruppenbereichsereignisse im Zusammenhang mit Mitgliedschaftsaktivitäten aufzulisten.
In Abbildung 3 ruft eine Chat-App die Methode spaces.spaceEvents.list() der Chat API auf, nachdem alle Mitgliedschaftsaktivitäten stattgefunden haben, und filtert die Anfrage nach neuen, aktualisierten und gelöschten Mitgliedschaftsereignissen. Die Chat API gibt eine Liste von spaceEvent-Ressourcen zurück, die die einzelnen Änderungen der Mitgliedschaft darstellen.
Die Chat-App kann dann auf Grundlage der letzten Aktivitäten 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
- Damit Mitgliedschaftsereignisse empfangen werden können, muss der Nutzer oder die Chat-App ein direktes Mitglied des Bereichs sein. Wenn sie indirekt über eine Google-Gruppe einem Gruppenbereich hinzugefügt, aktualisiert oder daraus entfernt wurden, erhält das Abo diese Mitgliedschaftsereignisse nicht. Informationen zur Funktionsweise von Google-Gruppenmitgliedschaften finden Sie unter Google-Gruppen zu Gruppenbereichen hinzufügen.
Nutzerabos
-
Bei Abonnements für Nutzer werden Ereignisse zu neuen Mitgliedern in Direktnachrichten oder unbenannten Gruppenchats (
google.workspace.chat.membership.v1.created) erst nach dem Posten der ersten Nachricht ausgelöst.
Kundenabos ( Entwicklervorschau)
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 des Developer Preview-Programms nicht streng durchgesetzt, aber in Zukunft (wird separat angekündigt).
- Mit einer Chat-App kann nur ein Kundenabo für eine bestimmte Google Workspace-Organisation erstellt werden. Eine Google Workspace-Organisation kann insgesamt bis zu fünf Kundenabos haben, die von verschiedenen Chat-Apps erstellt wurden.
Für Kundenabos gelten bei der Ereignisbereitstellung die folgenden allgemeinen Regeln:
- Space-Termine: Werden nur zugestellt, wenn der Termin in einem Space stattfindet, der von Ihrer Google Workspace-Organisation verwaltet wird.
- Nutzerereignisse: Werden nur bereitgestellt, 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 Art der Übermittlung hängt jedoch davon ab, welche Organisation den Gruppenbereich verwaltet:
Von Ihrer Google Workspace-Organisation verwaltete Bereiche
Wenn sich die Mitgliedschaft in einem Gruppenbereich ändert, der von der Google Workspace-Organisation verwaltet wird, wird dies als Gruppenbereichsereignis übermittelt.
Der Ressourcenname eines Bereichsereignisses 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. in einem externen benannten Gruppenbereich oder in einer Direktnachricht, die von einem externen Nutzer erstellt wurde), wird dieses Ereignis in Ihrem Abo als Nutzerereignis erfasst.
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-Gruppenbereichsereignis abrufen
- Ereignisse aus einem Google Chat-Gruppenbereich auflisten