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.

Slash-Befehle sind eine gängige Möglichkeit, wie 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:

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 mit einem Slash-Befehl sendet, ist sie nur für den Nutzer und die Chat-App sichtbar. Wenn Sie Ihre Chat-App so konfiguriert haben, dass sie zu Gruppenbereichen mit mehreren Personen hinzugefügt wird, können Sie auf den Slash-Befehl privat antworten, damit die Interaktion zwischen dem Nutzer und der Chat-App privat 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 im Gruppenbereich benachrichtigt werden, kann die Chat-App privat antworten und Informationen zur Verwendung der Chat-App und zur Unterstützung senden.

Vorbereitung

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:

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. Verwenden Sie ansonsten eindeutige Befehlsnamen. Wenn der Befehlsname für andere Chat-Apps identisch ist, muss der Nutzer ähnliche Befehle durchsuchen, 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 ein Argumenttext erforderlich ist, legen Sie als Beschreibung beispielsweise 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 „#“ (Strich) könnten Sie beispielsweise als „Learn about this app (Only visible to you)“ beschreiben./about

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ü menu > 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.

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:

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

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

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

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

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.

Weitere Informationen

• Beispiele für Chat-Apps mit Slash-Befehlen ansehen
• Nachricht senden
• Private Nachrichten senden
• Interaktive Dialoge öffnen