Google Chat-Oberflächen erstellen

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

In Google Chat werden Add-ons für Nutzer als Google Chat-Apps angezeigt. Weitere Informationen finden Sie unter Google Chat erweitern – Übersicht.

Für die Erstellung von Chat-Oberflächen stehen die folgenden Add-on-Komponenten zur Verfügung:

  • Trigger: Möglichkeiten, wie Google Chat-Nutzer eine Chat-App aufrufen können, z. B. durch Hinzufügen zu einem Gruppenbereich oder Senden einer Nachricht.
  • Ereignisobjekte: Daten, die Chat-Apps von Triggern oder UI-Interaktionen erhalten.
  • Aktionen: Möglichkeiten, wie Chat-Apps auf Interaktionen reagieren können, z. B. das Senden von Nachrichten oder das Zurückgeben einer kardinalen Benutzeroberfläche.
Chat-App empfängt ein Ereignisobjekt von einem Trigger vom Typ „Zu Gruppenbereich hinzugefügt“
Abbildung 1: Wenn ein Nutzer einem Gruppenbereich eine Chat-App hinzufügt, wird der Trigger Zu Gruppenbereich hinzugefügt 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 sind Karten, die in einem neuen Fenster geöffnet werden und Nutzer in der Regel auffordern, Informationen einzureichen.
  • Linkvorschauen: Karten mit Informationen zu einem externen Dienst.

Trigger

In diesem Abschnitt werden die Trigger beschrieben, die Google Workspace-Add-ons in Google Chat verwenden.

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

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

Trigger Beschreibung Typische Antwort
Dem Gruppenbereich hinzugefügt

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

 Die Chat-App sendet eine Einführungsnachricht, in der erklärt wird, wozu die Funktion dient und wie Nutzer im Gruppenbereich damit interagieren können.
Botschaft

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

  • Mit der Chat-App wird eine Nachricht in einem Direktnachrichtenbereich gesendet.
  • @mentions die Chat-App in einem beliebigen Gruppenbereich.
  • Es wird eine Nachricht mit einem Link gesendet, der dem URL-Muster für Linkvorschauen entspricht.
  • Gibt Text in das Mehrfachauswahlmenü eines selectionInput-Widgets ein.
 Die Chat-App antwortet basierend auf dem Inhalt der Nachricht. Eine Chat-App antwortet beispielsweise auf den Befehl /about mit einer Nachricht, in der die Aufgaben beschrieben 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 bereits installiert hat, 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 räumt den internen Speicher frei. Chat-Apps können nicht mehr mit Nachrichten auf diesen Trigger antworten, da sie nicht mehr Mitglied des Gruppenbereichs sind.
App-Befehl

Ein Nutzer verwendet einen Schnellbefehl oder einen Slash-Befehl in der Chat-App.

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

Anders als bei anderen Google Workspace-Add-ons müssen Sie alle Callback-Funktionen für diese Trigger über die Google Chat API konfigurieren. Eine Anleitung finden Sie unter Google Chat-App konfigurieren.

Weitere Informationen zum Beantworten von Triggern finden Sie in den folgenden Anleitungen:

Ereignisobjekte

In diesem Abschnitt werden alle Elemente von Chat-Ereignisobjekten definiert und erläutert. Weitere Informationen finden Sie unter Ereignisobjekte.

Ereignisobjekt
commonEventObject object (CommonEventObject)
Ein Objekt mit Informationen, die für alle Ereignisobjekte gemeinsam sind, unabhängig von der Hostanwendung.
chat object (Chat)
Ein Objekt mit allen Informationen zu Chatinteraktionen.

Chat

Chat
chat.user object (User)
Der Google Chat-Nutzer, der mit der Chat App interagiert hat.
chat.space object (Space)
Der Chatbereich, in dem ein Nutzer mit der Chat-App interagiert hat.
chat.eventTime

string (Timestamp format)

Der Zeitpunkt, zu dem die Interaktion stattgefunden hat.

Union-Feld payload.

Für payload ist nur einer der folgenden Werte zulässig:
chat.messagePayload

object (MessagePayload)

Die Nutzlast, die Chat-Apps von einem Nachrichten-Trigger erhalten.
chat.addedToSpacePayload

object (AddedToSpacePayload)

Die Nutzlast, die Chat-Apps von einem Trigger vom Typ Zu Gruppenbereich hinzugefügt erhalten.
chat.removedFromSpacePayload

object (RemovedFromSpacePayload)

