Slash-Befehle in einer Google Chat-App beantworten

Auf dieser Seite wird erläutert, wie Sie Slash-Befehle für Ihre Google Chat App einrichten und darauf reagieren.

Ein Slash-Befehl ist eine gängige Methode, mit der Nutzer eine Chat-App aufrufen und mit ihr interagieren. Mit Slash-Befehlen können Nutzer auch wichtige Funktionen einer Chat-App entdecken und verwenden.

Um einen Slash-Befehl zu verwenden, geben Nutzer einen Schrägstrich (/) und dann einen kurzen Textbefehl ein, z. B. /about, um Informationen zur Chat-App zu erhalten. Nutzer können verfügbare Slash-Befehle finden, indem sie einen Schrägstrich in Google Chat eingeben. Daraufhin wird ein Fenster mit den verfügbaren Befehlen für die Chat-App angezeigt:

Fenster für Slash-Befehle
Abbildung 1: Das Fenster, das angezeigt wird, wenn Nutzer einen Schrägstrich in Google Chat eingeben.

Informationen dazu, ob Sie Befehlszeilen einrichten sollten und wie Sie Nutzerinteraktionen gestalten, finden Sie unter Alle User Journeys definieren.

Slash-Befehle mit privaten Antworten

Wenn ein Nutzer eine Nachricht sendet, die einen Slash-Befehl enthält, ist die Nachricht nur für den Nutzer und die Chat-App sichtbar. Wenn Sie Ihre Chat-App so konfiguriert haben, dass Gruppenbereichen mit mehreren Personen hinzugefügt werden, können Sie auf den Slash-Befehl privat antworten, damit die Interaktion zwischen dem Nutzer und der Chat-App vertraulich bleibt.

Wenn Nutzer beispielsweise mehr über eine Chat-App erfahren möchten, die sie in einem Gruppenbereich entdeckt haben, können sie Befehle wie /about oder /help verwenden. Damit nicht alle anderen Nutzer im Gruppenbereich benachrichtigt werden, kann die Chat-App privat antworten und Informationen zur Verwendung der Chat-App und zur Kontaktaufnahme mit dem Support enthalten.

Vorbereitung

Node.js

Eine Google Chat-App, für die interaktive Funktionen aktiviert sind. Wenn Sie eine interaktive Chat-App mit einem HTTP-Dienst erstellen möchten, folgen Sie dieser Kurzanleitung.

Apps Script

Eine Google Chat-App, für die interaktive Funktionen aktiviert sind. Wenn Sie eine interaktive Chat-App in Apps Script erstellen möchten, folgen Sie dieser Kurzanleitung.

Python

Eine Google Chat-App, für die interaktive Funktionen aktiviert sind. Wenn Sie eine interaktive Chat-App mit einem HTTP-Dienst erstellen möchten, folgen Sie dieser Kurzanleitung.

Java

Eine Google Chat App mit aktivierten interaktiven Funktionen. Führen Sie diese Kurzanleitung aus, um eine interaktive Chat-App mit einem HTTP-Dienst zu erstellen.

Slash-Befehl einrichten

In diesem Abschnitt wird beschrieben, wie Sie einen Befehl mit einem Schrägstrich einrichten:

  1. Erstellen Sie einen Namen für Ihren Slash-Befehl.
  2. Konfigurieren Sie den Befehlsvorschlag in der Google Chat API.

Namen für den Slash-Befehl festlegen

Den Namen eines Slash-Befehls geben Nutzer in eine Chatnachricht ein, um die Chat-App aufzurufen. Unter dem Namen wird auch eine kurze Beschreibung angezeigt, die Nutzer über die Verwendung des Befehls informiert:

Name und Beschreibung des Slash-Befehls
Abbildung 2: Name und Beschreibung eines Slash-Befehls

Beachte bei der Auswahl eines Namens und einer Beschreibung für deinen Slash-Befehl die folgenden Empfehlungen:

  • So benennen Sie einen Slash-Befehl:

    • Verwenden Sie kurze, beschreibende und umsetzbare Wörter oder Wortgruppen, damit die Befehle für die Nutzer klar und einfach sind. Verwenden Sie beispielsweise /remindMe anstelle von /createAReminder.
    • Wenn Ihr Befehl mehr als ein Wort enthält, erleichtern Sie Nutzern das Lesen, indem Sie das erste Wort komplett kleinschreiben und dann den ersten Buchstaben der zusätzlichen Wörter großschreiben. Verwenden Sie beispielsweise /updateContact anstelle von /updatecontact.
    • Überlegen Sie, ob Sie einen eindeutigen oder einen gängigen Namen für den Befehl verwenden möchten. 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. Versuchen Sie andernfalls, eindeutige Befehlsnamen zu verwenden. Wenn Ihr Befehlsname für andere Chat-Apps identisch ist, muss der Nutzer nach ähnlichen Befehlen filtern, um Ihren zu finden und zu verwenden.

  • So beschreibst du deinen Slash-Befehl:

    • Die Beschreibung sollte kurz und klar sein, damit Nutzer wissen, was sie erwartet, wenn sie den Befehl aufrufen.
    • Informieren Sie die Nutzer, ob es Formatierungsanforderungen für den Befehl gibt. Wenn Sie beispielsweise einen /remindMe-Befehl erstellen, für den Argumenttext erforderlich ist, legen Sie die Beschreibung etwa auf Remind me to do [something] at [time] fest.
    • Informieren Sie die Nutzer darüber, ob die Chat-App an alle Nutzer im Gruppenbereich oder privat an den Nutzer antwortet, der den Befehl ausführt. Den Befehl „Schrägstrich“ /about könnten Sie beispielsweise als Learn about this app (Only visible to you) beschreiben.

