Interaktionen mit der Google Chat App empfangen und beantworten

Auf dieser Seite wird beschrieben, wie Ihre Google Chat-App Nutzerinteraktionen empfangen und darauf reagieren kann. Diese werden auch als Interaktionsereignisse für Google Chat-Apps bezeichnet.

Ein Interaktionsereignis in Google Chat steht für jede Aktion, die ein Nutzer ausführt, um eine Chat-App aufzurufen oder mit ihr zu interagieren, z. B. das @Erwähnen einer Chat-App oder das Hinzufügen zu einem Gruppenbereich. Wenn Nutzer mit einer Chat-App interagieren, sendet Google Chat ein Interaktionsereignis an die Chat-App. Die Chat-App kann das Ereignis verwenden, um die Interaktion zu verarbeiten und eine Antwort zu erstellen.

Chat-Apps verwenden Interaktionsereignisse beispielsweise für folgende Aktionen:

Beispiel für ein Interaktionsereignis Typische Antwort einer Chat-App
Ein Nutzer ruft eine Chat-Anwendung auf, indem er sie @erwähnt oder einen Slash-Befehl verwendet. Die Chat-App verarbeitet den Inhalt der Nachricht, um eine Nachricht zu erstellen. Beispiel: Eine Chat-App antwortet auf den Befehl /about mit einer Nachricht, in der die Aufgaben erläutert werden, die die Chat-App ausführen kann.
Ein Nutzer fügt einem Gruppenbereich eine Chat-App hinzu. Die Chat-App sendet eine Onboarding-Nachricht, in der erläutert wird, was sie tut und wie Nutzer im Gruppenbereich damit interagieren können.
Ein Nutzer entfernt eine Chat-App aus einem Gruppenbereich. Die Chat-App entfernt alle eingehenden Benachrichtigungen, die für den Bereich konfiguriert wurden, z. B. durch Löschen eines Webhooks, und gibt den gesamten internen Speicher frei.
Ein Nutzer klickt auf eine Schaltfläche auf einer Karte oder einem Dialogfeld, das von der Chat-App gesendet wurde. Die Chat-App verarbeitet und speichert alle vom Nutzer gesendeten Daten oder gibt eine andere Karte oder ein anderes Dialogfeld zurück.

Für jede Art von Nutzerinteraktion sendet Google Chat ein anderes Interaktionsereignis. Google Chat verwendet beispielsweise den Ereignistyp MESSAGE für jede Interaktion, bei der ein Nutzer die Chat-App in einer Nachricht aufruft. Weitere Informationen finden Sie unter Typen von App-Interaktionsereignissen in Google Chat.

Auf dieser Seite wird Folgendes beschrieben:

  • Konfigurieren Sie die Chat-App für den Empfang von Ereignissen.
  • Verarbeiten Sie das Interaktionsereignis in Ihrer Infrastruktur.
  • Reagieren Sie gegebenenfalls auf Interaktionsereignisse.

Interaktionsereignisse für Chat-Apps 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 zur Implementierung von Chat-Apps.

Wenn Sie eine interaktive Chat-App erstellt haben, müssen Sie die Google Chat API so konfigurieren, dass Google Chat Interaktionsereignisse senden kann:

  1. Öffnen Sie in der Google Cloud Console die Seite „Google Chat API“:

    Zur Seite „Google Chat API“

  2. Klicken Sie auf den Tab Konfiguration.
  3. Stellen Sie den Schalter Interaktive Funktionen aktivieren im Abschnitt Interaktive Funktionen auf „Ein“.
  4. Klicken Sie unter Funktionen auf eines oder beide der folgenden Kästchen:
    1. 1:1-Nachrichten empfangen: Damit können Nutzer in Direktnachrichten (DN) mit Ihrer Chat-App interagieren. Ihre Chat-App empfängt jedes Mal Interaktionsereignisse, wenn ein Nutzer eine Nachricht im DM-Bereich sendet.
    2. Gruppenbereichen und Gruppenunterhaltungen beitreten: Damit erlauben Sie Nutzern, Ihre Chat App Gruppenbereichen mit mehr als einer Person hinzuzufügen oder daraus zu entfernen. Ihre Chat-App empfängt Interaktionsereignisse, wenn sie dem Gruppenbereich hinzugefügt oder daraus entfernt wird oder wenn Nutzer im Gruppenbereich eine @Erwähnung schreiben oder einen Slash-Befehl verwenden.
  5. Geben Sie in den Verbindungseinstellungen an, wohin Interaktionsereignisse für die Chat-App von Google Chat gesendet werden sollen.
  6. Optional: Unter Slash-Befehle können Sie einen oder mehrere Slash-Befehle hinzufügen und konfigurieren. Weitere Informationen finden Sie unter Slash-Befehle einrichten.
  7. Optional: Fügen Sie unter Linkvorschau ein oder mehrere URL-Muster hinzu, die in der Chat App angezeigt werden, und konfigurieren Sie sie. Weitere Informationen finden Sie unter Vorschaulinks.
  8. Klicken Sie auf Speichern.

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

