Nutzerinteraktionen empfangen und darauf reagieren

Auf dieser Seite wird beschrieben, wie Ihre Google Chat App Nutzerinteraktionen empfangen und darauf reagieren kann. Sie wird auch als Google Chat App-Interaktionsereignisse bezeichnet.

Auf dieser Seite wird Folgendes beschrieben:

  • Konfigurieren Sie Ihre Chat-App so, dass sie Interaktionsereignisse empfängt.
  • Verarbeiten Sie das Interaktionsereignis in Ihrer Infrastruktur.
  • Reagieren Sie gegebenenfalls auf Interaktionsereignisse.

Vorbereitung

Eine Google Chat App mit aktivierten interaktiven Funktionen. Führen Sie zum Erstellen einer interaktiven Chat-App eine der folgenden Kurzanleitungen aus, die auf der gewünschten App-Architektur basieren:

Arten von Interaktionsereignissen

Ein Google Chat-App-Interaktionsereignis steht für jede Aktion, die ein Nutzer ausführt, um eine Chat-App aufzurufen oder mit ihr zu interagieren, z. B. eine Chat-App zu erwähnen oder zu einem Gruppenbereich hinzuzufügen.

Wenn Nutzer mit einer Chat-App interagieren, sendet Google Chat der Chat-App ein Interaktionsereignis, das in der Chat API als Typ Event dargestellt wird. Die Chat-App kann das Ereignis verwenden, um die Interaktion zu verarbeiten, und optional mit einer Nachricht antworten.

Für jede Art von Nutzerinteraktion sendet Google Chat eine andere Art von Interaktionsereignis, damit Ihre Chat-App jeden Ereignistyp entsprechend verarbeiten kann. Der Typ des Interaktionsereignisses wird mit dem Objekt eventType dargestellt.

In Google Chat wird der Ereignistyp ADDED_TO_SPACE beispielsweise für jede Interaktion verwendet, bei der ein Nutzer der Chat-App einen Gruppenbereich hinzufügt. So kann die Chat-App sofort mit einer Begrüßungsnachricht im Gruppenbereich antworten.

Die Chat-App sendet eine Willkommensnachricht.
Abbildung 1: Wenn ein Nutzer einem Gruppenbereich eine Chat-App hinzufügt, erhält die Chat-App ein ADDED_TO_SPACE Interaktionsereignis, das von der Chat-App verarbeitet wird, um eine Begrüßungsnachricht im Gruppenbereich zu senden.

Die folgende Tabelle zeigt häufige Nutzerinteraktionen, die Art des Interaktionsereignisses, das die Chat-Apps empfangen, und wie Chat-Apps normalerweise reagieren:

Nutzerinteraktion eventType Typische Antwort aus einer Chat-App
Ein Nutzer ruft eine Chat-App auf, indem er sie @erwähnt oder einen Slash-Befehl verwendet. MESSAGE 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.
Ein Nutzer fügt einem Gruppenbereich eine Chat-App hinzu. ADDED_TO_SPACE Die Chat-App sendet eine Onboarding-Nachricht, in der ihre Funktion erläutert wird und wie Nutzer im Gruppenbereich damit interagieren können.
Ein Nutzer entfernt eine Chat-App aus einem Gruppenbereich. REMOVED_FROM_SPACE Die Chat-App entfernt alle eingehenden Benachrichtigungen, die für den Bereich konfiguriert sind, z. B. das Löschen eines Webhooks, und gibt den gesamten internen Speicher frei.
Ein Nutzer klickt in einer Nachricht, einem Dialogfeld oder auf der Startseite der Chat-App auf einer Karte. CARD_CLICKED Die Chat-App verarbeitet und speichert entweder alle Daten, die der Nutzer gesendet hat, oder gibt eine andere Karte zurück.
Ein Nutzer öffnet die Startseite der Chat-App, indem er in einer 1:1-Nachricht auf den Tab Startseite klickt. APP_HOME Die Chat-App gibt eine statische oder interaktive Karte von der Startseite zurück.
Ein Nutzer sendet über die Startseite der Chat App ein Formular. SUBMIT_FORM Die Chat-App verarbeitet und speichert alle vom Nutzer eingereichten Daten oder gibt eine andere Karte zurück.