Die Nutzlast, die Chat-Apps von einem Trigger vom Typ Aus Gruppenbereich entfernt erhalten.
chat.buttonClickedPayload

object (ButtonClickedPayload)

Die Nutzlast, die Chat-Apps erhalten, wenn Nutzer in einer Nachricht oder auf einer Karte auf eine Schaltfläche klicken. Wenn ein Nutzer auf eine Schaltfläche klickt, um Informationen einzureichen, enthält das commonEventObject.formInputs-Objekt die vom Nutzer erfassten Werte. Weitere Informationen finden Sie unter Informationen von Google Chat-Nutzern erheben.
chat.widgetUpdatedPayload

object (WidgetUpdatedPayload)

Die Nutzlast, die Chat-Apps erhalten, wenn Nutzer Text in das Mehrfachauswahlmenü eines selectionInput-Widgets eingeben. Chat-Apps können dieses Ereignisobjekt verwenden, um vorgeschlagene Elemente aus einer dynamischen Datenquelle einzufügen. Wenn Sie beispielsweise Supportanfragen aus einer externen Datenquelle einfügen möchten, kann eine Chat-App die Datenquelle basierend auf dem abfragen, was der Nutzer in das Menü eingibt, und dann alle übereinstimmenden Supportanfragen als auswählbare Elemente zurückgeben.

Das CommonEventObject.parameters['autocomplete_widget_query']-Objekt enthält den Stringwert, den der Nutzer in das Menü eingibt.

chat.appCommandPayload

object (AppCommandPayload)

Die Nutzlast, die Chat-Apps erhalten, wenn ein Nutzer einen Befehl aus der Chat-App verwendet.

Nutzlast

Je nach Art der Interaktion enthält das Ereignis eine Nutzlast mit einer oder mehreren Chat API-Ressourcen.

Nachrichtennutzlast
MessagePayload
chat.messagePayload.message object (Message)
Die Chatnachricht, die das Ereignis ausgelöst hat.
chat.messagePayload.space object (Space)
Der Chatbereich, in dem ein Nutzer die Nachricht gesendet hat, die die Chat-App aufgerufen hat.

Zur Gruppenbereichsnutzlast hinzugefügt
AddedToSpacePayload
chat.addedToSpacePayload.space object (Space)
Der Chatbereich, dem der Nutzer die Chat App hinzugefügt oder installiert hat.

Wenn Administratoren Chat-Apps installieren, wird das Feld space.adminInstalled auf true gesetzt.

chat.addedToSpacePayload.interactionAdd boolean
Ob ein Nutzer der Chat-App über eine Nachricht einen Gruppenbereich hinzufügt. Beispiel: Er erwähnt die Chat-App oder verwendet einen Slash-Befehl. Wenn true, sendet Google Chat ein weiteres Ereignisobjekt mit einem messagePayload, das Informationen zur Nachricht enthält.

Aus der Gruppenbereichsnutzlast entfernt
RemovedFromSpacePayload
chat.removedFromSpacePayload.space object (Space)
Der Chat-Bereich, aus dem der Nutzer die Chat-App entfernt oder deinstalliert hat.

Wenn Administratoren Chat-Apps deinstallieren, wird das Feld space.adminInstalled auf false gesetzt.

Nutzlast für Klick auf Schaltfläche
ButtonClickedPayload
chat.buttonClickedPayload.message object (Message)
Die Chatnachricht, die die Schaltfläche enthält, auf die ein Nutzer geklickt hat.
chat.buttonClickedPayload.space object (Space)
Der Chatbereich, in dem der Nutzer in einer Chat-App-Nachricht auf eine Schaltfläche geklickt hat.
chat.buttonClickedPayload.isDialogEvent boolean
Ob der Nutzer auf die Schaltfläche geklickt hat, um mit einem Dialogfeld zu interagieren.
chat.buttonClickedPayload.dialogEventType enum (DialogEventType)
Wenn isDialogEvent true ist, der Interaktionstyp in einem Dialog.

Enum DialogEventType.

Für dialogEventType ist nur einer der folgenden Werte zulässig:
TYPE_UNSPECIFIED Standardwert. Nicht angegeben
REQUEST_DIALOG Ein Nutzer fordert einen Dialog an. Beispielsweise geben sie einen Befehl ein oder klicken in einer Nachricht auf eine Schaltfläche.
SUBMIT_DIALOG Ein Nutzer klickt in einem Dialogfeld auf ein interaktives Element. Ein Nutzer füllt beispielsweise Informationen in einem Dialogfeld aus und klickt auf eine Schaltfläche, um die Informationen zu senden.

