Google Chat-Oberflächen erstellen

Auf dieser Seite finden Sie eine Übersicht darüber, wie Sie Benutzeroberflächen für Google Workspace-Add‑ons erstellen, die Google Chat erweitern.

Zum Erstellen von Benutzeroberflächen für Chat-Apps verwenden Sie die folgenden Add‑on-Komponenten:

  • Trigger: Die Möglichkeiten, mit denen Google Chat-Nutzer eine Chat-App aufrufen können, z. B. indem sie sie einem Gruppenbereich hinzufügen oder ihr eine Nachricht senden.
  • Ereignisobjekte: Die Daten, die Chat-Apps von Triggern oder UI-Interaktionen erhalten.
  • Aktionen: Die Möglichkeiten, mit denen Chat-Apps auf Interaktionen reagieren können, z. B. durch Senden von Nachrichten oder Zurückgeben einer kartenbasierten Benutzeroberfläche.
Die Chat-App empfängt ein Ereignisobjekt von einem „Dem Gruppenbereich hinzugefügt“-Trigger.
Abbildung 1: Wenn ein Nutzer einem Gruppenbereich eine Chat-App hinzufügt, wird der Trigger In Gruppenbereich aufgenommen ausgelöst und ein Ereignisobjekt gesendet. Um mit einer Nachricht zu antworten, verarbeitet die Chat-App das Ereignisobjekt und gibt eine Aktion zurück, mit der die Nachricht erstellt wird.

Chat-Apps können Karten in den folgenden Benutzeroberflächen erstellen und anzeigen:

  • Nachrichten, die Text, statische oder interaktive Karten und Schaltflächen enthalten können.
  • Dialogfelder, die Karten sind, die in einem neuen Fenster geöffnet werden und Nutzer in der Regel auffordern, Informationen einzureichen.
  • Link-Vorschauen, die Karten sind, die eine Vorschau von Informationen zu einem externen Dienst enthalten.

Trigger

In diesem Abschnitt werden die Trigger erläutert, die Google Workspace-Add‑ons in Google Chat verwenden.

Trigger sind die spezifischen Möglichkeiten, mit denen Nutzer eine Chat-App über die Google Chat-Benutzeroberfläche aufrufen können, z. B. mit @-Erwähnungen oder App-Befehlen.

In der folgenden Tabelle sind die Google Chat-Trigger, eine Beschreibung und die typische Reaktion von Chat-Apps aufgeführt:

Trigger Beschreibung Typische Reaktion
In Gruppenbereich aufgenommen

Ein Nutzer fügt die Chat-App einem Gruppenbereich hinzu oder ein Google Workspace-Administrator installiert die Chat-App in Direktnachrichtenbereichen für Nutzer in seiner Organisation. Informationen zu von Administratoren installierten Chat-Apps finden Sie in der Google Workspace-Admin-Hilfe unter Marketplace-Apps in Ihrer Domain installieren.

 Die Chat-App sendet eine Onboarding-Nachricht, in der erklärt wird, was sie tut und wie Nutzer im Gruppenbereich mit ihr interagieren können.
Botschaft

Ein Nutzer interagiert auf eine der folgenden Arten mit der Chat-App in einer Nachricht:

  • Er sendet eine Nachricht in einem Direktnachrichtenbereich mit der Chat-App.
  • Er erwähnt die Chat-App in einem beliebigen Gruppenbereich mit @.
  • Er sendet eine Nachricht, die einen Link enthält, der dem URL-Muster für Link-Vorschauen entspricht.
  • Er gibt Text in das Mehrfachauswahlmenü eines selectionInput Widgets ein.
 Die Chat-App reagiert auf den Inhalt der Nachricht. Beispielsweise antwortet eine Chat-App auf den Slash-Befehl /about mit einer Nachricht, in der die Aufgaben erläutert werden, die die Chat-App ausführen kann.
Aus Gruppenbereich entfernt

Ein Nutzer entfernt die Chat-App aus einem Gruppenbereich oder ein Google Workspace-Administrator deinstalliert die Chat-App für einen Nutzer in seiner Organisation.

Nutzer können keine Chat-Apps entfernen, die von ihrem Administrator installiert wurden. Wenn ein Nutzer die Chat-App zuvor installiert hatte, bleibt sie installiert, unabhängig davon, ob ein Google Workspace Administrator versucht, sie zu deinstallieren.

 Die Chat-App entfernt alle für den Gruppenbereich konfigurierten eingehenden Benachrichtigungen (z. B. durch Löschen eines Webhooks) und löscht alle internen Daten. Chat-Apps können auf diesen Trigger nicht mit Nachrichten antworten, da sie kein Mitglied des Gruppenbereichs mehr sind.
App-Befehl

Ein Nutzer verwendet einen Chat-App Befehl.

 Die Chat-App reagiert auf den Befehl. Beispielsweise antwortet sie mit einer Nachricht oder öffnet ein Dialogfeld.

Im Gegensatz zu anderen Add‑ons müssen Sie alle Callback-Funktionen für diese Trigger mit der Google Chat API konfigurieren. Eine Anleitung finden Sie unter Chat-App konfigurieren.