Anfragen von Google Chat authentifizieren

In diesem Abschnitt wird erläutert, wie Sie für Anwendungen, die auf HTTP-Endpunkten basieren, prüfen können, ob die Anfragen an Ihren Endpunkt von Google Chat stammen.

Damit Interaktionsereignisse an den Endpunkt Ihrer Chat-App gesendet werden, sendet Google Anfragen an Ihren Dienst. Zur Überprüfung, ob die Anfrage von Google kommt, fügt Google Chat in den Authorization-Header jeder HTTPS-Anfrage an Ihren Endpunkt ein Inhabertoken ein. Beispiel:

POST
Host: yourappurl.com
Authorization: Bearer AbCdEf123456
Content-Type: application/json
User-Agent: Google-Dynamite

Der String AbCdEf123456 im obigen Beispiel ist das Inhaberautorisierungstoken. Dies ist ein von Google erstelltes kryptografisches Token. Sie können das Inhabertoken mit einer Open-Source-Google API-Clientbibliothek überprüfen:

Für die Inhabertokens, die in Google Chat-Anfragen gesendet werden, ist der Aussteller chat@system.gserviceaccount.com und das Feld audience ist auf die Nummer des Google Cloud-Projekts festgelegt, mit dem Sie Ihre Chat-Anwendung erstellt haben. Wenn die Cloud-Projektnummer Ihrer Chat-Anwendung beispielsweise 1234567890 lautet, ist das Feld audience im Inhabertoken 1234567890.

Wenn das Token für die Chat-Anwendung nicht verifiziert wird, sollte Ihr Dienst auf die Anfrage mit dem HTTPS-Antwortcode 401 (Unauthorized) antworten.

Java

import java.io.IOException;
import java.security.GeneralSecurityException;
import java.util.Collections;

import com.google.api.client.googleapis.auth.oauth2.GoogleIdToken;
import com.google.api.client.googleapis.auth.oauth2.GoogleIdTokenVerifier;
import com.google.api.client.googleapis.auth.oauth2.GooglePublicKeysManager;
import com.google.api.client.http.apache.ApacheHttpTransport;
import com.google.api.client.json.JsonFactory;
import com.google.api.client.json.jackson.JacksonFactory;

/** Tool for verifying JWT Tokens for Apps in Google Chat. */
public class JWTVerify {
  // Bearer Tokens received by apps will always specify this issuer.
  static String CHAT_ISSUER = "chat@system.gserviceaccount.com";

  // Url to obtain the public certificate for the issuer.
  static String PUBLIC_CERT_URL_PREFIX =
      "https://www.googleapis.com/service_accounts/v1/metadata/x509/";

  // Intended audience of the token, which is the project number of the app.
  static String AUDIENCE = "1234567890";

  // Get this value from the request's Authorization HTTPS header.
  // For example, for "Authorization: Bearer AbCdEf123456" use "AbCdEf123456"
  static String BEARER_TOKEN = "AbCdEf123456";

  public static void main(String[] args) throws GeneralSecurityException, IOException {
    JsonFactory factory = new JacksonFactory();

    GooglePublicKeysManager.Builder keyManagerBuilder =
        new GooglePublicKeysManager.Builder(new ApacheHttpTransport(), factory);

    String certUrl = PUBLIC_CERT_URL_PREFIX + CHAT_ISSUER;
    keyManagerBuilder.setPublicCertsEncodedUrl(certUrl);

    GoogleIdTokenVerifier.Builder verifierBuilder =
        new GoogleIdTokenVerifier.Builder(keyManagerBuilder.build());
    verifierBuilder.setIssuer(CHAT_ISSUER);
    GoogleIdTokenVerifier verifier = verifierBuilder.build();

    GoogleIdToken idToken = GoogleIdToken.parse(factory, BEARER_TOKEN);
    if (idToken == null) {
      System.out.println("Token cannot be parsed");
      System.exit(-1);
    }

    // Verify valid token, signed by CHAT_ISSUER.
    if (!verifier.verify(idToken)
        || !idToken.verifyAudience(Collections.singletonList(AUDIENCE))
        || !idToken.verifyIssuer(CHAT_ISSUER)) {
      System.out.println("Invalid token");
      System.exit(-1);
    }

    // Token originates from Google and is targeted to a specific client.
    System.out.println("The token is valid");
  }
}