Nutzlast für aktualisiertes Widget
WidgetUpdatedPayload
chat.widgetUpdatedPayload.space object (Space)
Der Chatbereich, in dem die Interaktion stattgefunden hat.

App-Befehlsnutzlast
AppCommandPayload
chat.appCommandPayload.appCommandMetadata object (AppCommandMetadata)
Metadaten dazu, welchen Befehl der Nutzer verwendet und wie er den Befehl ausgelöst hat.
chat.appCommandPayload.space object (Space)
Der Chatbereich, in dem ein Nutzer den Befehl verwendet hat.
chat.appCommandPayload.thread object (Thread)
Wenn die Interaktion in einem Chat-Thread stattgefunden hat, der Chat-Thread, in dem der Nutzer den Befehl verwendet hat.
chat.appCommandPayload.message object (Message)
Die Nachricht, die der Nutzer mit dem Befehl gesendet hat.
chat.appCommandPayload.configCompleteRedirectUri string
Wenn für den Befehl eine Autorisierung oder Konfiguration erforderlich ist, eine URL, auf die der Nutzer weitergeleitet werden soll, nachdem er den Vorgang außerhalb von Google Chat abgeschlossen hat.
chat.appCommandPayload.isDialogEvent boolean
Ob der Befehl ein Dialogfeld öffnet.
chat.appCommandPayload.dialogEventType enum (DialogEventType)
Die Art der Interaktion mit einem Dialogfeld.

Enum DialogEventType.

Für dialogEventType ist nur einer der folgenden Werte zulässig:
TYPE_UNSPECIFIED Standardwert. Nicht angegeben
REQUEST_DIALOG Ein Nutzer fordert einen Dialog an. Beispielsweise geben sie einen Befehl ein oder klicken in einer Nachricht auf eine Schaltfläche.
SUBMIT_DIALOG Ein Nutzer klickt in einem Dialogfeld auf ein interaktives Element. Ein Nutzer füllt beispielsweise Informationen in einem Dialogfeld aus und klickt auf eine Schaltfläche, um die Informationen zu senden.
App-Befehlsmetadaten
AppCommandMetadata
chat.appCommandPayload.appCommandMetadata.appCommandId

string (int64 format)

Die Befehls-ID.
chat.appCommandPayload.appCommandMetadata.appCommandType enum (AppCommandType)
Der Befehlstyp.

Enum AppCommandType.

Für AppCommandType ist nur einer der folgenden Werte zulässig:
APP_COMMAND_TYPE_UNSPECIFIED Standardwert. Nicht angegeben
SLASH_COMMAND Ein Nutzer verwendet den Befehl, indem er eine Nachricht sendet, die mit einem Schrägstrich / beginnt.

Chat-Aktionen

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

Damit eine Chat-App mit einer Add-on-Aktion antworten kann, muss sie innerhalb von 30 Sekunden reagieren und die Antwort muss im Gruppenbereich gepostet werden, in dem die Interaktion stattgefunden hat. Andernfalls muss die Chat-App die Authentifizierung einrichten und die Google Chat API aufrufen, um zu antworten.

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 einige Informationen aus einer Datenquelle abrufen, die Ereignisobjektinformationen aufzeichnen oder so ziemlich alles andere tun. Dieses Verarbeitungsverhalten ist im Wesentlichen das, was die Google Chat App definiert.

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

Gewünschte Antwort der Chat-App Erforderliche Aktion für die Rückgabe
Nachricht senden oder aktualisieren DataActions
Öffnen, aktualisieren oder schließen Sie ein Dialogfeld. RenderActions
Wenn Sie Informationen von einer Karte oder einem Dialogfeld erfassen möchten, können Sie Auswahlelemente basierend auf dem eingebenen Text in einem Mehrfachauswahlmenü vorschlagen. RenderActions
Vorschau von Links in Nachrichten, die Google Chat-Nutzer in einem Gruppenbereich senden. DataActions

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 zu tun:

  • Antworten Sie nach 30 Sekunden auf eine Interaktion.
  • 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 Sie können beispielsweise Gruppenbereiche auflisten, in denen ein Nutzer oder eine Chat-App Mitglied ist, oder Nutzer zu einem Gruppenbereich hinzufügen.
  • Aufgaben im Namen des Chat-Nutzers ausführen (erfordert Nutzerauthentifizierung).

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