Auf Befehle der Google Chat App reagieren

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

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.

Vorbereitung

Befehl einrichten

In diesem Abschnitt wird beschrieben, wie Sie die folgenden Schritte ausführen, um einen 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:

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.

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

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

   Zur Google Chat API-Seite

2. Klicken Sie auf Konfiguration.

3. Rufen Sie unter Verbindungseinstellungen die Option Trigger auf und geben Sie die Details Ihres Endpunkts an. Sie müssen diesen Trigger im nächsten Abschnitt verwenden, um auf den Befehl zu reagieren.

   1. HTTP-Endpunkt-URL: Sie können hier eine gemeinsame HTTP-Endpunkt-URL angeben. Wenn Sie für verschiedene Trigger unterschiedliche HTTP-Endpunkte verwenden möchten, geben Sie den Endpunkt direkt im Feld App-Befehl an.
   2. Apps Script: Geben Sie die Apps Script-Deployment-ID ein. Standardmäßig wird die Funktion onAppCommand aufgerufen. Wenn Sie eine andere Apps Script-Funktion verwenden möchten, geben Sie den Namen der benutzerdefinierten Funktion im Feld App-Befehl an.

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

5. Geben Sie die folgenden Informationen zum Befehl ein:

   1. 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.
   2. Beschreibung:Der Text, in dem beschrieben wird, wie der Befehl verwendet und formatiert wird. Textzeilen dürfen maximal 50 Zeichen lang sein.
   3. Befehlstyp:Wählen Sie entweder Schnellbefehl oder Slash-Befehl aus.
   4. 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.

6. Optional: Wenn Ihre Chat-App mit einem Dialogfeld auf den Befehl reagieren soll, setzen Sie ein Häkchen bei Dialogfeld öffnen.

7. Klicken Sie auf Speichern.

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

Auf einen Befehl reagieren

Wenn Nutzer einen Befehl verwenden, empfängt Ihre Chat-App ein Ereignisobjekt. Die Ereignisnutzlast enthält ein appCommandPayload-Objekt mit Details zum aufgerufenen Befehl (einschließlich der Befehls-ID und des Befehlstyps), damit Sie eine entsprechende Antwort zurückgeben können. Das Ereignisobjekt wird an den HTTP-Endpunkt oder die Apps Script-Funktion gesendet, die Sie beim Konfigurieren des App-Befehl-Triggers angegeben haben.

Der folgende Code zeigt ein Beispiel für eine Chat-App, die auf den Slash-Befehl /about mit einer Textnachricht antwortet. Um auf Slash-Befehle zu reagieren, verarbeitet die Chat-App Ereignisobjekte aus einem App-Befehl-Trigger. Wenn die Nutzlast eines Ereignisobjekts eine Slashcommand-ID enthält, gibt die Chat-App die Aktion DataActions mit einem createMessageAction-Objekt zurück:

// The ID of the slash command "/about".
// It's not enabled by default, set to the actual ID to enable it. You must
// use the same ID as set in the Google Chat API configuration.
const ABOUT_COMMAND_ID = 0;

/**
 * Google Cloud Function that responds to events sent from a
 * Google Chat space.
 *
 * @param {Object} req Request sent from Google Chat space
 * @param {Object} res Response to send back
 */
exports.avatarApp = function avatarApp(req, res) {
    if (req.method === 'GET' || !req.body.chat) {
        return res.send('Hello! This function is meant to be used ' +
            'in a Google Chat Space.');
    }
    // Stores the Google Chat event as a variable.
    const chatEvent = req.body.chat;

    // Handles events that contain payloads about commands
    if (chatEvent.appCommandPayload) {

      // Stores the Google Chat app command metadata as a variable.
      const appCommandMetadata = chatEvent.appCommandPayload.appCommandMetadata;

      // Executes the slash command logic based on its ID.
      // Slash command IDs are set in the Google Chat API configuration.
      switch (appCommandMetadata.appCommandId) {
          case ABOUT_COMMAND_ID:
              return res.send({ hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
                  text: 'The Avatar app replies to Google Chat messages.'
              }}}}});
      }
    // Handles MESSAGE events
    } else if (chatEvent.messagePayload) {

        // Stores the Google Chat event as a variable.
        const chatMessage = chatEvent.messagePayload.message;

        // Replies with the sender's avatar in a card otherwise.
        const displayName = chatMessage.sender.displayName;
        const avatarUrl = chatMessage.sender.avatarUrl;
        res.send({ hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
            text: 'Here\'s your avatar',
            cardsV2: [{
                cardId: 'avatarCard',
                card: {
                    name: 'Avatar Card',
                    header: {
                        title: `Hello ${displayName}!`,
                    },
                    sections: [{
                        widgets: [{
                            textParagraph: { text: 'Your avatar picture: ' }
                        }, {
                            image: { imageUrl: avatarUrl }
                        }]
                    }]
                }
            }]
        }}}}});
    }
};

// The ID of the slash command "/about".
// It's not enabled by default, set to the actual ID to enable it. You must
// use the same ID as set in the Google Chat API configuration.
const ABOUT_COMMAND_ID = 0;

/**
 * Responds to a MESSAGE event in Google Chat.
 *
 * @param {Object} event the event object from Google Chat
 */
function onMessage(event) {

    // Stores the Google Chat event as a variable.
    const chatMessage = event.chat.messagePayload.message;

    // Replies with the sender's avatar in a card otherwise.
    const displayName = chatMessage.sender.displayName;
    const avatarUrl = chatMessage.sender.avatarUrl;
    return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
        text: 'Here\'s your avatar',
        cardsV2: [{
            cardId: 'avatarCard',
            card: {
                name: 'Avatar Card',
                header: {
                    title: `Hello ${displayName}!`,
                },
                sections: [{
                    widgets: [{
                        textParagraph: { text: 'Your avatar picture: ' }
                    }, {
                        image: { imageUrl: avatarUrl }
                    }]
                }]
            }
        }]
    }}}}};
}

/**
 * Responds to an APP_COMMAND event in Google Chat.
 *
 * @param {Object} event the event object from Google Chat
 */
function onAppCommand(event) {

  // Stores the Google Chat app command metadata as a variable.
  const appCommandMetadata = event.chat.appCommandPayload.appCommandMetadata;

  // Executes the slash command logic based on its ID.
  // Slash command IDs are set in the Google Chat API configuration.
  switch (appCommandMetadata.appCommandId) {
      case ABOUT_COMMAND_ID:
          return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
              text: 'The Avatar app replies to Google Chat messages.'
          }}}}};
  }
}

Ersetzen Sie ABOUT_COMMAND_ID in diesem Codebeispiel durch die Befehls-ID, die Sie beim Konfigurieren des Befehls in der Chat API 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