Google verwendet KI-Technologie, um Inhalte in Ihre bevorzugte Sprache zu übersetzen. KI-Übersetzungen können Fehler enthalten.

Nutzerinteraktionen empfangen und darauf reagieren

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

Zum Erstellen interaktiver Oberflächen für Chat-Apps verwenden Sie die folgenden Komponenten:

Trigger: Die Möglichkeiten, mit denen Google Chat-Nutzer eine Chat-App aufrufen können, z. B. indem sie sie einem Gruppenbereich hinzufügen oder ihr eine Nachricht senden.
Ereignisobjekte: Die Daten, die Chat-Apps über Trigger oder UI-Interaktionen erhalten.
Aktionen: Die Möglichkeiten, wie Chat-Apps auf Interaktionen reagieren können, z. B. durch Senden von Nachrichten oder Zurückgeben einer kartenbasierten Benutzeroberfläche.

Die Chat-App empfängt ein Ereignisobjekt von einem „Added to space“-Trigger. — **Abbildung 1**: Wenn ein Nutzer einem Gruppenbereich eine Chat-App hinzufügt, wird der Trigger **Added to space** ausgelöst und ein Ereignisobjekt gesendet. Wenn Sie mit einer Nachricht antworten möchten, verarbeitet die Chat-App das Ereignisobjekt und gibt eine Aktion zurück, mit der die Nachricht erstellt wird.

Chat-Apps können Oberflächen auf folgende Weise erstellen und anzeigen:

Nachrichten, die Text, statische oder interaktive Karten und Zubehör-Schaltflächen enthalten können.
Startseiten (App-Startseite), die auf dem Tab Startseite von 1:1-Direktnachrichten mit der Chat App angezeigt werden.
Dialogfelder sind Karten, die in einem neuen Fenster geöffnet werden und Nutzer in der Regel auffordern, Informationen anzugeben.
Linkvorschauen – Karten, die Informationen zu einem externen Dienst in der Vorschau anzeigen.

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 und konfigurieren

So funktionieren Nutzerinteraktionen

Wenn ein Nutzer mit einer Chat-App interagiert, ruft Google Chat einen konfigurierten Trigger auf und sendet ein Ereignisobjekt an den Endpunkt oder die Funktion Ihrer Chat-App. Ihre Chat-App verarbeitet das Ereignisobjekt und kann entweder synchron eine Aktion zurückgeben (innerhalb von 30 Sekunden) oder asynchron über die Chat API antworten.

Das folgende Diagramm zeigt, wie Google Chat-Apps Nutzerinteraktionen verarbeiten und darauf reagieren:

Architektur für die Verarbeitung von Nutzerinteraktionen durch Google Chat-Apps.

Trigger

Auslöser sind die spezifischen Methoden, mit denen Nutzer eine Chat-App über die Chat-Benutzeroberfläche aufrufen, z. B. durch Erwähnungen oder App-Befehle.

In der folgenden Tabelle finden Sie Chat-Trigger, eine Beschreibung und Informationen dazu, wie Chat-Apps in der Regel reagieren:

Trigger	Beschreibung	Typische Antwort
In Gruppenbereich aufgenommen	Ein Nutzer fügt die Chat-App einem Gruppenbereich hinzu oder ein Google Workspace-Administrator installiert die Chat-App in Direktnachrichtenbereichen für Nutzer in seiner Organisation. Weitere Informationen zu von Administratoren installierten Chat-Apps finden Sie in der Google Workspace-Admin-Hilfe unter Marketplace-Apps in Ihrer Domain installieren.	Die Chat-App sendet eine Onboarding-Nachricht, in der erklärt wird, was die App macht und wie Nutzer im Gruppenbereich mit ihr interagieren können.
Botschaft	Ein Nutzer interagiert mit der Chat-App in einer Nachricht auf eine der folgenden Arten: Sendet eine Nachricht in einem Direktnachrichtenbereich mit der Chat App. Die Chat-App wird in einem beliebigen Bereich per @-Erwähnung erwähnt. Sendet eine Nachricht mit einem Link, der dem URL-Muster für Linkvorschauen entspricht. Gibt Text in das Multiselect-Menü eines `selectionInput`-Widgets ein.	Die Chat-App antwortet auf Grundlage des Inhalts der Nachricht. Eine Chat-App antwortet beispielsweise mit einer Nachricht, hängt eine Linkvorschaukarte an oder schlägt Elemente in einem Menü mit Mehrfachauswahl vor.
Aus Gruppenbereich entfernt	Ein Nutzer entfernt die Chat-App aus einem Gruppenbereich oder ein Google Workspace-Administrator deinstalliert die Chat-App für einen Nutzer in seiner Organisation. Nutzer können keine Chat-Apps entfernen, die von ihrem Administrator installiert wurden. Wenn ein Nutzer die Chat App bereits installiert hat, bleibt sie installiert, unabhängig davon, ob ein Google Workspace-Administrator versucht, sie zu deinstallieren.	In der Chat App werden alle eingehenden Benachrichtigungen entfernt, die für den Gruppenbereich konfiguriert sind (z. B. durch Löschen eines Webhooks), und der interne Speicher wird geleert. Chat-Apps können nicht mit Nachrichten auf diesen Trigger reagieren, da sie kein Mitglied des Gruppenbereichs mehr sind.
App-Befehl	Ein Nutzer ruft einen Chat-App-Befehl auf, z. B. einen Slash-Befehl, einen Schnellbefehl oder eine Nachrichtenaktion.	Die Chat-App antwortet auf den Befehl. Beispielsweise antwortet sie mit einer Nachricht oder öffnet ein Dialogfeld.
App-Startseite	Ein Nutzer öffnet den Tab Startseite in einem 1:1-Direktnachrichtenbereich (DM) mit der Chat App oder interagiert mit einem Widget auf der Startseitenkarte.	Die Chat-App gibt ein `RenderActions`-Objekt zurück, mit dem eine Homepagekarte (`pushCard`) eingefügt oder die angezeigte Homepagekarte (`updateCard`) aktualisiert wird.

Sie konfigurieren die Endpunkte oder Callback-Funktionen für diese Trigger in der Google Cloud Console auf der Seite Konfiguration der Chat API. Eine detaillierte Anleitung finden Sie unter Google Chat API konfigurieren.

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:

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

Zur Seite „Chat API Configuration“
Suchen Sie unter Interaktive Funktionen nach Starter-Prompts und klicken Sie auf Prompt hinzufügen.
Geben Sie im Feld Rang (1–3) eine Zahl zwischen 1 und 3 ein, um die Reihenfolge der Anzeige festzulegen.
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.
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.
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 vorkommen, dass eine Chat-App in bestimmten Situationen dasselbe Ereignis mehrmals empfängt. Wenn die Anfrage erfolgreich abgeschlossen wird, aber eine ungültige Antwortnutzlast zurückgegeben wird, wird die Anfrage in Google Chat nicht wiederholt.

Ereignisobjekte

Chat-Apps empfangen Ereignisobjekte, wenn ein Chat-Trigger ausgeführt wird oder wenn Chat-Nutzer mit einer Benutzeroberfläche der Chat-App interagieren, z. B. auf eine Schaltfläche klicken oder ein Dialogfeld senden. Mit dem Ereignisobjekt können Sie Interaktionsdaten verwenden, um auf Nutzeraktionen zu reagieren oder eine Benutzeroberfläche zu aktualisieren.

Nutzlasten von Ereignisobjekten

Jedes Chat-Ereignisobjekt enthält ein commonEventObject-Objekt mit Host- und Plattformdetails (hostApp: "CHAT", clientPlatform, userLocale, userTimezone, parameters und formInputs) sowie ein chat-Objekt mit Chatspezifischem Kontext:

Bei einem App Home-Trigger (wenn ein Nutzer den Tab Home in einer 1:1-Direktnachricht mit der Chat-App öffnet) enthält das chat-Objekt chat.user und chat.eventTime ohne ein payload-Feld. Wenn ein Nutzer auf einen Button auf der Startseitenkarte klickt, enthält das Ereignisobjekt chat.buttonClickedPayload sowie commonEventObject.parameters (und commonEventObject.formInputs, wenn die Karte Formulareingaben enthält).
Bei Interaktionen mit Gruppenbereichen und Nachrichten (Dem Gruppenbereich hinzugefügt, Nachricht, Aus Gruppenbereich entfernt, App-Befehl oder Interaktionen mit Schaltflächen und Widgets) enthält das chat-Objekt chat.user, chat.space, chat.eventTime und die entsprechende Interaktionsnutzlast:
- messagePayload: Enthält space, message und configCompleteRedirectUri, wenn ein Nutzer eine Nachricht sendet.
- addedToSpacePayload: Enthält space, interactionAdd und configCompleteRedirectUri, wenn die Chat-App einem Bereich hinzugefügt wird.
- removedFromSpacePayload: Enthält die space, wenn die Chat-App aus einem Gruppenbereich entfernt wird.
- buttonClickedPayload: Enthält space, message, isDialogEvent und dialogEventType, wenn ein Nutzer auf eine Schaltfläche auf einer Karte oder in einem Dialogfeld klickt.
- widgetUpdatedPayload: Enthält die space, wenn ein Nutzer mit einem Widget interagiert, z. B. wenn er in ein Mehrfachauswahlmenü mit einer externen Datenquelle eingibt.
- appCommandPayload: Enthält space, message, appCommandMetadata, isDialogEvent, dialogEventType und configCompleteRedirectUri, wenn ein Nutzer einen App-Befehl aufruft.

