Google Chat-Ereignisse abonnieren

Auf dieser Seite werden die Google Chat-Ereignisse beschrieben, die von einer Google Chat-App mit der Google Workspace Events API abonniert werden können. Nachdem Sie entschieden haben, welche Arten von Ereignissen Sie benötigen, erstellen Sie ein Abo, um Ereignisse von Google Chat zu empfangen.

Sie können Ereignisse nicht nur abonnieren, sondern auch die Chat API aufrufen. Mit dem Aufruf der Chat API können Sie regelmäßig Ereignisse abrufen oder Ereignisse nachholen, die Sie aufgrund eines Ausfalls bei einem Abo möglicherweise verpasst haben. Informationen dazu, wie Sie Chatereignisse empfangen und darauf antworten können, finden Sie in der Chat-Dokumentation unter Mit Ereignissen aus Google Chat arbeiten.

Unterstützte Chat-Zielressourcen

Die Google Workspace Events API unterstützt Abos für:

  • Gruppenbereiche, dargestellt als space-Ressourcen
  • Nutzer, dargestellt als user-Ressourcen der Cloud Identity API

Unterstützte Chatereignisse

Mit Google Workspace-Abos können Sie Ereignisse zu den folgenden Arten von Änderungen in Google Chat erhalten:

  • Neue, aktualisierte oder gelöschte Nachrichten im Gruppenbereich
  • Neue oder entfernte Reaktionen auf eine Nachricht.
  • Neue, aktualisierte oder entfernte Mitglieder im Gruppenbereich
  • Änderungen an dem von Ihnen abonnierten Gruppenbereich, z. B. ein aktualisierter Name oder eine aktualisierte Beschreibung des Gruppenbereichs

Ereignistypen zum Erstellen von Abos

Beim Erstellen eines Abos kannst du im Feld eventTypes[] angeben, welche Arten von Ereignissen du erhalten möchtest. Ereignistypen werden gemäß der CloudEvents-Spezifikation formatiert, z. B. google.workspace.APPLICATION.RESOURCE.VERSION.ACTION.

Wenn Sie beispielsweise Ereignisse über Nutzer erhalten möchten, die einem Chatbereich beitreten, geben Sie den Bereich als Zielressource und den Ereignistyp google.workspace.chat.membership.v1.created an. Wenn Sie Ereignisse zu einem bestimmten Nutzer empfangen möchten, der einen beliebigen Bereich einnimmt, geben Sie den Nutzer als Zielressource und den Ereignistyp google.workspace.chat.membership.v1.created an. Weitere Informationen zur Funktionsweise von Ereignissen finden Sie unter Struktur von Google Workspace-Ereignissen.

In der folgenden Tabelle sehen Sie, welche Ereignistypen für Abos von Gruppenbereichen und Abos für Nutzer unterstützt werden. Weitere Informationen zu Ausnahmen dafür, was ein Ereignis auslöst, finden Sie unter Einschränkungen.

Ereignistyp Format Ressourcendaten
Abos für Gruppenbereiche  
Eine Nachricht wird gepostet.

google.workspace.chat.message.v1.created

space.message
Eine Nachricht wird aktualisiert.

google.workspace.chat.message.v1.updated

space.message
Eine Nachricht wurde gelöscht.

google.workspace.chat.message.v1.deleted

space.message
Eine Reaktion wird erstellt.

google.workspace.chat.reaction.v1.created

space.message.reaction
Eine Reaktion wird gelöscht.

google.workspace.chat.reaction.v1.deleted

space.message.reaction
Ein Mitglied wird dem Gruppenbereich hinzugefügt.

google.workspace.chat.membership.v1.created

space.membership
Ein Mitglied wurde im Gruppenbereich aktualisiert.

google.workspace.chat.membership.v1.updated

space.membership
Ein Mitglied wird aus dem Gruppenbereich entfernt.

google.workspace.chat.membership.v1.deleted

space.membership
Der Gruppenbereich wird aktualisiert.

google.workspace.chat.space.v1.updated

space
Der Gruppenbereich wird gelöscht.

google.workspace.chat.space.v1.deleted

space
Abos für Nutzer  
Der Nutzer wird Mitglied eines Gruppenbereichs.

Nicht alle neuen Mitglieder lösen Ereignisse aus. Weitere Informationen finden Sie unter Einschränkungen.

google.workspace.chat.membership.v1.created

space.membership
Die Mitgliedschaft des Nutzers bei einem Gruppenbereich wird aktualisiert.

google.workspace.chat.membership.v1.updated

space.membership
Der Nutzer wird als direktes Mitglied eines Gruppenbereichs entfernt.

google.workspace.chat.membership.v1.deleted

space.membership

Batchereignistypen (nur Ausgabe)

Neben den von Ihnen abonnierten Ereignistypen empfängt Ihre Chat-App möglicherweise auch Batchereignisse. Ein Batch-Ereignis ist ein Ereignis, das viele Ereignisse desselben Typs darstellt, die in einem kurzen Zeitraum auftreten. Die Nutzlast eines Batchereignisses enthält eine Liste aller geänderten Ressourcen.

