Interaktionsereignisse empfangen und darauf reagieren

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

Auf dieser Seite wird Folgendes beschrieben:

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

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. wenn er eine Chat-App mit @erwähnt oder sie einem Gruppenbereich hinzufügt.

Wenn Nutzer mit einer Chat-App interagieren, sendet Google Chat ein Interaktionsereignis an die Chat-App, das in der Chat API als Event-Typ 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 von Nutzerinteraktion sendet Google Chat einen anderen Typ 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 beispielsweise der Ereignistyp ADDED_TO_SPACE für jede Interaktion verwendet, bei der ein Nutzer die Chat-App einem Gruppenbereich hinzufügt. So kann die Chat-App sofort mit einer Willkommensnachricht im Gruppenbereich antworten.

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

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

Interaktionsereignisse aus Dialogfeldern

Wenn in Ihrer 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 durch die Interaktion ein Dialogfeld geöffnet, Informationen aus einem Dialogfeld gesendet oder ein Dialogfeld geschlossen wird.

Die folgende Tabelle zeigt die häufigsten Interaktionen mit Dialogfeldern, die entsprechenden Dialogfeld-Ereignistypen und eine Beschreibung der typischen Reaktionen von Chat-Apps:

Weitere Informationen finden Sie unter Interaktive Dialogfelder öffnen.

Ereignisse zur Chat-App-Interaktion 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. Eingehende Webhooks können beispielsweise nur ausgehende Nachrichten senden und nicht auf Nutzer reagieren. Wenn Sie eine interaktive Chat-App entwickeln, 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 die 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 die Seite Konfiguration:

   Zur Seite „Chat API Configuration“

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

   Feld	Beschreibung
   Funktionalität	Erforderlich. Eine Reihe von Feldern, die festlegen, wie eine Chat-App mit Nutzern interagieren kann. Standardmäßig können Nutzer die Chat-App direkt in Google Chat finden und Nachrichten an sie 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 ist: 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 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.
   Einstiegsprompts	Optional. (science Entwicklervorschau) Bis zu drei Start-Prompts, die angezeigt werden, wenn Nutzer eine leere 1:1-Direktnachricht mit der Chat-App öffnen. Mit Prompts kann Text im Eingabebereich eingefügt werden (mit Unterstützung für mehrsprachige Lokalisierung) oder ein Slash-Befehl bzw. Schnellbefehl direkt ausgelöst werden. Weitere Informationen finden Sie unter Starter-Prompts konfigurieren.
   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 ansehen und installieren können. Verwenden Sie dieses Feld, um Ihre Chat-App zu testen oder sie mit Ihrem Team zu teilen. 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.

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

Einstiegsprompts konfigurieren

Mit Starter-Prompts können Nutzer die Funktionen Ihrer Chat-App kennenlernen, wenn sie eine leere 1:1-Direktnachricht mit Ihrer App öffnen. Sie können bis zu drei Starter-Prompts konfigurieren.

So fügen Sie Startaufforderungen hinzu und konfigurieren sie:

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

   Zur Seite „Chat API Configuration“

2. Suchen Sie unter Interaktive Funktionen nach Starter-Prompts und klicken Sie auf Prompt hinzufügen.

3. Geben Sie im Feld Rang (1–3) eine Zahl zwischen 1 und 3 ein, um die Reihenfolge der Anzeige festzulegen.

4. Wählen Sie unter Typauswahl aus, wie sich die Aufforderung verhält:

   • Text-Prompt: Füllt die Eingabezeile mit vordefiniertem Text, wenn der Nutzer auf den Prompt-Chip klickt.
   • Eingabeaufforderung: Führt einen registrierten Slash-Befehl oder Schnellbefehl aus, wenn darauf geklickt wird. Befehle, für die zusätzliche Argumente erforderlich sind, können nicht ausgewählt werden.

