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, wie 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 von Triggern oder UI-Interaktionen erhalten.
• Aktionen: Die Möglichkeiten, wie Chat-Apps auf Interaktionen reagieren können, z. B. durch das Senden von Nachrichten oder das Zurückgeben einer kartenbasierten Benutzeroberfläche.

Abbildung 1: Wenn ein Nutzer eine Chat-App zu einem Gruppenbereich hinzufügt, wird der Trigger Zu Gruppenbereich hinzugefügt ausgelöst und ein Ereignisobjekt gesendet. Um mit einer Nachricht zu antworten, verarbeitet die Chat-App das Ereignisobjekt und gibt eine Aktion zurück, die die Nachricht erstellt.

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

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

Vorbereitung

• Ein Google Workspace-Konto für Unternehmen mit Zugriff auf Google Chat.
• Google Cloud-Projekt erstellen
• OAuth-Zustimmungsbildschirm konfigurieren
• Aktivieren und konfigurieren Sie die Google Chat API.

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 innerhalb von 30 Sekunden eine Aktion synchron zurückgeben oder asynchron über die Chat API antworten.

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

Trigger

Trigger sind die spezifischen Möglichkeiten, wie Nutzer eine Chat-App über die Chat-Benutzeroberfläche aufrufen, z. B. mithilfe von @Erwähnungen oder App-Befehlen.

In der folgenden Tabelle finden Sie Chat-Trigger, eine Beschreibung und die typische Reaktion von Chat-Apps:

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 Gruppenbereichen für Direktnachrichten für Nutzer in seiner Organisation. Informationen zu von Administratoren installierten Chat-Apps finden Sie in der Google Workspace-Admin-Hilfe im Artikel Marketplace-Apps in Ihrer Domain installieren.	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.
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 in einem beliebigen Gruppenbereich erwähnt. Eine Nachricht mit einem Link, der dem URL-Muster für Linkvorschauen entspricht, wird gesendet. Gibt Text in das Mehrfachauswahlmenü eines selectionInput-Widgets ein.	Die Chat-App antwortet basierend auf dem Inhalt der Nachricht. Eine Chat-App antwortet beispielsweise mit einer Nachricht, hängt eine Linkvorschaukarte an oder schlägt Elemente in einem Mehrfachauswahlmenü 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 zuvor installiert hat, bleibt sie installiert, auch wenn ein Google Workspace-Administrator versucht, sie zu deinstallieren.	Die Chat-App entfernt alle eingehenden Benachrichtigungen, die für den Gruppenbereich konfiguriert sind (z. B. durch Löschen eines Webhooks), und löscht den internen Speicher. Chat-Apps können auf diesen Trigger nicht mit Nachrichten antworten, da sie nicht mehr Mitglied des Gruppenbereichs 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 mit der Chat-App oder interagiert mit einem Widget auf der Startseitenkarte.	Die Chat-App gibt ein RenderActions-Objekt zurück, das eine Startseitenkarte (pushCard) per Push-Benachrichtigung sendet oder die angezeigte Startseitenkarte (updateCard) aktualisiert.

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

Entwicklervorschau: Verfügbar im Rahmen des Google Workspace Developer Preview Program, das Vorabzugriff auf bestimmte Funktionen bietet.

Einstiegsprompts helfen Nutzern, die Funktionen Ihrer Chat-App zu entdecken, wenn sie eine leere 1:1-Direktnachricht mit Ihrer App öffnen. Sie können bis zu drei Einstiegsprompts konfigurieren.

So fügen Sie Einstiegsprompts hinzu und konfigurieren sie:

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

   Zur Seite „Chat API-Konfiguration“

2. Suchen Sie unter Interaktive Funktionen nach Einstiegsprompts und klicken Sie auf Prompt hinzufügen.

3. Geben Sie im Feld Rang (1–3) eine Zahl von 1 bis 3 ein, um die Anzeigereihenfolge festzulegen.

