Auf Befehle der Google Chat App reagieren

Hinweis:In dieser Anleitung wird beschrieben, wie Sie eine interaktive Chat-App mit Chat API-Interaktionsereignissen erstellen. Sie können Ihre Chat-App auch als Google Workspace-Add‑on erstellen. Informationen dazu, welches Framework verwendet werden soll, finden Sie unter Interaktive Google Chat-Apps erstellen.

Auf dieser Seite wird erläutert, wie Sie Befehle als Google Chat-App einrichten und darauf reagieren.

Mit Befehlen können Nutzer wichtige Funktionen einer Chat-App entdecken und verwenden. Nur Chat-Apps können den Inhalt eines Befehls sehen. Wenn ein Nutzer beispielsweise eine Nachricht mit einem Slash-Befehl sendet, ist die Nachricht nur für den Nutzer und die Chat-App sichtbar.

Informationen dazu, ob Sie Befehle erstellen sollten und wie Sie Nutzerinteraktionen gestalten, finden Sie unter Alle Nutzeraktionen definieren.

Arten von Chat-App-Befehlen

Sie können Chat-App-Befehle als Slash-Befehle oder Schnellbefehle erstellen. So können Nutzer die einzelnen Befehlstypen finden und verwenden:

1. Slash-Befehle:Nutzer senden Befehle als Nachrichten, indem sie einen Schrägstrich (/) und dann einen vordefinierten Text wie /about eingeben. Für Chat-Apps kann auch Argumenttext für den Slash-Befehl erforderlich sein. Für den Slash-Befehl /search kann beispielsweise Argumenttext erforderlich sein, der für eine Suchanfrage verwendet wird.
2. Schnellbefehle:Nutzer können Befehle verwenden, indem sie das Menü über den Antwortbereich einer Chat-Nachricht öffnen. Um einen Befehl zu verwenden, klicken sie auf Hinzufügen und wählen einen Befehl aus dem Menü aus.

Die folgenden Bilder zeigen, wie Nutzer ein Menü mit Slash-Befehlen und Schnellbefehlen aufrufen:

• 

  Abbildung 1: Nutzer können Slash-Befehle entdecken und verwenden, indem sie im Antwortbereich einen Schrägstrich / und dann den Namen des Befehls eingeben.

• 
  Abbildung 2: Nutzer können Schnellbefehle über das Menü im Antwortbereich einer Chatnachricht aufrufen und verwenden.

Vorbereitung

Hinweis :Die Codebeispiele in diesem Leitfaden sind für die Ausführung als Google Cloud-Funktion für Node.js, Python und Java geschrieben.

Node.js

Eine Google Chat-App, die Interaktionsereignisse empfängt und darauf reagiert. Wenn Sie eine interaktive Chat-App mit einem HTTP-Dienst erstellen möchten, folgen Sie dieser Kurzanleitung.

Apps Script

Eine Google Chat-App, die Interaktionsereignisse empfängt und darauf reagiert. Wenn Sie eine interaktive Chat-App in Apps Script erstellen möchten, folgen Sie dieser Kurzanleitung.

Python

Eine Google Chat-App, die Interaktionsereignisse empfängt und darauf reagiert. Wenn Sie eine interaktive Chat-App mit einem HTTP-Dienst erstellen möchten, folgen Sie dieser Kurzanleitung.

Java

Eine Google Chat-App, die Interaktionsereignisse empfängt und darauf reagiert. Wenn Sie eine interaktive Chat-App mit einem HTTP-Dienst erstellen möchten, folgen Sie dieser Kurzanleitung.

Befehl einrichten

In diesem Abschnitt wird beschrieben, wie Sie die folgenden Schritte ausführen, um den Befehl einzurichten:

1. Geben Sie einen Namen und eine Beschreibung für den Befehl ein.
2. Befehl in der Google Cloud Console konfigurieren

Befehl benennen und beschreiben

Der Name eines Befehls ist das, was Nutzer eingeben oder auswählen, um die Chat-App aufzurufen. Unter dem Namen wird auch eine kurze Beschreibung angezeigt, um Nutzer weiter darüber zu informieren, wie der Befehl verwendet wird:

Abbildung 3: Name und Beschreibung eines Slash-Befehls.

Berücksichtigen Sie bei der Auswahl eines Namens und einer Beschreibung für Ihren Befehl die folgenden Empfehlungen:

So benennen Sie einen Befehl:

• Verwenden Sie kurze, beschreibende und umsetzbare Wörter oder Formulierungen, damit die Befehle für den Nutzer klar sind. Verwenden Sie beispielsweise Remind me anstelle des Namens Create a reminder.
• Verwenden Sie einen eindeutigen oder gängigen Namen für den Befehl. Wenn Ihr Befehl eine typische Interaktion oder Funktion beschreibt, können Sie einen gängigen Namen verwenden, den Nutzer kennen und erwarten, z. B. Settings oder Feedback. Verwenden Sie ansonsten eindeutige Befehlsnamen. Wenn Ihr Befehlsname für andere Chat-Apps identisch ist, muss der Nutzer ähnliche Befehle filtern, um Ihren Befehl zu finden und zu verwenden.

So beschreiben Sie einen Befehl:

• Halten Sie die Beschreibung kurz und klar, damit Nutzer wissen, was sie erwartet, wenn sie den Befehl verwenden.
• Informieren Sie Nutzer, wenn für den Befehl Formatierungsanforderungen gelten. Wenn Sie beispielsweise einen Slash-Befehl erstellen, für den Argumenttext erforderlich ist, legen Sie die Beschreibung auf Remind me to do [something] at [time] fest.
• Teilen Sie den Nutzern mit, ob die Chat-App allen Personen im Gruppenbereich antwortet oder nur dem Nutzer, der den Befehl aufruft. Für den Schnellbefehl About könnten Sie ihn beispielsweise so beschreiben: Learn about this app (Only visible to you).

Befehl in der Google Cloud Console konfigurieren

Wenn Sie einen Slash-Befehl oder Schnellbefehl erstellen möchten, geben Sie Informationen zum Befehl in der Konfiguration Ihrer Chatanwendung für die Google Chat API an.

Führen Sie die folgenden Schritte aus, um einen Befehl in der Google Chat API zu konfigurieren:

1. Klicken Sie in der Google Cloud Console auf das Menü  > APIs und Dienste > Aktivierte APIs und Dienste > Google Chat API.

   Zur Google Chat API-Seite

2. Klicken Sie auf Konfiguration.

3. Klicken Sie unter Befehle auf Befehl hinzufügen.

4. Geben Sie eine Befehls-ID, eine Beschreibung, einen Befehlstyp und einen Namen für den Befehl ein:

   • Befehls-ID:Eine Zahl zwischen 1 und 1.000, die Ihre Chat-App verwendet, um den Befehl zu erkennen und eine Antwort zurückzugeben.
   • Beschreibung:Der Text, der beschreibt, was der Befehl bewirkt. Beschreibungen dürfen maximal 50 Zeichen lang sein und können Sonderzeichen enthalten.
   • Befehlstyp:Wählen Sie entweder Schnellbefehl oder Slash-Befehl aus.
   • Geben Sie einen Namen für den Schnellbefehl oder Slash-Befehl an:
     • Name des Schnellbefehls:Der Anzeigename, den Nutzer im Menü auswählen, um den Befehl aufzurufen. Kann bis zu 50 Zeichen lang sein und Sonderzeichen enthalten. Beispiel: Remind me.
     • Name des Slash-Befehls:Der Text, den Nutzer eingeben, um den Befehl in einer Nachricht aufzurufen. Muss mit einem Schrägstrich beginnen, darf nur Text enthalten und kann bis zu 50 Zeichen lang sein. Beispiel: /remindMe.

5. Optional: Wenn Ihre Chat-App mit einem Dialogfeld auf den Befehl reagieren soll, wählen Sie das Kästchen Dialogfeld öffnen aus.

6. Klicken Sie auf Speichern.

Der Befehl ist jetzt für die Chat App konfiguriert.

Auf einen Befehl reagieren

Weitere Beispiele finden Sie unter Google Chat-App-Beispiele.

Wenn Nutzer einen Befehl verwenden, empfängt Ihre Chat-App ein Interaktionsereignis. Die Ereignisnutzlast enthält Metadaten mit Details zum aufgerufenen Befehl (einschließlich der Befehls-ID und des Befehlstyps), damit Sie eine entsprechende Antwort zurückgeben können.

Eine Chat-App antwortet privat auf den Slash-Befehl /help und erklärt, wie man Support erhält.

