Interaktionsereignisse empfangen und darauf reagieren

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

Auf dieser Seite wird Folgendes beschrieben:

• Chat-App so konfigurieren, dass sie Interaktionsereignisse empfängt
• Interaktionsereignis in Ihrer Infrastruktur verarbeiten
• Bei Bedarf auf Interaktionsereignisse reagieren

Vorbereitung

• Ein Google Workspace-Konto für Unternehmen oder Enterprise mit Zugriff auf Google Chat.
• Google Cloud-Projekt erstellen.
• OAuth-Zustimmungsbildschirm konfigurieren.
• Google Chat API aktivieren.

Arten von Interaktionsereignissen

Ein Google Chat-App-Interaktionsereignis stellt jede Aktion dar, die ein Nutzer ausführt, um eine Chat-App aufzurufen oder mit ihr zu interagieren, z. B. eine Chat-App zu erwähnen oder sie 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 zu antworten.

Für jede Art der 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 eventType Objekt dargestellt.

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

In der folgenden Tabelle sind häufige Nutzerinteraktionen, der Typ des Interaktionsereignisses, das die Chat-Apps empfangen, und die typische Antwort von Chat-Apps aufgeführt:

Alle unterstützten Interaktionsereignisse finden Sie in der EventType Referenz dokumentation.

Interaktionsereignisse aus Dialogfeldern

Wenn Ihre Chat-App Dialogfelderöffnet, enthält das Interaktionsereignis die folgenden zusätzlichen Informationen, mit denen Sie eine Antwort verarbeiten können:

• isDialogEvent ist auf true gesetzt.
• The DialogEventType gibt an, ob die Interaktion das Öffnen eines Dialogfelds auslöst, sendet Informationen aus einem Dialogfeld oder schließt ein Dialogfeld.

In der folgenden Tabelle sind die häufigsten Interaktionen mit Dialogfeldern, die entsprechenden Dialogereignistypen und eine Beschreibung der typischen Antwort von Chat-Apps aufgeführt:

Weitere Informationen finden Sie unter Interaktive Dialogfelder öffnen.

Interaktionsereignisse von Chat-Apps empfangen

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

Chat-App so konfigurieren, dass sie Interaktionsereignisse empfängt

Nicht alle Chat-Apps sind interaktiv. Eingehende Webhooks können beispielsweise 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 Ihrer Chat-App finden Sie unter Implementierungsarchitekturen für Chat-Apps.

Für jede interaktive Funktion, 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. Öffnen Sie in der Google Cloud Console die Seite „Chat API“ und klicken Sie auf die Seite Konfiguration:

   Zur Seite „Chat API-Konfiguration“

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 bestimmen, wie die Chat-App mit Nutzern interagieren kann. Standardmäßig können Nutzer die Chat-App direkt in Google Chat finden und ihr 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, der einer der folgenden sein kann: 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, das eine Chat-App implementiert. 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 Dialogflow-Google Chat-App erstellen, die natürliche Sprache versteht.
   Befehle	Optional. Slash-Befehle und Schnellbefehle für die Chat-App. Mit Befehlen können Nutzer eine Aktion anfordern oder eine bestimmte Funktion Ihrer Chat-App verwenden. Weitere Informationen finden Sie unter Auf Google Chat-App-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 Linkvorschauen.
   Sichtbarkeit	Optional. Bis zu fünf Personen oder eine oder mehrere Google-Gruppen, die Ihre Chat-App sehen und installieren können. Verwenden Sie dieses Feld, um Ihre Chat-App zu testen oder sie für Ihr Team freizugeben. Weitere Informationen finden Sie unter Interaktive Funktionen testen.

3. Klicken Sie auf Speichern. Wenn Sie die Chat-App-Konfiguration speichern, ist Ihre Chat-App für die angegebenen Nutzer in Ihrer Google Workspace-Organisation verfügbar.

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

Wiederholungen von HTTP-Aufrufen an Ihren Dienst verarbeiten