4. Wählen Sie unter Typauswahl aus, wie sich die Aufforderung verhalten soll:

   • Text-Prompt: Wenn der Nutzer auf den Prompt-Chip klickt, wird die Eingabezeile mit vordefiniertem Text gefüllt.
   • 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 die Eingabeaufforderung basierend auf Ihrer Typauswahl:

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

     1. Geben Sie unter Titel den Prompt-Titel ein, der auf dem Chip angezeigt werden soll (bis zu 30 Zeichen).
     2. Geben Sie unter Prompt-Text den Text ein, der in der Eingabezeile angezeigt werden soll (bis zu 60 Zeichen).
     3. Optional: Lokalisierte Titel und Texte für Nutzer in anderen Sprachen hinzufügen:
     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.

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 Netzwerkfehlers oder eines HTTPS-Statuscodes, der nicht 2xx ist), versucht Google Chat möglicherweise, die Nachricht innerhalb weniger Minuten noch einmal zuzustellen. Dies ist jedoch nicht garantiert. Daher kann es in bestimmten Situationen vorkommen, dass eine Chat-App dasselbe Ereignis mehrmals empfängt. Wenn die Anfrage erfolgreich abgeschlossen wird, aber eine ungültige Antwortnutzlast zurückgibt, wiederholt Google Chat die Anfrage nicht.

Ereignisobjekte

Chat-Apps erhalten 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 zu antworten oder eine Benutzeroberfläche zu aktualisieren.

Im Jahr 2025 wurden Google Chat-Apps um die Unterstützung von Add-on-Ereignissen erweitert. Dies ist seit Juli 2025 die Standardeinstellung für neue Chat-Apps. In der gesamten Chat-Dokumentation sind Add-on-Ereignisse der Standardereignistyp, der in Anleitungen und Codebeispielen verwendet wird. Die Dokumentation zu Chat-Ereignissen (für Chat-Apps, die keine Google Workspace-Add-ons sind) ist in minimierte Abschnitte unterteilt (z. B. Chat-Apps, die keine Add-ons sind: Interaktionsereignisse empfangen und darauf reagieren).

Ereignis- und Antworttypen bestimmen

Wenn Ihre Chat-App ein Ereignisobjekt empfängt, hängen die Struktur der Nutzlast und die Art der Antwort davon ab, ob Ihre Chat-App als Google Workspace-Add-on konfiguriert ist.

In der folgenden Tabelle können Sie nachsehen, welche Art von Ereignisobjekten Ihre App empfängt und wie sie reagieren soll:

App-Typ	Empfängt Add-on-Ereignisse (Standard für neue Apps, die nach Juli 2025 erstellt wurden)	Empfängt Chat-Ereignisse (Vorherige Standardeinstellung, vor Juli 2025)
Apps Script-Apps Prüfen Sie die Manifestdatei (appsscript.json).	Das Objekt chat wird in addOns konfiguriert: { "addOns": { "chat": {} } }	Das chat-Objekt wird im Stammverzeichnis des Manifests konfiguriert: { "chat": {} }
Andere Apps Sehen Sie sich die Seite Google Chat API Konfiguration an.	Das Kästchen „Diese Chat-App als Google Workspace-Add‑on erstellen“ ist aktiviert.	Das Kästchen „Diese Chat-App als Google Workspace-Add‑on erstellen“ ist nicht aktiviert.
Wo finde ich die Dokumentation?	In Leitfäden und Codebeispielen Referenzdokumentation zu Ereignissen: Add-on-Ereignisobjekte	Minimierte Abschnitte (z. B. Chat-Apps, die keine Add-ons sind: Interaktionsereignisse empfangen und darauf reagieren) Referenzdokumentation zu Ereignissen: Interaktionsereignisse der Chat API
Maßnahmen	Geben Sie eine Aktion zurück, z. B. DataActions oder RenderActions. Informationen zum Antworten mit einer Aktion	Gibt eine Message-Ressource zurück. Informationen zum Beantworten mit einer Nachricht

Nutzlasten von Ereignisobjekten

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