Weitere Informationen zu Add-on-Ereignisobjekten in Chat und anderen Google Workspace-Anwendungen finden Sie unter Ereignisobjekte.

Antwort bereitstellen

In diesem Abschnitt wird erläutert, wie Chat-Apps Aktionen verwenden, um synchron auf Nutzerinteraktionen zu reagieren.

Wenn eine Chat-App mit einer Aktion reagieren soll, muss sie innerhalb von 30 Sekunden antworten. Die Antwort muss sich auf den Gruppenbereich beziehen, in dem die Interaktion stattgefunden hat. Für diese synchronen Antworten ist keine Authentifizierung erforderlich. Wenn Ihre Chat-App länger als 30 Sekunden benötigt oder außerhalb des Gruppenbereichs agieren muss, richten Sie die Authentifizierung ein und antworten Sie asynchron mit der Google Chat API.

Um synchron auf Nutzerinteraktionen zu reagieren, verarbeitet Ihre Chat-App das eingehende Ereignisobjekt und gibt eines der folgenden JSON-Objekte zurück:

DataActions: Erstellt oder aktualisiert Chatnachrichten (CreateMessageAction, UpdateMessageAction) oder fügt Link-Vorschauen (UpdateInlinePreviewAction) mit chatDataActionMarkup an.
RenderActions: Erstellt, aktualisiert oder schließt eine Startseite oder ein Dialogfeld (pushCard, updateCard, endNavigation: "CLOSE_DIALOG") oder bietet dynamische Vorschläge für die Eingabe in ein Menü mit Mehrfachauswahl (modifyCard).
AuthorizationError: Fordert Nutzer mit einer einfachen Autorisierungskarte (basic_authorization_prompt) auf, sich bei einem externen Dienst anzumelden oder sich dort zu authentifizieren.

In der folgenden Tabelle sehen Sie, wie Chat-Apps mit Aktionen reagieren können. Chat-Apps können JSON-Objekte direkt zurückgeben oder die Antwort mit den Apps Script-Funktionen AddOnResponseService und CardService erstellen.

Antwort der Chat-App	Erforderliche Aktion zum Zurückgeben (JSON)	Erforderliche Aktion für die Rückgabe (Apps Script)
Nachricht senden oder Nachricht aktualisieren	`DataActions` (`createMessageAction` oder `updateMessageAction`)	`DataActionsResponse`
Vorschaulinks in Nachrichten, die Chat-Nutzer in einem Gruppenbereich senden.	`DataActions` (`updateInlinePreviewAction`)	`DataActionsResponse`
Eine Startseite auf dem Tab Startseite einer Direktnachricht rendern oder aktualisieren.	`RenderActions` (`pushCard` oder `updateCard`)	`ActionResponse`
Dialogfeld öffnen, aktualisieren oder schließen.	`RenderActions` (`pushCard`, `updateCard` oder `endNavigation: "CLOSE_DIALOG"`)	`ActionResponse`
Wenn Sie Informationen von einer Karte oder einem Dialogfeld erfassen möchten, schlagen Sie Auswahlmöglichkeiten vor, die auf dem basieren, was Nutzer in ein Mehrfachauswahlmenü eingeben.	`RenderActions` (`modifyCard`)	`ActionResponse`
Konfiguration oder Autorisierung für einen externen Dienst anfordern	`AuthorizationError` (`basic_authorization_prompt`)	`AuthorizationException`

Mit Nachricht antworten

Chat-Apps können mit einer Nachricht auf die folgenden Trigger oder Interaktionen reagieren:

Nachricht-Trigger, z. B. wenn Nutzer eine Chat-App @erwähnen oder ihr eine Direktnachricht senden.
Auslöser vom Typ „Zum Gruppenbereich hinzugefügt“, z. B. wenn Nutzer die Chat-App über den Google Workspace Marketplace installieren oder einem Gruppenbereich hinzufügen.
App-Befehle werden ausgelöst, z. B. wenn Nutzer einen Slash-Befehl oder einen Schnellbefehl aufrufen.
Button-Klicks auf Karten in Nachrichten oder Dialogfeldern. Das kann beispielsweise passieren, wenn Nutzer Informationen eingeben und auf „Senden“ klicken.

Chat-Apps können in einer Nachricht Folgendes enthalten:

Text mit Hyperlinks, @Erwähnungen und Emojis. Weitere Informationen
Eine oder mehrere Karten, die in einer Nachricht angezeigt oder in einem neuen Fenster als Dialogfeld geöffnet werden können. Weitere Informationen finden Sie unter Karten für Google Chat-Apps erstellen.
Ein oder mehrere Zubehör-Widgets, die als Schaltflächen nach Text oder Karten in einer Nachricht angezeigt werden.

Wenn Sie mit einer Nachricht antworten möchten, geben Sie DataActions mit einem CreateMessageAction-Objekt zurück:

{
  "hostAppDataAction": {
    "chatDataAction": {
      "createMessageAction": {
        "message": <var>MESSAGE</var>
      }
    }
  }
}

Ersetzen Sie MESSAGE durch eine Message-Ressource aus der Chat API.

Im folgenden Beispiel erstellt und sendet eine Chat-App eine Onboarding-Nachricht, wenn sie einem Gruppenbereich hinzugefügt wird. Dazu reagiert sie mit DataActions auf den Trigger Dem Gruppenbereich hinzugefügt:

Node.js

/**
 * Sends an onboarding message when the Chat app is added to a space.
 *
 * @param {Object} req The request object from Google Chat.
 * @param {Object} res The response object from the Chat app.
 */
exports.cymbalApp = function cymbalApp(req, res) {
  const chatEvent = req.body.chat;
  // Send an onboarding message when added to a Chat space
  if (chatEvent.addedToSpacePayload) {
    res.json({ hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
      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`.'
    }}}}});
  }
};

Python

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.
  """
  chat_event = request.get_json()["chat"]
  if "addedToSpacePayload" in chat_event:
    return json.jsonify({ "hostAppDataAction": { "chatDataAction": {
      "createMessageAction": { "message": {
        "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`.'
      }}
    }}})

Java