5. Konfigurieren Sie den Prompt entsprechend Ihrer Auswahl:

   • Wenn Sie „Text-Prompt“ ausgewählt haben:

     1. Geben Sie unter Titel den Prompt-Titel ein, der auf dem Chip angezeigt wird (bis zu 30 Zeichen).
     2. Geben Sie unter Prompt-Text den Text ein, der in der Eingabezeile angezeigt wird (bis zu 60 Zeichen).
     3. Optional: Fügen Sie lokalisierte Titel und Texte für Nutzer in anderen Sprachen hinzu:
     4. Klicken Sie unter Lokalisierte Prompts auf Sprache hinzufügen.
     5. Wählen Sie unter Sprache eine unterstützte Sprache aus dem Drop-down-Menü aus.
     6. Geben Sie unter Lokalisierter Titel den lokalisierten Titel ein (bis zu 30 Zeichen).
     7. Geben Sie unter Lokalisierter Prompt-Text den lokalisierten Prompt-Text ein (bis zu 60 Zeichen).
     8. Wiederholen Sie den Vorgang, um bei Bedarf weitere Sprachen hinzuzufügen.

   • Wenn Sie „Eingabeaufforderung“ ausgewählt haben:

     1. Wählen Sie unter Slash-Befehl / Schnellbefehl den Befehl aus dem Drop-down-Menü aus.

6. Klicken Sie auf Fertig und dann am Seitenende auf Speichern.

Wiederholungsversuche für HTTP-Aufrufe an Ihren Dienst verarbeiten

Wenn eine HTTPS-Anfrage an Ihren Dienst fehlschlägt (z. B. aufgrund eines Zeitlimits, eines vorübergehenden Netzwerkfehlers oder eines HTTPS-Statuscodes, der nicht mit „2xx“ beginnt), versucht Google Chat möglicherweise, die Zustellung innerhalb weniger Minuten einige Male zu wiederholen. Dies ist jedoch nicht garantiert. Daher kann es in bestimmten Situationen vorkommen, dass eine Chat-App dieselbe Nachricht mehrmals empfängt. Wenn die Anfrage erfolgreich abgeschlossen wird, aber eine ungültige Nachrichtennutzlast zurückgibt, wird die Anfrage von Google Chat nicht wiederholt.

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 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, die Informationen zum Interaktionsereignis aufzeichnen oder so gut wie alles andere tun. Dieses Verhalten definiert im Wesentlichen die Google Chat-App.

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

Für jedes Interaktionsereignis empfangen Chat-Apps einen Anfragetext, 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 für Chat-Apps.

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

In Echtzeit antworten

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

Damit die Chat-App in Echtzeit antworten kann, muss sie ein Message-Objekt zurückgeben. Wenn Sie mit einer Nachricht im Gruppenbereich antworten möchten, kann das Message-Objekt die Objekte text, cardsV2 und accessoryWidgets enthalten. Informationen zur Verwendung mit anderen Antworttypen finden Sie in den folgenden Anleitungen:

• Interaktive Dialogfelder öffnen
• Vorschaulinks
• Von Nutzern eingereichte Informationen verarbeiten

Mit Nach­richt antworten

In diesem Beispiel erstellt und sendet Ihre Chat-App eine Textnachricht, wenn sie einem Gruppenbereich hinzugefügt wird. Weitere Informationen

Wenn Sie eine Nachricht senden möchten, wenn ein Nutzer Ihre Chat-App einem Gruppenbereich hinzufügt, muss Ihre Chat-App auf ein ADDED_TO_SPACE-Interaktionsereignis reagieren. Wenn Sie auf ADDED_TO_SPACE-Interaktionsereignisse mit einer Nachricht antworten möchten, verwenden Sie den folgenden Code:

/**
 * 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 Nachricht 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. Eine Chat-App muss beispielsweise auf den Nutzer reagieren, nachdem eine lang andauernde 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 Chat API-Übersicht.

Weitere Informationen

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