Befehlszeilen-Befehl in der Google Chat API konfigurieren

Wenn Sie einen Befehl mit einem Schrägstrich erstellen möchten, müssen Sie in der Konfiguration Ihrer Chat-App für die Google Chat API Informationen zum Befehl angeben.

So konfigurieren Sie einen Slash-Befehl in der Google Chat API:

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

    Zur Seite „Google Chat API“

  2. Klicken Sie auf Konfiguration.

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

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

    1. Name:Der Anzeigename für den Befehl und das, was Nutzer eingeben, um Ihre App aufzurufen. Muss mit einem Schrägstrich beginnen, nur Text enthalten und darf maximal 50 Zeichen lang sein.
    2. Beschreibung:Text, der die Verwendung und Formatierung des Befehls beschreibt. Beschreibungen dürfen maximal 50 Zeichen lang sein.
    3. Befehls-ID:Eine Zahl zwischen 1 und 1.000, die von Ihrer Chat-App verwendet wird, um den Befehl zu erkennen und eine Antwort zurückzugeben.

  5. Optional: Wenn Ihre Chat-App auf den Befehl mit einem Dialogfeld reagieren soll, setzen Sie ein Häkchen in das Kästchen Dialogfeld öffnen.

  6. Klicken Sie auf Speichern.

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

Auf einen Slash-Befehl reagieren

Wenn Nutzer eine Chatnachricht mit einem Slash-Befehl erstellen, empfängt Ihre Chat-App ein MESSAGE-Interaktionsereignis. Die Ereignisnutzlast enthält die Objekte slashCommand und slashCommandMetadata. Diese Objekte enthalten Details zum in der Nachricht verwendeten Befehl (einschließlich der Befehls-ID), damit du eine entsprechende Antwort zurückgeben kannst.

Private Nachricht für die Chat-App von Cymbal Labs. In der Nachricht wird angegeben, dass die Chat-App von Cymbal Labs erstellt wurde. Außerdem enthält sie einen Link zur Dokumentation und einen Link zum Supportteam.
Eine Chat-App antwortet privat auf den Befehl /help, um zu erklären, wie Sie Support erhalten.

Der folgende Code zeigt ein Beispiel für eine Chat-App, die auf den /about-Schrägstrichenbefehl antwortet, indem sie MESSAGE-Interaktionsereignisse verarbeitet und erkennt, ob die Nachricht die übereinstimmende Befehls-ID enthält. Wenn die Nachricht die Befehls-ID enthält, gibt die Chat-App eine private Nachricht zurück:

Node.js

node/avatar-app/index.js
// 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 res.send({
        privateMessageViewer: event.user,
        text: 'The Avatar app replies to Google Chat messages.'
      });
  }
}

Apps Script

apps-script/avatar-app/avatar-app.gs
// 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
# Checks for the presence of a slash command in the message.
if "slashCommand" in request_json["message"]:
  # Executes the slash command logic based on its ID.
  # Slash command IDs are set in the Google Chat API configuration.
  if request_json["message"]["slashCommand"]["commandId"] == ABOUT_COMMAND_ID:
    return {
      "privateMessageViewer": request_json["user"],
      "text": 'The Avatar app replies to Google Chat messages.'
    }

Java

java/avatar-app/src/main/java/App.java
// Checks for the presence of a slash command in the message.
if (body.getAsJsonObject("message").has("slashCommand")) {
  // Executes the slash command logic based on its ID.
  // Slash command IDs are set in the Google Chat API configuration.
  JsonObject slashCommand = body.getAsJsonObject("message").getAsJsonObject("slashCommand");
  switch (slashCommand.get("commandId").getAsString()) {
    case ABOUT_COMMAND_ID:
      Message aboutMessage = new Message();
      aboutMessage.setText("The Avatar app replies to Google Chat messages.");
      aboutMessage.setPrivateMessageViewer(new User()
        .setName(body.getAsJsonObject("user").get("name").getAsString()));
      response.getWriter().write(gson.toJson(aboutMessage));
      return;
  }
}

Legen Sie ABOUT_COMMAND_ID auf die Befehls-ID fest, die Sie beim Konfigurieren des Slash-Befehls in der Chat API angegeben haben. Wie Sie diesen Code testen, erfahren Sie unter Interaktive Funktionen für Google Chat-Apps testen.