Google Chat-Ereignisse abonnieren

Auf dieser Seite werden die Google Chat-Ereignisse beschrieben, die eine Google Chat-App mit der Google Workspace Events API abonnieren kann. Nachdem Sie sich entschieden haben, welche Ereignistypen Sie benötigen, erstellen Sie ein Abo, um Ereignisse von Google Chat zu erhalten.

Sie können nicht nur Ereignisse abonnieren, sondern auch durch Aufrufen der Chat API nach Ereignissen fragen. Wenn du die Chat API aufrufst, kannst du Ereignisse regelmäßig abrufen oder dir Ereignisse ansehen, die du aufgrund eines Ausfalls verpasst hast. Informationen dazu, wie Sie Chat-Ereignisse empfangen und darauf reagieren können, finden Sie in der Chat-Dokumentation unter Mit Ereignissen aus Google Chat arbeiten.

Unterstützte Chat-Ereignisse

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 am Gruppenbereich, den Sie abonniert haben, z. B. ein aktualisierter Name oder eine aktualisierte Beschreibung des Gruppenbereichs.

Ressourcen, die Sie auf Ereignisse überwachen können

Wenn Sie Ereignisse empfangen möchten, müssen Sie eine zu überwachende Chatressource angeben. Diese wird als Zielressource des Abos bezeichnet.

Die Google Workspace Events API unterstützt die folgenden Zielressourcen für Google Chat:

Zielressource Format Einschränkungen
Leerzeichen

//chat.googleapis.com/spaces/SPACE

Dabei ist SPACE die ID im Ressourcennamen der Chat API-Ressource space. Sie können die ID aus der URL des Gruppenbereichs oder mit der Methode spaces.list() abrufen.

 Der Google Chat-Nutzer, der das Abo autorisiert, muss über sein Google Workspace- oder Google-Konto Mitglied des Gruppenbereichs sein.
Alle Gruppenbereiche für einen Nutzer

//chat.googleapis.com/spaces/-

 Das Abo empfängt nur Ereignisse für die Gruppenbereiche, in denen der Nutzer über sein Google Workspace- oder Google-Konto Mitglied ist.
Nutzer

//cloudidentity.googleapis.com/users/USER

Dabei ist USER die ID im Ressourcennamen der Chat API-Ressource user. Weitere Informationen finden Sie unter Google Chat-Nutzer identifizieren und angeben.

Das Abo empfängt nur Ereignisse zu dem Nutzer, der das Abo autorisiert hat. Ein Nutzer kann kein Abo im Namen anderer Nutzer autorisieren.

Ereignistypen zum Erstellen von Abos

Wenn Sie ein Abo erstellen, geben Sie im Feld eventTypes[] an, welche Arten von Ereignissen Sie erhalten möchten. Ereignistypen werden gemäß der CloudEvents-Spezifikation formatiert, z. B. google.workspace.APPLICATION.RESOURCE.VERSION.ACTION.

Wenn Sie beispielsweise Ereignisse zu Nutzern erhalten möchten, die einem Chatbereich beitreten, geben Sie den Chatbereich als Zielressource und den Ereignistyp google.workspace.chat.membership.v1.created an. Wenn Sie Ereignisse dazu erhalten möchten, dass ein bestimmter Nutzer einem Gruppenbereich beitritt, geben Sie den Nutzer als Zielressource und den Ereignistyp als 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 von Nutzern unterstützt werden. Informationen zu Ausnahmen, die das Auslösen eines Ereignisses betreffen, 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 wird 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
Dem Gruppenbereich wird ein Mitglied hinzugefügt.

google.workspace.chat.membership.v1.created

space.membership
Ein Mitglied wird 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 in 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

Batch-Ereignistypen (nur Ausgabe)

Neben den Ereignistypen, die Sie abonnieren, erhält Ihre Chat-App möglicherweise auch Batch-Ereignisse. Ein Batch-Ereignis ist ein Ereignis, das viele Ereignisse desselben Typs darstellt, die in kurzer Zeit auftreten. Die Nutzlast eines Batchereignisses enthält eine Liste aller geänderten Ressourcen.

Wenn ein Nutzer beispielsweise einem Gruppenbereich gleichzeitig 20 Nutzer hinzufügt, erhält 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 die Mitglieder dem Gruppenbereich hinzugefügt hat.

Sie erhalten ein Batch-Ereignis für jeden Ereignistyp, den Sie abonnieren. Sie müssen also keine Batch-Ereignisse angeben, wenn Sie ein Abo erstellen. Wenn Sie beispielsweise neue Reaktionen abonnieren (google.workspace.chat.reaction.v1.created), wird Ihre Chat-App automatisch so konfiguriert, dass sie Batch-Reaktionsereignisse (google.workspace.chat.reaction.v1.batchCreated) empfängt.

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

Batch-Ereignistyp Format
Es werden mehrere Nachrichten gepostet.

google.workspace.chat.message.v1.batchCreated
Es werden mehrere Nachrichten aktualisiert.

google.workspace.chat.message.v1.batchUpdated
Mehrere Nachrichten werden 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 wurden mehrere Mitglieder hinzugefügt oder der abonnierte Nutzer wurde mehreren Gruppenbereichen hinzugefügt.

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

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

google.workspace.chat.membership.v1.batchDeleted
Für den Gruppenbereich gibt es mehrere Updates.

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 Google Chat empfängt, enthält das Feld data die Nutzlast für das Ereignis. Diese Payload enthält Informationen zur geänderten Google Workspace-Ressource. Wenn Sie beispielsweise Mitgliedschaftsereignisse in einem Gruppenbereich abonniert haben, enthält die Nutzlast für diese Ereignisse Informationen zur geänderten Ressource spaces.membership.

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 enthalten sein 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 die Nachricht „Hallo Welt“ in den Gruppenbereich.

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"
    }
}
Ressourcendaten sind ausgeschlossen.
{
    "message":
    {
        "name": "spaces/AAAABBBBBB/messages/CCCCCCCCC.DDDDDDDDD"
    }
}
Ein Nutzer wird zum Administrator eines 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"
    }
}
Ressourcendaten sind ausgeschlossen.
{
    "membership":
    {
        "name": "spaces/AAAABBBBBB/members/1234567890987654321"
    }
}
Ein Nutzer aktualisiert die Beschreibung des Gruppenbereichs in „Sales team for 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"
    }
}
Ressourcendaten sind ausgeschlossen.
{
    "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"
          }
        }
    ]
}
Ressourcendaten sind ausgeschlossen.
{
    "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": "😊"
        }
    }
}
Ressourcendaten werden nicht berücksichtigt.
{
    "reaction":
    {
        "name": "spaces/AAAABBBBBB/messages/123456789.123456789/reactions/1111111111111111.222222222222222"
    }
}
Nutzer reagieren auf eine Nachricht mit dem Emoji 😊 und dem Emoji 😸. 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": "😸"
            }
          }
        }
    ]
}
Ressourcendaten werden nicht berücksichtigt
{
    "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.
  • Damit der Nutzer Mitgliedschaftsereignisse erhält, muss er ein direktes Mitglied des Gruppenbereichs sein. Wenn ein Nutzer einem Gruppenbereich indirekt über eine Google-Gruppe hinzugefügt, aktualisiert oder entfernt wurde, werden diese Mitgliedschaftsereignisse nicht an das Abo gesendet. Informationen zur Funktionsweise von Google-Gruppenmitgliedschaften finden Sie unter Google-Gruppen zu Gruppenbereichen hinzufügen.