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 einer Google Chat-App stellt jede Aktion dar, die ein Nutzer ausführt, um eine Chat-App aufzurufen oder mit ihr zu interagieren. Dazu zählt z. B. die @Erwähnung 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 beispielsweise Interaktionsereignisse, um Folgendes zu tun:

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 Arten 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.

Google Chat-App-Interaktionsereignisse empfangen

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

Google 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 Nutzern antworten. Wenn Sie eine interaktive Chat-Anwendung erstellen, müssen Sie einen Endpunkt auswählen, über den die Chat-Anwendung Interaktionsereignisse empfangen, verarbeiten und auf sie 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 Ihnen 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. Aktivieren Sie im Abschnitt Interaktive Funktionen die Option Interaktive Funktionen aktivieren.
4. Klicken Sie unter Funktionen eines oder beide der folgenden Kästchen an:
   1. 1:1-Nachrichten empfangen: Nutzer können in Direktnachrichten (DN) mit Ihrer Chat-App interagieren. Ihre Chat-App empfängt jedes Mal Interaktionsereignisse, wenn ein Nutzer eine Nachricht im DN-Bereich sendet.
   2. Gruppenbereichen und Gruppenunterhaltungen beitreten: Nutzer können 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 und wenn Nutzer im Gruppenbereich @erwähnen oder einen Slash-Befehl verwenden.
5. Geben Sie unter Verbindungseinstellungen an, wohin Interaktionsereignisse für Chat-Apps von Google Chat gesendet werden sollen.
6. Optional: Fügen Sie unter Slash-Befehle einen oder mehrere Slash-Befehle hinzu und konfigurieren Sie sie. 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.

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

Anfragen von Google Chat authentifizieren

Für Anwendungen, die auf HTTP-Endpunkten basieren, wird in diesem Abschnitt erläutert, wie Sie 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. Damit geprüft werden kann, 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 mithilfe einer Open-Source-Clientbibliothek der Google API prü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 in Google Chat gesendeten Inhabertokens 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 werden kann, sollte Ihr Dienst auf die Anfrage mit dem HTTPS-Antwortcode 401 (Unauthorized) antworten.

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");
  }
}

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 bei HTTP-Aufrufen an den Dienst verarbeiten

Wenn eine HTTPS-Anfrage an Ihren Dienst fehlschlägt (z. B. bei einer Zeitüberschreitung, einem vorübergehenden Netzwerkausfall oder einem HTTPS-Statuscode ohne 2xx), wiederholt Google Chat innerhalb weniger Minuten die Zustellung mehrmals. 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 Nachrichtennutzlast zurückgibt, wiederholt Google Chat die Anfrage nicht.

Interaktionsereignisse verarbeiten oder darauf reagieren

In diesem Abschnitt wird erläutert, wie Google Chat-Apps 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-Anwendungen dem Nutzer mit einer Nachricht. Die Google Chat-App kann auch bestimmte Informationen aus einer Datenquelle abrufen, Informationen zu Interaktionsereignissen aufzeichnen und vieles mehr. Dieses Verarbeitungsverhalten bestimmt im Wesentlichen die Google Chat App.

Für jedes Interaktionsereignis erhalten Chat-Apps einen Anfragetext. Dies ist die JSON-Nutzlast, die das Ereignis darstellt. Sie können diese Informationen verwenden, um eine Antwort zu verarbeiten. Beispiele für Ereignisnutzlasten finden Sie unter Arten von Chat-App-Interaktionsereignissen.

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

In Echtzeit antworten

Durch 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 Leitfäden:

• Kartennachricht erstellen
• SMS erstellen
• Interaktive Dialogfelder öffnen
• Vorschaulinks
• Vom Nutzer eingegebene Formulardaten auf Karten lesen
• Slash-Befehle einrichten

Für eine synchrone Antwort muss eine Chat-Anwendung innerhalb von 30 Sekunden antworten und die Antwort muss in dem 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 Bereichs 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 abgeschlossen wurde. In diesem Fall können Chat-Anwendungen 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 zur Chat API.