Diese Seite wurde von der Cloud Translation API übersetzt.

Interaktionen mit der Google Chat App empfangen und beantworten

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

Ein Interaktionsereignis in einer Google Chat-Anwendung 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 Aufgaben:

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 Gruppenbereich konfiguriert wurden, z. B. das 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 eine andere Art von 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-Anwendung erstellen, müssen Sie einen Endpunkt auswählen, mit dem die Chat-Anwendung 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.

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

Öffnen Sie in der Google Cloud Console die Seite „Google Chat API“:
Zur Seite „Google Chat API“
Klicken Sie auf den Tab Konfiguration.
Stellen Sie den Schalter Interaktive Funktionen aktivieren im Abschnitt Interaktive Funktionen auf "Ein".
Klicken Sie unter Funktionen eines oder beide der folgenden Kästchen an:
1. 1:1-Nachrichten empfangen: Damit können Nutzer in Direktnachrichten-Gruppenbereichen mit Ihrer Chat-App interagieren. Jedes Mal, wenn ein Nutzer eine Nachricht im DM-Bereich sendet, empfängt Ihre Chat-App Interaktionsereignisse.
2. Gruppenbereichen und Gruppenunterhaltungen beitreten: Damit können Nutzer Ihre Chat App zu Gruppenbereichen mit mehr als einer Person hinzufügen und daraus 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.
Geben Sie unter Verbindungseinstellungen an, wohin Google Chat-Interaktionsereignisse für die Chat-App gesendet werden soll.
Optional: Unter Slash-Befehle können Sie einen oder mehrere Slash-Befehle hinzufügen und konfigurieren. Weitere Informationen finden Sie unter Slash-Befehle einrichten.
Optional: Fügen Sie unter Linkvorschau ein oder mehrere URL-Muster hinzu, die Ihre Chat-App als Vorschau anzeigen soll, und konfigurieren Sie sie. Weitere Informationen finden Sie unter Vorschaulinks.
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 erstellt wurden, prüfen können, ob die Anfragen an Ihren Endpunkt von Google Chat stammen.

Zum Senden von Interaktionsereignissen an den Endpunkt Ihrer Chat-App sendet Google Anfragen an Ihren Dienst. Um zu prüfen, 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 Ihr Inhabertoken mithilfe einer Open-Source-Clientbibliothek der Google API überprüfen:

Java: https://github.com/google/google-api-java-client
Python: https://github.com/google/google-api-python-client
.NET: https://github.com/google/google-api-dotnet-client

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-App 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 Ihren Dienst verarbeiten

Wenn eine HTTPS-Anfrage an Ihren Dienst fehlschlägt (z. B. eine Zeitüberschreitung, ein vorübergehender Netzwerkfehler oder ein Non-2xx-HTTPS-Statuscode), wiederholt Google Chat innerhalb weniger Minuten die Zustellung mehrmals. Dies kann jedoch nicht garantiert werden. Daher kann es vorkommen, dass eine Chat-App in bestimmten Situationen dieselbe Nachricht mehrmals empfängt. Wenn die Anfrage erfolgreich abgeschlossen, 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 verschiedene Arten reagieren. In vielen Fällen antworten interaktive Chat-Apps dem Nutzer mit einer Nachricht. Die Google Chat-App kann auch Informationen aus einer Datenquelle abrufen, Interaktionsereignisinformationen aufzeichnen und vieles mehr. Dieses Verarbeitungsverhalten ist im Wesentlichen die Definition der Google Chat-App.

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

Das folgende Diagramm zeigt, wie die Google Chat-Anwendung 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.

Informationen zum Erstellen synchroner Antworten auf Interaktionsereignisse finden Sie in den folgenden Anleitungen:

Für eine synchrone Antwort muss eine Chat-App innerhalb von 30 Sekunden antworten. Die Antwort muss im Gruppenbereich gepostet werden, in dem die Interaktion aufgetreten ist. Andernfalls kann die Chat-Anwendung asynchron reagieren.

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 es sein, dass eine Chat-App dem Nutzer antworten muss, nachdem eine lang andauernde Aufgabe ausgeführt wurde. In diesem Fall können Chat-Apps asynchron antworten, indem die Google Chat API aufgerufen wird.

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