Wenn ein Nutzer beispielsweise einem Gruppenbereich gleichzeitig 20 Nutzer hinzufügt, empfängt Ihre Chat-App möglicherweise ein Batch-Ereignis (google.workspace.chat.membership.v1.batchCreated). Die Ereignisnutzlast enthält eine Liste aller neuen Membership-Ressourcen, die erstellt wurden, als der Nutzer dem Gruppenbereich die Mitglieder hinzugefügt hat.

Sie erhalten ein Batchereignis für jeden Ereignistyp, den Sie abonnieren. Sie müssen also beim Erstellen eines Abos keine Batchereignisse angeben. Wenn Sie beispielsweise neue Reaktionen abonnieren (google.workspace.chat.reaction.v1.created), wird Ihre Chat-App automatisch für den Empfang von Batch-Reaktionsereignissen (google.workspace.chat.reaction.v1.batchCreated) konfiguriert.

In der folgenden Tabelle sind die möglichen Batchereignisse für ein Abo aufgeführt:

Batch-Ereignistyp Format
Es werden mehrere Nachrichten gepostet.

google.workspace.chat.message.v1.batchCreated
Mehrere Nachrichten werden aktualisiert.

google.workspace.chat.message.v1.batchUpdated
Es werden mehrere Nachrichten gelöscht.

google.workspace.chat.message.v1.batchDeleted
Es werden mehrere Reaktionen erstellt.

google.workspace.chat.reaction.v1.batchCreated
Mehrere Reaktionen werden gelöscht.

google.workspace.chat.reaction.v1.batchDeleted
Dem abonnierten Gruppenbereich werden mehrere Mitglieder hinzugefügt oder der abonnierte Nutzer wurde mehreren Gruppenbereichen hinzugefügt.

google.workspace.chat.membership.v1.batchCreated
Mehrere Mitgliedschaften werden im Gruppenbereich mit Abo oder für den jeweiligen Nutzer aktualisiert.

google.workspace.chat.membership.v1.batchUpdated
Es wurden mehrere Mitglieder aus dem abonnierten Gruppenbereich entfernt oder der abonnierte Nutzer wurde aus mehreren Gruppenbereichen entfernt.

google.workspace.chat.membership.v1.batchDeleted
Der Gruppenbereich hat mehrere Aktualisierungen.

google.workspace.chat.space.v1.batchUpdated

Ereignisdaten

In diesem Abschnitt werden Ereignisdaten und Beispielnutzlasten für Ereignisse in Google Chat beschrieben.

Wenn Ihr Google Workspace-Abo ein Ereignis von Chat empfängt, enthält das Feld data die Nutzlast für das Ereignis. Diese Nutzlast enthält Informationen über die Google Workspace-Ressource, die sich geändert hat. Wenn Sie beispielsweise Mitgliedschaftsereignisse in einem Gruppenbereich abonniert haben, enthält die Nutzlast für diese Ereignisse Informationen zur Ressource spaces.membership, die sich geändert hat.

Ressourcendaten in der Ereignisnutzlast

Wenn Sie ein Abo erstellen, können Sie angeben, ob die Nutzlast Details zur Ressource oder nur den Namen der Ressource enthalten soll. Wenn Sie beispielsweise Ereignisse zu Mitgliedern in einem Chatbereich erhalten möchten, können Sie angeben, welche Felder einer Mitgliedschaftsressource in der Ereignisnutzlast empfangen werden sollen.

Die folgende Tabelle enthält Beispiele für JSON-Nutzlasten für ein Abo des Chatbereichs spaces/AAAABBBBBB. Für jedes Ereignis, das das Abo empfängt, wird die Nutzlast im Feld data des Ereignisses angezeigt:

Beispiel Ereignistyp JSON-Nutzlast

Ein Nutzer postet eine Nachricht mit dem Text „Hallo Welt“.

google.workspace.chat.message.v1.created

Enthält Ressourcendaten
{
    "message":
    {
        "name": "spaces/AAAABBBBBB/messages/CCCCCCCCC.DDDDDDDDD",
        "sender":
        {
            "name": "users/1234567890987654321",
            "type": "HUMAN"
        },
        "createTime": "2023-09-07T21:37:36.260127Z",
        "text": "Hello world",
        "thread":
        {
            "name": "spaces/AAAABBBBBB/threads/EEEEEEEEEEEE"
        },
        "space":
        {
            "name": "spaces/AAAABBBBBB"
        },
        "argumentText": "Hello world"
    }
}
Schließt Ressourcendaten aus
{
    "message":
    {
        "name": "spaces/AAAABBBBBB/messages/CCCCCCCCC.DDDDDDDDD"
    }
}
Ein Nutzer wird zum Administrator des Gruppenbereichs.

google.workspace.chat.membership.v1.updated