Eine Liste aller unterstützten Interaktionsereignisse finden Sie in der EventType-Referenzdokumentation.

Interaktionsereignisse aus Dialogen

Wenn in der Chat-App Dialogfelder geöffnet werden, enthält das Interaktionsereignis die folgenden zusätzlichen Informationen, die Sie zum Verarbeiten einer Antwort verwenden können:

  • isDialogEvent ist auf true festgelegt.
  • Mit DialogEventType wird angegeben, ob die Interaktion das Öffnen eines Dialogfelds auslöst, Informationen aus einem Dialogfeld sendet oder ein Dialogfeld schließt.

In der folgenden Tabelle sind die gängigen Interaktionen mit Dialogen, die entsprechenden Dialogereignistypen und eine Beschreibung der typischen Reaktion von Chat-Apps aufgeführt:

Nutzerinteraktion mit einem Dialogfeld Dialogfeldereignistyp Typische Antwort
Ein Nutzer löst eine Dialoganfrage aus. Beispielsweise verwendet er einen Befehl mit einem Schrägstrich oder klickt auf eine Schaltfläche in einer Nachricht. REQUEST_DIALOG Das Dialogfeld wird in der Chat App geöffnet.
Ein Nutzer sendet im Dialogfeld Informationen, indem er auf eine Schaltfläche klickt. SUBMIT_DIALOG Die Chat-App wechselt entweder zu einem anderen Dialogfeld oder schließt das Dialogfeld, um die Interaktion abzuschließen.
Ein Nutzer schließt oder schließt das Dialogfeld, bevor er Informationen sendet. CANCEL_DIALOG Optional kann die Chat-App mit einer neuen Nachricht antworten oder die Nachricht oder Karte aktualisieren, über die der Nutzer das Dialogfeld geöffnet hat.

Weitere Informationen finden Sie unter Interaktive Dialogfelder öffnen.

Interaktionsereignisse der Chat-App empfangen

In diesem Abschnitt wird beschrieben, wie Sie Interaktionsereignisse für Ihre Chat-App empfangen und verarbeiten.

Chat-App für den Empfang von Interaktionsereignissen konfigurieren

Nicht alle Chat-Apps sind interaktiv. Beispielsweise können eingehende Webhooks nur ausgehende Nachrichten senden und nicht auf Nutzer antworten. Wenn Sie eine interaktive Chat-App erstellen, müssen Sie einen Endpunkt auswählen, über den Ihre Chat-App Interaktionsereignisse empfangen, verarbeiten und darauf reagieren kann. Weitere Informationen zum Entwerfen der Chat-App finden Sie unter Architekturen für die Implementierung von Chat-Apps.