Python

import sys

from oauth2client import client

# Bearer Tokens received by apps will always specify this issuer.
CHAT_ISSUER = 'chat@system.gserviceaccount.com'

# Url to obtain the public certificate for the issuer.
PUBLIC_CERT_URL_PREFIX = 'https://www.googleapis.com/service_accounts/v1/metadata/x509/'

# Intended audience of the token, which will be the project number of the app.
AUDIENCE = '1234567890'

# Get this value from the request's Authorization HTTPS header.
# For example, for 'Authorization: Bearer AbCdEf123456' use 'AbCdEf123456'.
BEARER_TOKEN = 'AbCdEf123456'

try:
  # Verify valid token, signed by CHAT_ISSUER, intended for a third party.
  token = client.verify_id_token(
      BEARER_TOKEN, AUDIENCE, cert_uri=PUBLIC_CERT_URL_PREFIX + CHAT_ISSUER)

  if token['iss'] != CHAT_ISSUER:
    sys.exit('Invalid issuee')
except:
  sys.exit('Invalid token')

# Token originates from Google and is targeted to a specific client.
print 'The token is valid'

Wiederholungsversuche von HTTP-Aufrufen an den Dienst verarbeiten

Wenn eine HTTPS-Anfrage an Ihren Dienst fehlschlägt (z. B. aufgrund einer Zeitüberschreitung, eines vorübergehenden Netzwerkfehlers oder eines Nicht-2xx-HTTPS-Statuscodes), wiederholt Google Chat innerhalb weniger Minuten die Zustellung mehrmals. Das ist jedoch nicht garantiert. Daher kann es vorkommen, dass eine Chat-Anwendung in bestimmten Situationen mehrmals dieselbe Nachricht empfängt. Wenn die Anfrage erfolgreich abgeschlossen wird, aber eine ungültige Nachrichtennutzlast zurückgegeben wird, wiederholt Google Chat die Anfrage nicht.

Interaktionsereignisse verarbeiten oder darauf reagieren

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

Wenn Ihre Chat-App ein Interaktionsereignis von Google Chat empfängt, kann sie auf unterschiedliche Weise antworten. In vielen Fällen antworten interaktive Chat-Apps den Nutzern mit einer Nachricht. Die Google Chat-App kann auch bestimmte Informationen aus einer Datenquelle abrufen, Informationen zu Interaktionsereignissen aufzeichnen und vieles mehr. Dieses Verarbeitungsverhalten ist im Wesentlichen die Definition der Google Chat App.

Für jedes Interaktionsereignis erhalten Chat-Apps einen Anfragetext. Dies ist die JSON-Nutzlast, die das Ereignis darstellt. Anhand dieser Informationen können Sie eine Antwort bearbeiten. Beispiele für Ereignisnutzlasten finden Sie unter Arten von Interaktionsereignissen in Chat-Apps.

Das folgende Diagramm zeigt, wie die Google Chat-App normalerweise verschiedene Arten von Interaktionsereignissen verarbeitet oder darauf reagiert:

Architektur, wie Interaktionsereignisse in Google Chat-Apps verarbeitet werden

In Echtzeit antworten

Über Interaktionsereignisse können Chat-Apps in Echtzeit oder synchron antworten. Synchrone Antworten erfordern keine Authentifizierung.

In den folgenden Anleitungen erfahren Sie, wie Sie synchrone Antworten auf Interaktionsereignisse erstellen:

Für eine synchrone Antwort muss eine Chat-App innerhalb von 30 Sekunden antworten. Außerdem muss die Antwort in dem Bereich gepostet werden, in dem die Interaktion stattgefunden hat. Andernfalls kann die Chat-App asynchron reagieren.

Asynchron reagieren

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 er eine lang andauernde Aufgabe ausgeführt hat. In diesem Fall können Chat-Apps durch Aufrufen der Google Chat API asynchron antworten.

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 zur Chat API.