Enthält Ressourcendaten
{
    "membership":
    {
        "name": "spaces/AAAABBBBBB/members/1234567890987654321",
        "state": "JOINED",
        "member":
        {
            "name": "users/1234567890987654321",
            "type": "HUMAN"
        },
        "createTime": "1970-01-01T00:00:00Z",
        "role": "ROLE_MANAGER"
    }
}
Schließt Ressourcendaten aus
{
    "membership":
    {
        "name": "spaces/AAAABBBBBB/members/1234567890987654321"
    }
}
Ein Nutzer aktualisiert die Beschreibung des Gruppenbereichs in „Vertriebsteam für Cymbal Labs“. google.workspace.chat.space.v1.updated
Enthält Ressourcendaten
{
    "space":
    {
        "name": "spaces/AAAABBBBBB",
        "displayName": "Cymbal Sales",
        "spaceThreadingState": "THREADED_MESSAGES",
        "spaceType": "SPACE",
        "spaceDetails":
        {
            "description": "Sales team for Cymbal Labs."
        },
        "spaceHistoryState": "HISTORY_ON"
    }
}
Schließt Ressourcendaten aus
{
    "space":
    {
        "name": "spaces/AAAABBBBBB"
    }
}
Dem Gruppenbereich wurden zwei Chat-Nutzer gleichzeitig hinzugefügt. google.workspace.chat.membership.v1.batchCreated
Enthält Ressourcendaten
{
    "memberships": [
        {
          "membership": {
            "name": "spaces/AAAABBBBBB/members/1234567890987654321",
            "state": "JOINED",
            "member":
            {
                "name": "users/1234567890987654321",
                "type": "HUMAN"
            },
            "createTime": "1970-01-01T00:00:00Z",
            "role": "ROLE_MEMBER"
          }
        },
        {
          "membership": {
            "name": "spaces/AAAABBBBBB/members/987654321234567890",
            "state": "JOINED",
            "member":
            {
                "name": "users/987654321234567890",
                "type": "HUMAN"
            },
            "createTime": "1970-01-01T00:00:00Z",
            "role": "ROLE_MEMBER"
          }
        }
    ]
}
Schließt Ressourcendaten aus
{
    "memberships": [
        {
          "membership": {
            "name": "spaces/AAAABBBBBB/members/1234567890987654321"
          }
        },
        {
          "membership": {
            "name": "spaces/AAAABBBBBB/members/98765432123456789019"
          }
        }
    ]
}
Ein Nutzer reagiert auf eine Nachricht mit dem Emoji 😊. google.workspace.chat.reaction.v1.created
Enthält Ressourcendaten
{
    "reaction":
    {
        "name": "spaces/AAAABBBBBB/messages/123456789.123456789/reactions/1111111111111111.222222222222222",
        "user":
        {
            "name": "users/1234567890987654321",
            "type": "HUMAN"
        },
        "emoji":
        {
            "unicode": "😊"
        }
    }
}
Lässt Ressourcendaten aus
{
    "reaction":
    {
        "name": "spaces/AAAABBBBBB/messages/123456789.123456789/reactions/1111111111111111.222222222222222"
    }
}
Nutzer reagieren auf eine Nachricht mit den 😊-Emojis und DAGs-Emojis. google.workspace.chat.reaction.v1.batchCreated
Enthält Ressourcendaten
{
    "reactions": [
        {
          "reaction": {
            "name": "spaces/AAAABBBBBB/messages/123456789.123456789/reactions/1111111111111111.222222222222222",
            "user":
            {
                "name": "users/1234567890987654321",
                "type": "HUMAN"
            },
            "emoji":
            {
                "unicode": "😊"
            }
          }
        },
        {
          "reaction": {
            "name": "spaces/AAAABBBBBB/messages/123456789.123456789/reactions/3333333333333333.444444444444444",
            "user":
            {
                "name": "users/98765431234564321",
                "type": "HUMAN"
            },
            "emoji":
            {
                "unicode": "😸"
            }
          }
        }
    ]
}
Lässt Ressourcendaten aus
{
    "reactions": [
      {
        "reaction": {
            "name": "spaces/AAAABBBBBB/messages/123456789.123456789/reactions/1111111111111111.222222222222222"
        },
        "reaction": {
            "name": "spaces/AAAABBBBBB/messages/123456789.123456789/reactions/3333333333333333.444444444444444",
        }
      }
    ]
}

Beschränkungen
  • Bei Abos von Nutzern 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.
  • Änderungen am Gruppenbereichsverlauf lösen keine aktualisierten Gruppenbereichsereignisse aus (Ereignistyp: google.workspace.chat.spaces.v1.updated).
  • Um Mitgliedschaften zu empfangen, muss der Nutzer ein direktes Mitglied des Gruppenbereichs sein. Wenn ein Nutzer über eine Google-Gruppe indirekt einem Gruppenbereich hinzugefügt, aktualisiert oder entfernt wurde, werden diese Mitgliedschaftsereignisse nicht an das Abo gesendet. Informationen zur Funktionsweise von Google-Gruppenmitgliedschaften finden Sie unter Google-Gruppe zu einem Gruppenbereich hinzufügen.