Für jede der interaktiven Funktionen, die Sie erstellen möchten, müssen Sie Ihre Konfiguration in der Chat API aktualisieren, damit Google Chat entsprechende Interaktionsereignisse an Ihre Chat-App senden kann:

  1. Rufen Sie in der Google Cloud Console die Seite „Chat API“ auf und klicken Sie auf Konfiguration:

    Zur Chat API-Konfigurationsseite

  2. Prüfen Sie unter Interaktive Funktionen die Einstellungen und aktualisieren Sie sie entsprechend den Funktionen, die Sie erstellen möchten:

    Feld Beschreibung
    Funktionen Erforderlich. Eine Reihe von Feldern, die festlegen, wie die Chat-App mit Nutzern interagieren kann:
    • 1:1-Nachrichten empfangen: Nutzer können die Google Chat App direkt in Google Chat finden und Nachrichten senden.
    • Gruppenbereichen und Gruppenunterhaltungen beitreten: Nutzer können die Chat App Gruppenbereichen und Gruppenunterhaltungen hinzufügen.
    Verbindungseinstellungen Erforderlich. Der Endpunkt für die Chat-App, einer der folgenden:
    • HTTP-Endpunkt-URL: Ein HTTPS-Endpunkt, auf dem die Chat-App-Implementierung gehostet wird.
    • Apps Script: Eine Bereitstellungs-ID für ein Apps Script-Projekt, in dem eine Chat-App implementiert ist.
    • Cloud Pub/Sub-Themenname: Ein Pub/Sub-Thema, das die Chat-App als Endpunkt abonniert.
    • Dialogflow: Registriert die Chat-App mit einer Dialogflow-Integration. Weitere Informationen finden Sie unter In Dialogflow Google Chat App erstellen, die natürliche Sprache versteht.
    Slash-Befehle Optional. Befehle, die Nutzern in Google Chat angezeigt werden können. Damit können Nutzer die wichtigsten Aktionen für Ihre Chat App in Google Chat sehen und eine bestimmte Aktion auswählen, mit der sie interagieren möchten. Weitere Informationen finden Sie unter Als Chat-App auf Slash-Befehle reagieren.
    Linkvorschauen Optional. URL-Muster, die die Chat-App erkennt und für die sie zusätzliche Inhalte bereitstellt, wenn Nutzer Links senden. Weitere Informationen finden Sie unter Vorschaulinks.
    Sichtbarkeit Optional. Bis zu fünf Personen oder eine oder mehrere Google-Gruppen, die Ihre Chat-App aufrufen und installieren dürfen. Mit diesem Feld können Sie Ihre Chat-App testen oder die Chat App für Ihr Team freigeben. Weitere Informationen finden Sie unter Interaktive Funktionen testen.
  3. Klicken Sie auf Speichern. Wenn Sie die Konfiguration der Chat-App speichern, ist sie für die angegebenen Nutzer in Ihrer Google Workspace-Organisation verfügbar.

Die Chat-App ist jetzt so konfiguriert, dass sie Interaktionsereignisse von Google Chat empfängt.

HTTP-Aufrufwiederholungen an den Dienst verarbeiten

Wenn eine HTTPS-Anfrage an Ihren Dienst fehlschlägt (z. B. aufgrund einer Zeitüberschreitung, eines vorübergehenden Netzwerkausfalls oder eines anderen HTTPS-Statuscodes, der nicht 2xx ist), versucht Google Chat möglicherweise innerhalb weniger Minuten mehrmals, die Zustellung zu wiederholen. Dies ist jedoch nicht garantiert. Daher kann es vorkommen, dass eine Chat-App in bestimmten Situationen dieselbe Nachricht mehrmals empfängt. Wenn die Anfrage erfolgreich abgeschlossen wird, aber eine ungültige Nachrichtenn-Nutzlast zurückgibt, wird die Anfrage in Google Chat nicht noch einmal versucht.

Interaktionsereignisse verarbeiten oder darauf reagieren

In diesem Abschnitt wird erläutert, wie Google Chat-Apps Interaktionsereignisse verarbeiten und darauf reagieren können.

Nachdem Ihre Chat-App ein Interaktionsereignis von Google Chat erhalten hat, kann sie auf verschiedene Arten reagieren. In vielen Fällen antworten interaktive Chat-Apps dem Nutzer mit einer Nachricht. Die Google Chat App kann auch einige Informationen aus einer Datenquelle abrufen, Informationen zu Interaktionsereignissen aufzeichnen oder vieles mehr. Dieses Verarbeitungsverhalten ist im Wesentlichen das, was die Google Chat App definiert.

Um synchron zu antworten, muss eine Chat-App innerhalb von 30 Sekunden antworten und die Antwort muss in dem Bereich gepostet werden, in dem die Interaktion stattgefunden hat. Andernfalls kann die Chat-App asynchron antworten.