@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 GenericJson onEvent(@RequestBody JsonNode event) throws Exception {
    JsonNode chatEvent = event.at("/chat");
    if (!chatEvent.at("/addedToSpacePayload").isEmpty()) {
      return new GenericJson() { {
        put("hostAppDataAction", new GenericJson() { {
          put("chatDataAction", new GenericJson() { {
            put("createMessageAction", new GenericJson() { {
              put("message", 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`."
              ));
            } });
          } });
        } });
      } };
    }
    return new GenericJson();
  }
}

Apps Script

/**
 * Sends an onboarding message when the Chat app is added to a space.
 *
 * @param {Object} event The event object from Google Chat.
 * @return {Object} Response from the Chat app.
 */
function onAddedToSpace(event) {
  return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
    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:

Beispiel für eine Onboarding-Nachricht

Nachricht bearbeiten

Chat-Apps können auch gesendete Nachrichten aktualisieren. Eine Chat-App kann beispielsweise eine Nachricht aktualisieren, nachdem ein Nutzer ein Dialogfeld gesendet oder auf einer Karte in einer Nachricht auf eine Schaltfläche geklickt hat.

Wenn Sie eine Nachricht einer Chat-App als Reaktion auf eine Interaktion aktualisieren möchten, geben Sie DataActions mit einem UpdateMessageAction zurück:

{
  "hostAppDataAction": {
    "chatDataAction": {
      "updateMessageAction": {
        "message": <var>MESSAGE</var>
      }
    }
  }
}

Ersetzen Sie MESSAGE durch eine Message-Ressource aus der Chat API.

Chat-Apps können auch eine von einem Nutzer gesendete Nachricht aktualisieren, um eine Linkvorschaukarte mit updateInlinePreviewAction anzuhängen. Weitere Informationen finden Sie unter Vorschaulinks.

Asynchron mit der Google Chat API antworten

Anstatt eine Aktion synchron zurückzugeben, müssen Chat-Apps möglicherweise die Google Chat API aufrufen, um auf eine Interaktion zu reagieren oder proaktive Nachrichten zu senden. Chat-Apps müssen beispielsweise die Google Chat API aufrufen, um Folgendes zu tun:

Auf eine Interaktion nach 30 Sekunden reagieren, z. B. nach Abschluss einer zeitaufwendigen Aufgabe.
Nachrichten zu einem bestimmten Zeitpunkt senden oder Benachrichtigungen über Änderungen an externen Ressourcen senden
Aufgaben außerhalb des Bereichs ausführen, in dem die Interaktion stattgefunden hat
Aufgaben in Chat ausführen, die nicht als synchrone Aktionen verfügbar sind, z. B. Gruppenbereiche auflisten oder Mitglieder zu einem Gruppenbereich hinzufügen.
Aufgaben im Namen eines Chat-Nutzers ausführen (erfordert Nutzerauthentifizierung).

Wenn Sie nach 30 Sekunden auf eine Interaktion antworten, müssen Sie den Empfang des Ereignisobjekts innerhalb von 30 Sekunden bestätigen, indem Sie eine leere Antwort zurückgeben. Andernfalls wird dem Nutzer eine Fehlermeldung angezeigt, dass Ihre Chat-App nicht reagiert:

Node.js

async function onEvent(req, res) {
  // Trigger asynchronous job that will respond using the Google Chat API.
  ...

  // Respond with an empty response to the Google Chat platform.
  return res.send({});
};

Python

def on_event(event) -> dict:
  # Trigger asynchronous job that will respond using the Google Chat API.
  ...

  // Respond with an empty response to the Google Chat platform.
  return {}

Java

public String onEvent(JsonNode event) {
  // Trigger asynchronous job that will respond using the Google Chat API.
  ...

  // Respond with an empty response to the Google Chat platform.
  return "{}";
}

Apps Script

function onEvent(event) {
  // Trigger asynchronous job that will respond using the Google Chat API.
  ...

  // Respond with an empty response to the Google Chat platform.
  return null;
}

Wenn Sie eine Nachricht über die Chat API senden möchten, richten Sie die Authentifizierung ein und rufen Sie die Methode spaces.messages.create auf. Eine Anleitung finden Sie unter Nachricht senden. Anleitungen zur Verwendung zusätzlicher Chat API-Methoden finden Sie in der Chat API-Übersicht.

Chat-Apps, die keine Add‑ons sind: Nutzerinteraktionen empfangen und darauf reagieren

Chat-Apps, die keine Google Workspace-Add‑ons sind, empfangen Chat API-Interaktionsereignisse (Event) anstelle von Google Workspace-Add‑on-Ereignisobjekten (EventObject) und antworten mit einer Message-Ressource anstelle einer Aktion.

Wenn Sie eine Chat-App, die kein Add‑on ist, auf das Google Workspace-Add‑on-Framework umstellen möchten, lesen Sie den Abschnitt Google Chat-App in ein Google Workspace-Add‑on umwandeln.

Arten von Interaktionsereignissen

Bei jeder Art von Nutzerinteraktion sendet Google Chat einer Chat-App, die kein Add‑on ist, ein Event-Objekt, dessen Typ durch das Feld eventType dargestellt wird:

Nutzerinteraktion	`eventType`	Typische Antwort einer Chat-App, die kein Add-on ist
Ein Nutzer sendet eine Nachricht an eine Chat-App, z. B. durch @Erwähnung der Chat-App oder durch Verwendung eines Slash-Befehls.	`MESSAGE`	Die Chat-App antwortet auf Grundlage des Inhalts der Nachricht. Eine Chat-App antwortet beispielsweise auf den Slash-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.	`ADDED_TO_SPACE`	Die Chat-App sendet eine Onboarding-Nachricht, in der erklärt wird, was sie tut und wie Nutzer im Gruppenbereich mit ihr interagieren können.
Ein Nutzer entfernt eine Chat-App aus einem Gruppenbereich.	`REMOVED_FROM_SPACE`	In der Chat App werden alle eingehenden Benachrichtigungen entfernt, die für den Gruppenbereich konfiguriert sind (z. B. durch Löschen eines Webhooks), und der interne Speicher wird geleert.
Ein Nutzer klickt in einer Chat-App-Nachricht, einem Dialogfeld oder auf der Startseite auf eine Schaltfläche auf einer Karte.	`CARD_CLICKED`	Die Chat-App verarbeitet und speichert entweder alle vom Nutzer eingegebenen Daten oder gibt eine andere Karte zurück.
Ein Nutzer öffnet die Startseite der Chat-App, indem er in einer 1:1-Nachricht auf den Tab Startseite klickt.	`APP_HOME`	Die Chat-App gibt eine statische oder interaktive Karte von der Startseite zurück.
Ein Nutzer sendet ein Formular über die Startseite der Chat App.	`SUBMIT_FORM`	Die Chat-App verarbeitet und speichert entweder alle vom Nutzer eingegebenen Daten oder gibt eine andere Karte zurück.
Ein Nutzer ruft einen Befehl über einen Schnellbefehl auf.	`APP_COMMAND`	Die Chat-App antwortet basierend auf dem aufgerufenen Befehl. Eine Chat-App antwortet beispielsweise auf den Befehl About mit einer Nachricht, in der die Aufgaben erläutert werden, die die Chat-App ausführen kann.

Eine Liste aller unterstützten Interaktionsereignisse und Beispiel-JSON-Nutzlasten finden Sie unter Arten von Chat-App-Interaktionsereignissen und in der EventType-Referenzdokumentation.

Interaktionsereignisse aus Dialogfeldern

Wenn Ihre Chat-App, die kein Add-on ist, Dialogfelder öffnet, enthält das Interaktionsereignis die folgenden zusätzlichen Informationen, die Sie zum Verarbeiten einer Antwort verwenden können:

Das Feld isDialogEvent ist auf true gesetzt.
Mit DialogEventType>(REQUEST_DIALOG, SUBMIT_DIALOG oder CANCEL_DIALOG) wird angegeben, ob durch die Interaktion ein Dialogfeld geöffnet, Informationen aus einem Dialogfeld gesendet oder ein Dialogfeld geschlossen wird.

Chat-App konfigurieren, die kein Add-on ist, um Interaktionsereignisse zu empfangen

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

Zur Seite „Chat API Configuration“
Deaktivieren Sie unter Interaktive Funktionen die Option Diese Chat-App als Google Workspace-Add-on erstellen und konfigurieren Sie Funktionalität, einen einzelnen Verbindungseinstellungen-Endpunkt (HTTP-Endpunkt-URL, Apps Script, Cloud Pub/Sub-Themenname oder Dialogflow), Befehle, Einstiegsprompts, Linkvorschauen und Sichtbarkeit.
Klicken Sie auf Speichern.

Mit einer Nachricht in einer Chat-App antworten, die kein Add‑on ist

Wenn Sie synchron in einer Chat-App antworten möchten, die kein Add-on ist, geben Sie direkt ein Message-Objekt zurück. Im folgenden Beispiel wird auf ein ADDED_TO_SPACE-Interaktionsereignis mit einer Nachricht geantwortet:

Node.js

/**
 * 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`.'
    });
  }
};

Python

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({})

Java

@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();
    }
  }
}

Apps Script

/**
 * 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`.'
  };
}

Nutzerinteraktionen empfangen und darauf reagieren Mit Sammlungen den Überblick behalten Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.

Vorbereitung

So funktionieren Nutzerinteraktionen

Trigger

Einstiegsprompts konfigurieren

Wiederholungsversuche für HTTP-Aufrufe an Ihren Dienst verarbeiten

Ereignisobjekte

Nutzlasten von Ereignisobjekten

Antwort bereitstellen

Mit Nach­richt antworten

Node.js

Python

Java

Apps Script

Nachricht bearbeiten

Asynchron mit der Google Chat API antworten

Node.js

Python

Java

Apps Script

Weitere Informationen

Chat-Apps, die keine Add‑ons sind: Nutzerinteraktionen empfangen und darauf reagieren

Arten von Interaktionsereignissen

Interaktionsereignisse aus Dialogfeldern

Chat-App konfigurieren, die kein Add-on ist, um Interaktionsereignisse zu empfangen

Mit einer Nachricht in einer Chat-App antworten, die kein Add‑on ist

Node.js

Python

Java

Apps Script

Nutzerinteraktionen empfangen und darauf reagieren

Mit Nachricht antworten