Auf Slash-Befehle in Google Chat antworten

Auf dieser Seite wird erläutert, wie Sie eine Google Chat-App so konfigurieren, dass sie auf Schrägstricheingaben reagiert.

In Google Chat werden Add-ons für Nutzer als Google Chat-Apps angezeigt. Weitere Informationen finden Sie unter Google Chat erweitern – Übersicht.

Slash-Befehle sind eine gängige Methode, mit der Nutzer eine Chat-App aufrufen und mit ihr interagieren. Außerdem helfen sie Nutzern, wichtige Funktionen einer Chat-App zu entdecken und zu verwenden. Ob Sie Slash-Befehle einrichten sollten und wie Sie Nutzerinteraktionen gestalten, erfahren Sie in der Chat API-Dokumentation unter Alle User Journeys definieren.

So verwenden Nutzer Slash-Befehle

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:

Abbildung 1: Das Fenster, das angezeigt wird, wenn Nutzer einen Schrägstrich in Google Chat eingeben.

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 Kontaktaufnahme mit dem Support senden.

Vorbereitung

Node.js

Ein Google Workspace-Add-on, das Google Chat erweitert. Führen Sie dazu die HTTP-Kurzanleitung aus.

Hinweis: Die Codebeispiele in diesem Leitfaden sind so geschrieben, dass sie als Google Cloud-Funktion für Node.js ausgeführt werden.

Apps Script

Ein Google Workspace-Add-on, das Google Chat erweitert. Wenn Sie ein solches Script erstellen möchten, folgen Sie der Apps Script-Kurzanleitung.

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:

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. 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 „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 Befehl mit einem Schrägstrich 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 MESSAGE 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 mit dem Schrägstrich zu reagieren.

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

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

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

7. Klicken Sie auf Speichern.

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

Auf einen Slash-Befehl reagieren

Wenn Nutzer eine Chatnachricht erstellen, erhält Ihre Chat-App ein Ereignisobjekt mit Informationen zur Nachricht. Das Ereignisobjekt enthält eine Nutzlast mit Details zum in der Nachricht verwendeten Befehl (einschließlich der Befehls-ID), damit du eine entsprechende Antwort zurückgeben kannst.

Warnung: In diesem Abschnitt wird ein Beispiel verwendet, in dem der Slash-Befehl über eine Nachricht ausgelöst wird und das Ereignisobjekt ein MessagePayload enthält. Dies kann sich in Zukunft ändern.

Wenn Sie auf einen Befehl reagieren möchten, müssen Sie den Message-Trigger implementieren, damit Ihre Chat-App alle Ereignisobjekte verarbeiten kann, die Metadaten für Befehle enthalten.

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

Node.js

// 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 messages 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 chatMessage = req.body.chat.messagePayload.message;

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

    // 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 }
                    }]
                }]
            }
        }]
    }}}}});
};

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;

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

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

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

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.