Für jedes Interaktionsereignis erhalten Chat-Apps einen Request Body, also die JSON-Nutzlast, die das Ereignis darstellt. Sie können die Informationen verwenden, um eine Antwort zu verarbeiten. Beispiele für Ereignisnutzlasten finden Sie unter Typen von Interaktionsereignissen für Chat-Apps.

Das folgende Diagramm zeigt, wie verschiedene Arten von Interaktionsereignissen in der Google Chat App normalerweise verarbeitet oder beantwortet werden:

Architektur der Verarbeitung von Interaktionsereignissen in Google Chat-Apps

In Echtzeit antworten

Mithilfe von Interaktionsereignissen können Chat-Apps in Echtzeit oder synchron antworten. Für synchrone Antworten ist keine Authentifizierung erforderlich.

Damit in Echtzeit reagiert werden kann, muss die Chat-App ein Message-Objekt zurückgeben. Um im Gruppenbereich mit einer Nachricht zu antworten, kann das Message-Objekt die Objekte text, cardsV2 und accessoryWidgets enthalten. Informationen zur Verwendung mit anderen Antworttypen finden Sie in den folgenden Leitfäden:

Mit Nach­richt antworten

In diesem Beispiel erstellt und sendet die Chat-App eine SMS, wenn sie einem Gruppenbereich hinzugefügt wird. Weitere Informationen zu Best Practices für das Onboarding von Nutzern finden Sie unter Nutzern die Chat-App vorstellen.

Wenn eine Textnachricht gesendet werden soll, wenn ein Nutzer Ihre Chat-App einem Gruppenbereich hinzufügt, muss Ihre Chat-App auf ein ADDED_TO_SPACEInteraktionsereignis reagieren. Verwenden Sie den folgenden Code, um auf ADDED_TO_SPACE-Interaktionsereignisse mit einer Textnachricht zu antworten:

Node.js

/**
 * Sends an onboarding message when the Chat app is added to a space.
 *
 * @param {Object} req The event object from Chat API.
 * @param {Object} res The response object from the Chat app. An onboarding message that
 * introduces the app and helps people get started with it.
 */
exports.onMessage = function onMessage(req, res) {
  if (req.method === 'GET' || !req.body.message) {
    res.send(
      'Hello! This function is meant to be used in a Google Chat space.');
  }

  // Send an onboarding message when added to a Chat space
  if (req.body.type === 'ADDED_TO_SPACE') {
    res.json({
      'text': 'Hi, Cymbal at your service. I help you manage your calendar
      from Google Chat. Take a look at your schedule today by typing
      `/checkCalendar`, or schedule a meeting with `/scheduleMeeting`. To
      learn what else I can do, type `/help`.'
    });
  }
};

Apps Script

/**
 * Sends an onboarding message when the Chat app is added to a space.
 *
 * @param {Object} event The event object from Chat API.
 * @return {Object} Response from the Chat app. An onboarding message that
 * introduces the app and helps people get started with it.
 */
function onAddToSpace(event) {

  return {
    'text': 'Hi, Cymbal at your service. I help you manage your calendar
    from Google Chat. Take a look at your schedule today by typing
    `/checkCalendar`, or schedule a meeting with `/scheduleMeeting`. To learn
    what else I can do, type `/help`.'
  }
}

Das Codebeispiel gibt die folgende Textnachricht zurück:

Beispiel für eine Onboarding-Nachricht.

Asynchron antworten

Manchmal müssen Chat-Apps nach 30 Sekunden auf ein Interaktionsereignis reagieren oder Aufgaben außerhalb des Gruppenbereichs ausführen, in dem das Interaktionsereignis generiert wurde. Beispielsweise kann eine Chat-App dem Nutzer antworten, nachdem eine Aufgabe mit langer Ausführungszeit abgeschlossen wurde. In diesem Fall können Chat-Apps asynchron antworten, indem sie die Google Chat API aufrufen.

Informationen zum Erstellen einer Nachricht mit der Chat API finden Sie unter Nachricht erstellen. Anleitungen zur Verwendung zusätzlicher Chat API-Methoden finden Sie in der Übersicht über die Chat API.