• Bei einem App-Startseite-Trigger (wenn ein Nutzer den Tab Startseite in einer 1:1-Direktnachricht mit der Chat-App öffnet) enthält das Objekt chat die Felder chat.user und chat.eventTime ohne ein Union-Feld payload. Wenn ein Nutzer auf eine Schaltfläche in der Startseitenkarte klickt, enthält das Ereignisobjekt chat.buttonClickedPayload zusammen mit commonEventObject.parameters (und commonEventObject.formInputs, wenn die Karte Formulareingaben enthält).
• Bei Interaktionen mit Gruppenbereichen und Nachrichten (Zu Gruppenbereich hinzugefügt, Nachricht, Aus Gruppenbereich entfernt, App-Befehl oder Interaktionen mit Schaltflächen und Widgets) enthält das Objekt chat die Elemente chat.user, chat.space, chat.eventTime und die entsprechende Interaktionsnutzlast:
  • messagePayload: Enthält die space, message und configCompleteRedirectUri, wenn ein Nutzer eine Nachricht sendet.
  • addedToSpacePayload: Enthält space, interactionAdd und configCompleteRedirectUri, wenn die Chat-App einem Gruppenbereich 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 den space, wenn ein Nutzer mit einem Widget interagiert, z. B. wenn er in ein Menü mit Mehrfachauswahl mit einer externen Datenquelle schreibt.
  • appCommandPayload: Enthält space, message, appCommandMetadata, isDialogEvent, dialogEventType und configCompleteRedirectUri, wenn ein Nutzer einen App-Befehl aufruft.

Informationen zu Add-on-Ereignisobjekten in Google 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 mehr 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.

Hinweis: In dieser Dokumentation wird davon ausgegangen, dass Ihre App Add-on-Ereignisse empfängt. Informationen dazu, welchen Antworttyp Ihre App zurückgeben muss, finden Sie unter Ereignis- und Antworttypen bestimmen.

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

• DataActions: Erstellt oder aktualisiert Chatnachrichten (CreateMessageAction, UpdateMessageAction) oder hängt Linkvorschauen (UpdateInlinePreviewAction) mit chatDataActionMarkup an.
• RenderActions: Erstellt, aktualisiert oder schließt eine Startseite oder ein Dialogfeld (pushCard, updateCard, endNavigation: "CLOSE_DIALOG") oder stellt dynamische Eingabevorschläge für ein Menü mit Mehrfachauswahl (modifyCard) bereit.
• AuthorizationError: Fordert Nutzer mit einer einfachen Autorisierungskarte (basic_authorization_prompt) auf, sich bei einem externen Dienst anzumelden oder 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 AddOnResponseService und CardService von Apps Script erstellen.

Antwort der Chat-App	Erforderliche Aktion, die zurückgegeben werden soll (JSON)	Erforderliche Aktion für die Rückgabe (Apps Script)
Nachricht senden oder Nachricht aktualisieren	DataActions (createMessageAction oder updateMessageAction)	DataActionsResponse
Links in Nachrichten, die Chat-Nutzer in einem Gruppenbereich senden, in der Vorschau anzeigen	DataActions (updateInlinePreviewAction)	DataActionsResponse
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 aus einer Karte oder einem Dialogfeld erfassen möchten, können Sie Auswahlmöglichkeiten vorschlagen, die auf den Eingaben der Nutzer in einem Mehrfachauswahlmenü basieren.	RenderActions (modifyCard)	ActionResponse
Konfiguration oder Autorisierung für einen externen Dienst anfordern.	AuthorizationError (basic_authorization_prompt)	AuthorizationException

Mit Nach­richt antworten

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

• Nachrichtenauslöser, z. B. wenn Nutzer eine Chat-App mit @erwähnen oder ihr eine Direktnachricht senden.
• Zu Gruppenbereich hinzugefügt-Trigger, z. B. wenn Nutzer die Chat-App über den Google Workspace Marketplace installieren oder einem Gruppenbereich hinzufügen.
• App-Befehl-Trigger, z. B. wenn Nutzer einen Slash-Befehl oder Schnellbefehl aufrufen.
• Klicks auf Schaltflächen in Karten in Nachrichten oder Dialogfeldern. Beispielsweise, wenn Nutzende Informationen eingeben und auf „Senden“ klicken.

Hinweis: Bei Auslösern vom Typ Aus Gruppenbereich entfernt können Chat-Apps nicht mit einer Nachricht antworten, da sie sich nicht mehr im Gruppenbereich befinden.

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

