Rispondere ai comandi slash in Google Chat

Questa pagina spiega come configurare un'app Google Chat in modo che risponda ai comandi con barra.

In Google Chat, i componenti aggiuntivi vengono visualizzati dagli utenti come app Google Chat. Per saperne di più, consulta la panoramica di Estensione di Google Chat.

Un comando slash è un modo comune in cui gli utenti richiamano e interagiscono con un'app Chat. I comandi slash aiutano anche gli utenti a scoprire e utilizzare le funzionalità chiave di un'app Chat. Per decidere se configurare i comandi slash e capire come progettare le interazioni degli utenti, consulta Definire tutti i percorsi utente nella documentazione dell'API Chat.

Come gli utenti utilizzano i comandi slash

Per utilizzare un comando slash, gli utenti devono digitare una barra (/) e poi un breve comando di testo, come /about per ottenere informazioni sull'app Chat. Gli utenti possono scoprire i comandi slash disponibili digitando una barra in Google Chat, che mostra una finestra che elenca i comandi disponibili per l'app Chat:

Quando un utente invia un messaggio contenente un comando slash, il messaggio è visibile solo all'utente e all'app Chat. Se hai configurato l'app Chat in modo che venga aggiunta a spazi con più persone, ti consigliamo di rispondere al comando slash in privato per mantenere privata l'interazione tra l'utente e l'app Chat.

Ad esempio, per scoprire di più su un'app di Chat che hanno trovato in uno spazio, gli utenti possono utilizzare comandi come /about o /help. Per evitare di inviare una notifica a tutti gli altri utenti dello spazio, l'app Chat può rispondere in privato con informazioni su come utilizzare l'app e ricevere assistenza.

Prerequisiti

Configurare un comando slash

Questa sezione spiega come completare i seguenti passaggi per configurare un comando con barra.

1. Crea un nome per il comando slash.
2. Configura il comando barra nell'API Google Chat.

Assegna un nome al comando slash

Il nome di un comando slash è ciò che gli utenti digitano in un messaggio di Chat per richiamare l'app Chat. Sotto il nome viene visualizzata anche una breve descrizione per fornire ulteriori informazioni agli utenti su come utilizzare il comando:

Quando scegli un nome e una descrizione per il comando slash, tieni conto dei seguenti consigli:

• Per assegnare un nome al comando slash:

  • Utilizza parole o frasi brevi, descrittive e strategiche per rendere i comandi chiari e semplici per l'utente. Ad esempio, invece di dire /createAReminder, usa /remindMe.
  • Se il comando contiene più di una parola, aiuta gli utenti a leggerlo utilizzando tutte le lettere minuscole per la prima parola e poi la prima lettera maiuscola per le parole aggiuntive. Ad esempio, invece di /updatecontact, utilizza /updateContact.
  • Valuta la possibilità di utilizzare un nome univoco o comune per il comando. Se il comando descrive un'interazione o una funzionalità tipica, puoi utilizzare un nome comune riconosciuto e previsto dagli utenti, ad esempio /settingso /feedback. In caso contrario, prova a utilizzare nomi di comandi univoci, perché se il nome del tuo comando è uguale a quello di altre app di chat, l'utente deve filtrare i comandi simili per trovare e utilizzare il tuo.

• Per descrivere il comando slash:

  • Mantieni la descrizione breve e chiara in modo che gli utenti sappiano cosa aspettarsi quando richiamano il comando.
  • Comunica agli utenti se sono previsti requisiti di formattazione per il comando. Ad esempio, se crei un comando /remindMe che richiede un testo dell'argomento, imposta la descrizione su qualcosa di simile a Remind me to do [something] at [time].
  • Comunica agli utenti se l'app Chat deve rispondere a tutti gli utenti dello spazio o in privato all'utente che richiama il comando. Ad esempio, per il comando barra /about, puoi descriverlo come Learn about this app (Only visible to you).

Configurare il comando barra nell'API Google Chat

Per creare un comando con barra, devi specificare le informazioni sul comando nella configurazione dell'app Chat per l'API Google Chat.

Per configurare un comando barra nell'API Google Chat, completa i seguenti passaggi:

1. Nella console Google Cloud, fai clic su Menu menu > API e servizi > API e servizi abilitati > API Google Chat

   Vai alla pagina dell'API Google Chat

2. Fai clic su Configurazione.

3. In Impostazioni avanzate, vai a Trigger e verifica che il campo MESSAGE contenga un trigger, ad esempio un endpoint HTTP o una funzione di Apps Script. Devi utilizzare questo trigger per rispondere al comando slash nella sezione seguente.

4. In Comandi slash, fai clic su Aggiungi un comando slash.

5. Inserisci un nome, un ID comando e una descrizione per il comando:

   1. Nome: il nome visualizzato per il comando e ciò che gli utenti digitano per richiamare l'app. Deve iniziare con una barra, contenere solo testo e può avere un massimo di 50 caratteri.
   2. Descrizione:il testo che descrive come utilizzare e formattare il comando. Le descrizioni possono contenere fino a 50 caratteri.
   3. ID comando:un numero compreso tra 1 e 1000 utilizzato dalla tua app Chat per riconoscere il comando slash e restituire una risposta.

6. (Facoltativo) Se vuoi che l'app Chat risponda al comando con una finestra di dialogo, seleziona la casella di controllo Apri una finestra di dialogo.

7. Fai clic su Salva.

Il comando slash è ora configurato per l'app Chat.

Rispondere a un comando slash

Quando gli utenti creano un messaggio di Chat, la tua app Chat riceve un oggetto evento contenente informazioni sul messaggio. L'oggetto evento contiene un payload con i dettagli del comando utilizzato nel messaggio (incluso l'ID comando), in modo da poter restituire una risposta appropriata.

Per rispondere a un comando slash, devi implementare l'attivatore Messaggio in modo che la tua app Chat possa gestire eventuali oggetti evento contenenti i metadati dei comandi slash.

Il seguente codice mostra un esempio di app Chat che risponde al comando barra /about con un messaggio. Per rispondere ai comandi slash, l'app Chat gestisce gli oggetti evento da un attivatore Messaggio. Quando il payload di un oggetto evento contiene un ID comando con barra, l'app Chat restituisce l'azione DataActions con un oggetto createMessageAction:

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

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

Per utilizzare questo esempio di codice, sostituisci ABOUT_COMMAND_ID con l'ID comando specificato quando hai configurato il comando slash nell'API Chat.