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 entschieden haben, welche Arten von Ereignissen Sie benötigen, erstellen Sie ein Abo, um Ereignisse von Google Chat zu empfangen.

Sie können nicht nur Ereignisse abonnieren, sondern auch Ereignisse abfragen, indem Sie die Chat API aufrufen. Durch Aufrufen der Chat API können Sie Ereignisse regelmäßig abrufen oder Ereignisse nachholen, die Sie aufgrund eines Ausfalls bei einem Abo möglicherweise verpasst haben. 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 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.

Ressourcen, die Sie auf Ereignisse überwachen können

Damit Sie Ereignisse empfangen können, müssen Sie eine Chat-Ressource angeben, die überwacht werden soll. Diese wird als Zielressource des Abos bezeichnet.

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

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 Bereich als Zielressource und den Ereignistyp als google.workspace.chat.membership.v1.created an. Wenn Sie Ereignisse dazu erhalten möchten, wenn ein bestimmter Nutzer einem beliebigen Bereich 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 Abonnements von Bereichen und Abonnements von Nutzern unterstützt werden. Informationen zu Ausnahmen, die ein Ereignis auslösen, finden Sie unter Einschränkungen.

Batch-Ereignistypen (nur Ausgabe)

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

Wenn ein Nutzer beispielsweise 20 Nutzer gleichzeitig einem Gruppenbereich hinzufügt, erhält Ihre Chat-App möglicherweise ein Batch-Ereignis (google.workspace.chat.membership.v1.batchCreated). Die Ereignis-Payload 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. Daher müssen Sie beim Erstellen eines Abos keine Batch-Ereignisse angeben. 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:

Ereignisdaten

In diesem Abschnitt werden Ereignisdaten und Beispielnutzlasten für Ereignisse in 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 zur geänderten Google Workspace-Ressource. Wenn Sie beispielsweise Mitgliedschaftsereignisse in einem Bereich abonniert haben, enthält die Nutzlast für diese Ereignisse Informationen zur geänderten spaces.membership-Ressource.

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 Sie in der Ereignisnutzlast erhalten möchten.

In der folgenden Tabelle finden Sie Beispiele für JSON-Nutzlasten für ein Abo des Chat-Bereichs spaces/AAAABBBBBB. Für jedes Ereignis, das das Abo empfängt, wird die Nutzlast im Feld data des Ereignisses angezeigt:

{
    "message":
    {
        "name": "spaces/SPACE_ID/messages/MESSAGE_ID",
        "sender":
        {
            "name": "users/USER_ID",
            "type": "HUMAN"
        },
        "createTime": "2023-09-07T21:37:36.260127Z",
        "text": "Hello world",
        "thread":
        {
            "name": "spaces/SPACE_ID/threads/THREAD_ID"
        },
        "space":
        {
            "name": "spaces/SPACE_ID"
        },
        "argumentText": "Hello world"
    }
}
      

{
    "message":
    {
        "name": "spaces/SPACE_ID/messages/MESSAGE_ID"
    }
}
      

{
    "membership":
    {
        "name": "spaces/SPACE_ID/members/MEMBER_ID",
        "state": "JOINED",
        "member":
        {
            "name": "users/USER_ID",
            "type": "HUMAN"
        },
        "createTime": "1970-01-01T00:00:00Z",
        "role": "ROLE_MANAGER"
    }
}
      

{
    "membership":
    {
        "name": "spaces/SPACE_ID/members/MEMBER_ID"
    }
}
      

{
    "space":
    {
        "name": "spaces/SPACE_ID",
        "displayName": "Cymbal Sales",
        "spaceThreadingState": "THREADED_MESSAGES",
        "spaceType": "SPACE",
        "spaceDetails":
        {
            "description": "Sales team for Cymbal Labs."
        },
        "spaceHistoryState": "HISTORY_ON"
    }
}
      

{
    "space":
    {
        "name": "spaces/SPACE_ID"
    }
}
      

{
    "memberships": [
        {
          "membership": {
            "name": "spaces/SPACE_ID/members/MEMBER_ID",
            "state": "JOINED",
            "member":
            {
                "name": "users/USER_ID",
                "type": "HUMAN"
            },
            "createTime": "1970-01-01T00:00:00Z",
            "role": "ROLE_MEMBER"
          }
        },
        {
          "membership": {
            "name": "spaces/SPACE_ID/members/MEMBER_ID",
            "state": "JOINED",
            "member":
            {
                "name": "users/USER_ID",
                "type": "HUMAN"
            },
            "createTime": "1970-01-01T00:00:00Z",
            "role": "ROLE_MEMBER"
          }
        }
    ]
}
      

{
    "memberships": [
        {
          "membership": {
            "name": "spaces/SPACE_ID/members/MEMBER_ID"
          }
        },
        {
          "membership": {
            "name": "spaces/SPACE_ID/members/MEMBER_ID"
          }
        }
    ]
}
      

{
    "reaction":
    {
        "name": "spaces/SPACE_ID/messages/MESSAGE_ID/reactions/REACTION_ID",
        "user":
        {
            "name": "users/USER_ID",
            "type": "HUMAN"
        },
        "emoji":
        {
            "unicode": "😊"
        }
    }
}
      

{
    "reaction":
    {
        "name": "spaces/SPACE_ID/messages/MESSAGE_ID/reactions/REACTION_ID"
    }
}
      

{
    "reactions": [
        {
          "reaction": {
            "name": "spaces/SPACE_ID/messages/MESSAGE_ID/reactions/REACTION_ID",
            "user":
            {
                "name": "users/USER_ID",
                "type": "HUMAN"
            },
            "emoji":
            {
                "unicode": "😊"
            }
          }
        },
        {
          "reaction": {
            "name": "spaces/SPACE_ID/messages/MESSAGE_ID/reactions/REACTION_ID",
            "user":
            {
                "name": "users/USER_ID",
                "type": "HUMAN"
            },
            "emoji":
            {
                "unicode": "😸"
            }
          }
        }
    ]
}
      

{
    "reactions": [
      {
        "reaction": {
            "name": "spaces/SPACE_ID/messages/MESSAGE_ID/reactions/REACTION_ID"
        },
        "reaction": {
            "name": "spaces/SPACE_ID/messages/MESSAGE_ID/reactions/REACTION_ID",
        }
      }
    ]
}
      

• 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.
• 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.

Weitere Informationen

• Struktur von Google Workspace-Ereignissen
• OAuth-Bereiche auswählen
• Abo erstellen, um Chat-Ereignisse zu empfangen