• Text, der Hyperlinks, @Erwähnungen und Emojis enthält. Weitere Informationen finden Sie unter Nachrichten formatieren.
• Eine oder mehrere Karten, die in einer Nachricht oder in einem neuen Fenster als Dialogfeld angezeigt werden können. Weitere Informationen finden Sie unter Karten für Google Chat-Apps erstellen.
• Ein oder mehrere Zubehör-Widgets, d. h. Schaltflächen, die nach dem Text oder den 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-Textnachricht, wenn sie einem Gruppenbereich hinzugefügt wird. Dazu reagiert sie auf den Trigger Zu Gruppenbereich hinzugefügt mit DataActions:

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 Textnachricht zurück:

Nachricht bearbeiten

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

Wenn Sie eine Chat-App-Nachricht als Antwort 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 Linkvorschau-Karte 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:

• Nach 30 Sekunden auf eine Interaktion reagieren (z. B. nach Abschluss einer langwierigen Aufgabe).
• Nachrichten nach einem Zeitplan senden oder Benachrichtigungen über Änderungen an externen Ressourcen senden.
• Aufgaben außerhalb des Gruppenbereichs ausführen, in dem die Interaktion stattgefunden hat.
• Aufgaben in Google 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. So vermeiden Sie, dass der Nutzer eine Fehlermeldung erhält, 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.

Weitere Informationen

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

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

Chat-Apps, die keine Google Workspace-Add-ons sind, erhalten 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 aktualisieren möchten, lesen Sie den Hilfeartikel Google Chat-App in ein Google Workspace-Add‑on umwandeln.

Arten von Interaktionsereignissen

Für jede 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. indem er die Chat-App mit @ erwähnt oder einen Slash-Befehl verwendet.	MESSAGE	Die Chat-App antwortet basierend auf dem Inhalt der Nachricht. Beispielsweise antwortet eine Chat-App 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 eine Chat-App zu einem Gruppenbereich 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	Die Chat-App entfernt alle eingehenden Benachrichtigungen, die für den Gruppenbereich konfiguriert sind (z. B. durch Löschen eines Webhooks), und löscht den internen Speicher.
Ein Nutzer klickt auf einer Karte in einer Nachricht, einem Dialogfeld oder auf der Startseite einer Chat-App auf eine Schaltfläche.	CARD_CLICKED	Die Chat-App verarbeitet und speichert entweder die vom Nutzer gesendeten Daten oder gibt eine andere Karte zurück.
Ein Nutzer öffnet die Startseite der Chat-App, indem er in einer Direktnachricht 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 die vom Nutzer gesendeten Daten oder gibt eine andere Karte zurück.
Ein Nutzer ruft einen Befehl mit einem 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 JSON-Beispielnutzlasten finden Sie unter Arten von Interaktionsereignissen in Chat-Apps und in der Referenzdokumentation zu EventType.

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.
• DialogEventType (REQUEST_DIALOG, SUBMIT_DIALOG oder CANCEL_DIALOG) gibt an, ob die Interaktion ein Dialogfeld öffnet, Informationen aus einem Dialogfeld sendet oder ein Dialogfeld schließt.

Chat-App, die kein Add-on ist, für den Empfang von Interaktionsereignissen konfigurieren

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

   Zur Seite „Chat API-Konfiguration“

2. Deaktivieren Sie unter Interaktive Funktionen die Option Diese Chat-App als Google Workspace-Add-on erstellen und konfigurieren Sie Funktionen, einen einzelnen Endpunkt für Verbindungseinstellungen (HTTP-Endpunkt-URL, Apps Script, Cloud Pub/Sub-Themenname oder Dialogflow), Befehle, Einstiegsprompts, Linkvorschauen und Sichtbarkeit.

3. Klicken Sie auf Speichern.

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

Wenn Sie in einer Chat-App, die kein Add-on ist, synchron antworten möchten, geben Sie direkt ein Message-Objekt zurück. Im folgenden Beispiel wird auf ein ADDED_TO_SPACE-Interaktionsereignis mit einer Textnachricht 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`.'
  };
}