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

Sie können Chat-App-Befehle als Slash-Befehle oder Kurzbefehle erstellen. So können Nutzer die verschiedenen 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. 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.
Auf den folgenden Bildern ist zu sehen, wie Nutzer ein Menü mit Slash- und Schnellbefehlen finden:
  • Ein Nutzer entdeckt Slash-Befehle.
    Abbildung 1 Nutzer können Slash-Befehle finden und verwenden, indem sie im Antwortbereich einen Schrägstrich / gefolgt vom Namen des Befehls eingeben.
  • Ein Nutzer ruft Schnellbefehle über das Menü auf.
    Abbildung 2: Nutzer können Schnellbefehle über das Menü im Antwortbereich einer Chatnachricht finden und verwenden.

Vorbereitung

HTTP Apps Script

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. 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:

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

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: So konfigurieren Sie einen 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. Gehen Sie unter Erweiterte Einstellungen zu Trigger und prüfen Sie, ob das Feld App-Befehl einen Trigger enthält, z. B. einen HTTP-Endpunkt oder eine Apps Script-Funktion. Sie müssen diesen Trigger im folgenden Abschnitt verwenden, um auf den Befehl zu reagieren.

  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, mit der Ihre Chat-App den Befehl erkennt und eine Antwort zurückgibt.
    2. Befehlstyp:Wählen Sie entweder Schnellbefehl oder Schrägstrichenbefehl aus.
    3. 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.
    4. Name:Der nutzerfreundliche Name für den Befehl. Namen können bis zu 50 Zeichen lang sein und Sonderzeichen enthalten.
    5. Beschreibung:Text, der die Verwendung und Formatierung des Befehls beschreibt. Beschreibungen dürfen maximal 50 Zeichen lang sein.

  6. Optional: Wenn Ihre Chat-App auf den Befehl mit einem Dialogfeld reagieren soll, setzen Sie ein Häkchen in das Kästchen 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, erhält Ihre Chat-App ein Ereignisobjekt. Die Ereignisnutzlast enthält ein appCommandPayload-Objekt mit Details zum aufgerufenen Befehl (einschließlich Befehls-ID und Befehlstyp), damit du eine entsprechende Antwort zurückgeben kannst. Das Ereignisobjekt wird an den HTTP-Endpunkt oder die Apps Script-Funktion gesendet, die Sie beim Konfigurieren des App-Befehls-Triggers angegeben haben.

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 Befehl „//about“ mit einer Textnachricht antwortet. Um auf Slash-Befehle zu reagieren, verarbeitet die Chat-App Ereignisobjekte von einem App-Befehls-Trigger. Wenn die Nutzlast eines Ereignisobjekts eine Slash-Befehls-ID enthält, gibt die Chat-App die Aktion DataActions mit einem createMessageAction-Objekt zurück:

Node.js Apps Script 
// 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.'
          }}}}};
  }
}

Wenn Sie dieses Codebeispiel verwenden möchten, ersetzen Sie ABOUT_COMMAND_ID 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.

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.