Auf Befehle der Google Chat App reagieren

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

Befehle helfen Nutzern, wichtige Funktionen einer Chat-App zu entdecken und zu verwenden. Nur Chat-Apps können den Inhalt eines Befehls sehen. Wenn ein Nutzer beispielsweise eine Nachricht mit einem Befehl sendet, ist sie 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 User Journeys definieren.

Arten von Chat-App-Befehlen

1. Slash-Befehle:Nutzer senden Befehle als Nachrichten, indem sie einen Schrägstrich (/) und dann einen vordefinierten Text wie /about eingeben. Chat-Apps können auch Argumenttext für den Slash-Befehl erfordern. Für den Befehl „Schrägstrich“ /search kann beispielsweise Argumenttext erforderlich sein, der für eine Suchanfrage verwendet wird.
2. Schnellbefehle:Nutzer können Befehle verwenden, indem sie im Antwortbereich einer Chatnachricht das Menü öffnen. Wenn er einen Befehl verwenden möchte, klickt er auf Hinzufügen und wählt einen Befehl aus dem Menü aus.

Vorbereitung

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. Konfigurieren Sie den Befehl in der Google Cloud Console.

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, die Nutzer über die Verwendung des Befehls informiert:

Beachten 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 Wortgruppen, damit die Befehle für den Nutzer klar sind. Verwenden Sie beispielsweise Remind me anstelle von 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 möglichst eindeutige Befehlsnamen. Wenn der Befehlsname für andere Chat-Apps identisch ist, muss der Nutzer ähnliche Befehle filtern, um Ihren zu finden und zu verwenden.

So beschreiben Sie einen Befehl:

• Die Beschreibung sollte kurz und prägnant sein, damit Nutzer wissen, was sie bei Verwendung des Befehls erwartet.
• Informieren Sie die Nutzer, ob es Formatierungsanforderungen für den Befehl gibt. Wenn Sie beispielsweise einen Slash-Befehl erstellen, für den Argumenttext erforderlich ist, können Sie als Beschreibung Remind me to do [something] at [time] festlegen.
• Informieren Sie die Nutzer darüber, ob die Chat-App an alle im Gruppenbereich oder privat an den Nutzer antwortet, der den Befehl ausführt. Beispielsweise könnten Sie den Schnellbefehl About als Learn about this app (Only visible to you) beschreiben.

Befehl in der Google Cloud Console konfigurieren

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

So konfigurieren Sie einen 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 Befehle auf Befehl hinzufügen.

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

   • Befehls-ID:Eine Zahl zwischen 1 und 1.000, mit der Ihre Chat-App den Befehl erkennt und eine Antwort zurückgibt.
   • Name:Der Anzeigename für den Befehl. Namen können bis zu 50 Zeichen lang sein und Sonderzeichen enthalten.
   • Beschreibung:Text, der die Funktionsweise des Befehls beschreibt. Beschreibungen dürfen maximal 50 Zeichen lang sein und Sonderzeichen enthalten.
   • Befehlstyp:Wählen Sie entweder Schnellbefehl oder Schrägstrichenbefehl aus.
   • Wenn Sie einen Slash-Befehl konfigurieren, geben Sie einen Wert für das Feld Name des Slash-Befehls ein, um anzugeben, was Nutzer eingeben müssen, um den Befehl 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 auf den Befehl mit einem Dialogfeld reagieren soll, klicken Sie das Kästchen Dialogfeld öffnen an.

6. Klicken Sie auf Speichern.

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

Auf einen Befehl reagieren

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

Um auf jeden Befehlstyp zu reagieren, müssen Sie verschiedene Ereignistypen und Metadatenobjekte in der Ereignisnutzlast verarbeiten:

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

Auf einen Slash-Befehl reagieren

Der folgende Code zeigt ein Beispiel für eine Chat-App, die auf den Befehl „//about“ antwortet. Die Chat-App verarbeitet MESSAGE-Interaktionsereignisse, erkennt, ob das Interaktionsereignis die übereinstimmende Befehls-ID enthält, und gibt 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;
  }
}

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 übereinstimmende Befehls-ID enthält, und gibt 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;
  }
}

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.

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

Weitere Informationen

• Beispiele für Chat-Apps ansehen, in denen Befehle verwendet werden
• Nachricht senden
• Interaktive Dialoge öffnen