Informationen zum Reagieren auf einen Trigger finden Sie in den folgenden Anleitungen:

Ereignisobjekte

Chat-Apps erhalten Ereignisobjekte, wenn ein Google Chat-Trigger ausgelöst wird oder wenn Google Chat-Nutzer mit einer Benutzeroberfläche der Chat-App interagieren (z. B. auf eine Schaltfläche klicken). Mit dem Ereignisobjekt können Sie Interaktionsdaten verwenden, um zu reagieren oder eine Benutzeroberfläche zu aktualisieren.

Informationen zum Verarbeiten von Ereignisobjekten finden Sie in den folgenden Anleitungen:

Weitere Informationen zu Add‑on-Ereignisobjekten in Google Chat und anderen Google Workspace-Anwendungen finden Sie unter Ereignisobjekte.

Chat-Aktionen

In diesem Abschnitt wird erläutert, wie Chat-Apps Add‑on-Aktionen verwenden können, um auf Nutzerinteraktionen zu reagieren.

Um mit einer Add‑on-Aktion zu reagieren, muss eine Chat-App innerhalb von 30 Sekunden antworten und die Antwort muss in dem Gruppenbereich veröffentlicht werden, in dem die Interaktion stattgefunden hat. Andernfalls muss die Chat-App die Authentifizierung einrichten und die Google Chat API aufrufen, um zu reagieren.

Chat-Apps können Interaktionen auf viele Arten verarbeiten und darauf reagieren. In vielen Fällen antworten Chat-Apps mit einer Nachricht. Chat-Apps können auch Informationen aus einer Datenquelle abrufen, die Informationen zum Ereignisobjekt aufzeichnen oder vieles mehr. Dieses Verarbeitungsverhalten definiert im Wesentlichen die Google Chat-App.

Um auf Nutzerinteraktionen zu reagieren, müssen Chat-Apps das entsprechende Ereignisobjekt verarbeiten und eines der folgenden JSON-Objekte zurückgeben:

In der folgenden Tabelle wird gezeigt, wie Chat-Apps mit Aktionen reagieren können. Chat-Apps können JSON-Objekte zurückgeben oder die Antwort mit Apps Script's AddOnResponseServiceerstellen.

Antwort der Chat-App Erforderliche Aktion zum Zurückgeben (JSON) Erforderliche Aktion zum Zurückgeben (Apps Script)
Nachricht senden oder aktualisieren. DataActions DataActionsResponse
Dialogfeld öffnen, aktualisieren oder schließen RenderActions ActionResponse
Informationen von einer Karte oder einem Dialogfeld erfassen, Auswahlmöglichkeiten basierend auf der Eingabe der Nutzer in ein Mehrfachauswahlmenü vorschlagen RenderActions ActionResponse
Vorschau von Links in Nachrichten, die Google Chat-Nutzer in einem Gruppenbereich senden DataActions DataActionsResponse

Mit der Google Chat API antworten

Anstatt eine Add‑on-Aktion zurückzugeben, müssen Chat-Apps möglicherweise die Google Chat API verwenden, um auf eine Interaktion zu reagieren. Chat-Apps müssen beispielsweise die Google Chat API aufrufen, um Folgendes auszuführen:

  • Nach 30 Sekunden auf eine Interaktion reagieren
  • Aufgaben außerhalb des Gruppenbereichs ausführen, in dem die Interaktion stattgefunden hat
  • Aufgaben in Google Chat ausführen, die nicht als Add‑on-Aktionen verfügbar sind Beispielsweise Gruppenbereiche auflisten, in denen ein Nutzer oder eine Chat-App Mitglied ist, oder Nutzer einem Gruppenbereich hinzufügen
  • Aufgaben im Namen des Google Chat-Nutzers ausführen (erfordert Nutzerauthentifizierung)

Wenn Sie nach 30 Sekunden auf ein Interaktionsereignis reagieren möchten, müssen Sie den Empfang eines Interaktionsereignisses innerhalb von 30 Sekunden bestätigen, indem Sie eine leere Antwort senden, wie hier gezeigt, um zu vermeiden, dass Nutzern eine Fehlermeldung angezeigt wird, die besagt, dass Ihre Chat-App nicht reagiert:

Node.js

async function onEvent(req, res) {
  // Trigger asynchronous job that will respond using the Google Chat API.
  ...

  // Respond with an empty response to the Google Chat platform.
  return res.send({});
};

Python

def on_event(event) -> dict:
  # Trigger asynchronous job that will respond using the Google Chat API.
  ...

  # Respond with an empty response to the Google Chat platform.
  return {}

Java

public String onEvent(JsonNode event) {
  // Trigger asynchronous job that will respond using the Google Chat API.
  ...

  // Respond with an empty response to the Google Chat platform.
  return "{}";
}

Apps Script

function onEvent(event) {
  // Trigger asynchronous job that will respond using the Google Chat API.
  ...

  // Respond with an empty response to the Google Chat platform.
  return null;
}

Informationen zum Authentifizieren und Aufrufen der Google Chat API finden Sie in der Übersicht zur Google Chat API.