Um auf die einzelnen Befehlstypen zu reagieren, müssen Sie verschiedene Ereignistypen und Metadatenobjekte in der Ereignisnutzlast verarbeiten:

Befehlstyp	Ereignistyp	Befehlsmetadaten
Slash-Befehl	MESSAGE	message.slashCommand oder message.annotation.slashCommand
Schnellbefehl	APP_COMMAND	appCommandMetadata

In den folgenden Abschnitten erfahren Sie, wie Sie mit einer Nachricht auf einen Befehl reagieren.

Auf einen Slash-Befehl reagieren

Der folgende Code zeigt ein Beispiel für eine Chat-App, die auf den Slash-Befehl /about antwortet. Die Chat-App verarbeitet MESSAGE-Interaktionsereignisse, erkennt, ob das Interaktionsereignis die passende Befehls-ID enthält, und gibt eine private Nachricht zurück:

Node.js

node/avatar-app/index.js

Auf GitHub ansehen

/**
 * Handles slash and quick commands.
 *
 * @param {Object} event - The Google Chat event.
 * @param {Object} res - The HTTP response object.
 */
function handleAppCommands(event, res) {
  const {appCommandId, appCommandType} = event.appCommandMetadata;

  switch (appCommandId) {
    case ABOUT_COMMAND_ID:
      return res.send({
        privateMessageViewer: event.user,
        text: 'The Avatar app replies to Google Chat messages.'
      });
    case HELP_COMMAND_ID:
      return res.send({
        privateMessageViewer: event.user,
        text: 'The Avatar app replies to Google Chat messages.'
      });
  }
}

Apps Script

apps-script/avatar-app/avatar-app.gs

Auf GitHub ansehen

// Checks for the presence of a slash command in the message.
if (event.message.slashCommand) {
  // Executes the slash command logic based on its ID.
  // Slash command IDs are set in the Google Chat API configuration.
  switch (event.message.slashCommand.commandId) {
    case ABOUT_COMMAND_ID:
      return {
        privateMessageViewer: event.user,
        text: 'The Avatar app replies to Google Chat messages.'
      };
  }
}

Python

python/avatar-app/main.py

Auf GitHub ansehen

def handle_app_commands(event: Mapping[str, Any]) -> Mapping[str, Any]:
    """Handles slash and quick commands.

    Args:
        Mapping[str, Any] event: The Google Chat event.

    Returns:
        Mapping[str, Any]: the response
    """
    app_command_id = event["appCommandMetadata"]["appCommandId"]

    if app_command_id == ABOUT_COMMAND_ID:
        return {
            "privateMessageViewer": event["user"],
            "text": "The Avatar app replies to Google Chat messages.",
        }
    elif app_command_id == HELP_COMMAND_ID:
        return {
            "privateMessageViewer": event["user"],
            "text": "The Avatar app replies to Google Chat messages.",
        }
    return {}

Java

java/avatar-app/src/main/java/AvatarApp.java

Auf GitHub ansehen

/**
 * Handles slash and quick commands.
 *
 * @param event    The Google Chat event.
 * @param response The HTTP response object.
 */
private void handleAppCommands(JsonObject event, HttpResponse response) throws Exception {
  int appCommandId = event.getAsJsonObject("appCommandMetadata").get("appCommandId").getAsInt();

  switch (appCommandId) {
    case ABOUT_COMMAND_ID:
      Message aboutMessage = new Message();
      aboutMessage.setText("The Avatar app replies to Google Chat messages.");
      aboutMessage.setPrivateMessageViewer(new User()
          .setName(event.getAsJsonObject("user").get("name").getAsString()));
      response.getWriter().write(gson.toJson(aboutMessage));
      return;
    case HELP_COMMAND_ID:
      Message helpMessage = new Message();
      helpMessage.setText("The Avatar app replies to Google Chat messages.");
      helpMessage.setPrivateMessageViewer(new User()
          .setName(event.getAsJsonObject("user").get("name").getAsString()));
      response.getWriter().write(gson.toJson(helpMessage));
      return;
  }
}

Ersetzen Sie ABOUT_COMMAND_ID durch die Befehls-ID, die Sie beim Konfigurieren des Befehls in der Google Cloud Console angegeben haben.

Auf einen Schnellbefehl reagieren