Wenn eine HTTPS-Anfrage an Ihren Dienst fehlschlägt (z. B. aufgrund einer Zeitüberschreitung, eines vorübergehenden Netzwerkausfalls oder eines HTTPS-Statuscodes, der nicht im 2xx-Bereich liegt), versucht Google Chat möglicherweise einige Male innerhalb weniger Minuten, die Zustellung zu wiederholen (dies wird 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.

Nachdem Ihre Chat-App ein Interaktionsereignis von Google Chat empfangen hat, kann sie auf viele Arten reagieren. In vielen Fällen antworten interaktive Chat-Apps dem Nutzer mit einer Nachricht. Google Chat-Apps können auch Informationen aus einer Datenquelle abrufen, die Informationen zum Interaktionsereignis aufzeichnen oder vieles mehr. Dieses Verarbeitungsverhalten definiert im Wesentlichen die Google Chat-App.

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

Für jedes Interaktionsereignis erhalten Chat-Apps einen Anfragetextkörper, der die JSON-Nutzlast darstellt, die das Ereignis repräsentiert. Sie können die Informationen verwenden, um eine Antwort zu verarbeiten. Beispiele für Ereignisnutzlasten finden Sie unter Arten von Interaktionsereignissen von Chat-Apps.

Das folgende Diagramm zeigt, wie Google Chat-Apps in der Regel auf verschiedene Arten von Interaktionsereignissen reagieren:

In Echtzeit antworten

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

Um in Echtzeit zu antworten, muss die Chat-App ein Message-Objekt zurückgeben. Um mit einer Nachricht im Gruppenbereich zu antworten, kann das Message Objekt die text, cardsV2 und accessoryWidgets Objekte enthalten. Informationen zur Verwendung mit anderen Arten von Antworten finden Sie in den folgenden Anleitungen:

• Interaktive Dialogfelder öffnen
• Linkvorschauen
• Von Nutzern gesendete Informationen verarbeiten

Mit Nach­richt antworten

In diesem Beispiel erstellt und sendet Ihre Chat-App eine Textnachricht, wenn sie einem Gruppenbereich hinzugefügt wird. Best Practices für das Onboarding von Nutzern finden Sie unter Nutzer mit Ihrer Chat-App vertraut machen.

Wenn ein Nutzer Ihre Chat-App einem Gruppenbereich hinzufügt, sendet Ihre Chat-App eine Textnachricht, indem sie auf ein ADDED_TO_SPACE Interaktionsereignisreagiert. Verwenden Sie den folgenden Code, um auf ADDED_TO_SPACE-Interaktionsereignisse mit einer Textnachricht zu antworten:

/**
 * 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.
 */
exports.cymbalApp = function cymbalApp(req, res) {
  // 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`.'
    });
  }
};

from flask import Flask, request, json
app = Flask(__name__)

@app.route('/', methods=['POST'])
def cymbal_app():
  """Sends an onboarding message when the Chat app is added to a space.

  Returns:
    Mapping[str, Any]: The response object from the Chat app.
  """
  event = request.get_json()
  if event['type'] == 'ADDED_TO_SPACE':
    return json.jsonify({
      '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`.'
    })
  return json.jsonify({})

@SpringBootApplication
@RestController
public class App {
  public static void main(String[] args) {
    SpringApplication.run(App.class, args);
  }

  /*
   * Sends an onboarding message when the Chat app is added to a space.
   *
   * @return The response object from the Chat app.
   */
  @PostMapping("/")
  @ResponseBody
  public Message onEvent(@RequestBody JsonNode event) {
    switch (event.get("type").asText()) {
      case "ADDED_TO_SPACE":
        return new Message().setText(
          "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`.");
      default:
        return new Message();
    }
  }
}

/**
 * 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.
 */
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:

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 muss eine Chat-App möglicherweise auf den Nutzer antworten, nachdem eine zeitaufwendige Aufgabe 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 zur Chat API.

Weitere Informationen

• Nachricht senden
• Interaktive Dialogfelder öffnen
• Linkvorschauen
• Von Nutzern auf Karten gesendete Formulardaten lesen
• Auf Befehle reagieren
• Startseite für eine Chat-App erstellen
• Anfragen von Chat überprüfen
• Interaktive Funktionen für Google Chat-Apps testen