Der folgende Code zeigt ein Beispiel für eine Chat-App, die auf den Schnellbefehl Hilfe antwortet. Die Chat-App verarbeitet APP_COMMAND-Interaktionsereignisse, erkennt, ob das Interaktionsereignis die passende Befehls-ID enthält, und gibt eine private Nachricht zurück:

Node.js

node/avatar-app/index.js

Auf GitHub ansehen

/**
 * Handles slash and quick commands.
 *
 * @param {Object} event - The Google Chat event.
 * @param {Object} res - The HTTP response object.
 */
function handleAppCommands(event, res) {
  const {appCommandId, appCommandType} = event.appCommandMetadata;

  switch (appCommandId) {
    case ABOUT_COMMAND_ID:
      return res.send({
        privateMessageViewer: event.user,
        text: 'The Avatar app replies to Google Chat messages.'
      });
    case HELP_COMMAND_ID:
      return res.send({
        privateMessageViewer: event.user,
        text: 'The Avatar app replies to Google Chat messages.'
      });
  }
}

Apps Script

apps-script/avatar-app/avatar-app.gs

Auf GitHub ansehen

/**
 * Handles the APP_COMMAND event type. This function is triggered when a user
 * interacts with a quick command within the Google Chat app.  It responds
 * based on the command ID.
 *
 * @param {Object} event The event object from Google Chat, containing details
 *     about the app command interaction.  It includes information like the
 *     command ID and the user who triggered it.
 */
function onAppCommand(event) {
  // Executes the quick command logic based on its ID.
  // Command IDs are set in the Google Chat API configuration.
  switch (event.appCommandMetadata.appCommandId) {
    case HELP_COMMAND_ID:
      return {
        privateMessageViewer: event.user,
        text: 'The Avatar app replies to Google Chat messages.'
      };
  }
}

Python

python/avatar-app/main.py

Auf GitHub ansehen

def handle_app_commands(event: Mapping[str, Any]) -> Mapping[str, Any]:
    """Handles slash and quick commands.

    Args:
        Mapping[str, Any] event: The Google Chat event.

    Returns:
        Mapping[str, Any]: the response
    """
    app_command_id = event["appCommandMetadata"]["appCommandId"]

    if app_command_id == ABOUT_COMMAND_ID:
        return {
            "privateMessageViewer": event["user"],
            "text": "The Avatar app replies to Google Chat messages.",
        }
    elif app_command_id == HELP_COMMAND_ID:
        return {
            "privateMessageViewer": event["user"],
            "text": "The Avatar app replies to Google Chat messages.",
        }
    return {}

Java

java/avatar-app/src/main/java/AvatarApp.java

Auf GitHub ansehen

/**
 * Handles slash and quick commands.
 *
 * @param event    The Google Chat event.
 * @param response The HTTP response object.
 */
private void handleAppCommands(JsonObject event, HttpResponse response) throws Exception {
  int appCommandId = event.getAsJsonObject("appCommandMetadata").get("appCommandId").getAsInt();

  switch (appCommandId) {
    case ABOUT_COMMAND_ID:
      Message aboutMessage = new Message();
      aboutMessage.setText("The Avatar app replies to Google Chat messages.");
      aboutMessage.setPrivateMessageViewer(new User()
          .setName(event.getAsJsonObject("user").get("name").getAsString()));
      response.getWriter().write(gson.toJson(aboutMessage));
      return;
    case HELP_COMMAND_ID:
      Message helpMessage = new Message();
      helpMessage.setText("The Avatar app replies to Google Chat messages.");
      helpMessage.setPrivateMessageViewer(new User()
          .setName(event.getAsJsonObject("user").get("name").getAsString()));
      response.getWriter().write(gson.toJson(helpMessage));
      return;
  }
}

Ersetzen Sie HELP_COMMAND_ID durch die Befehls-ID, die Sie beim Konfigurieren des Befehls in der Google Cloud Console angegeben haben.

Befehl testen

Informationen zum Testen des Befehls und des Codes finden Sie unter Interaktive Funktionen für Google Chat-Apps testen.

Informationen zum Testen und Verwenden des Befehls in der Chat-Benutzeroberfläche finden Sie in der Google Chat-Hilfe unter Apps in Google Chat verwenden.

Weitere Informationen

• Chat-App-Beispiele mit Befehlen ansehen
• Nachricht senden
• Interaktive Dialogfelder öffnen