Rispondere ai comandi dell'app Google Chat

In questa pagina viene spiegato come configurare e rispondere ai comandi come app Google Chat.

I comandi aiutano gli utenti a scoprire e utilizzare le funzionalità chiave di un'app di Chat. Solo le app di Chat possono vedere il contenuto di un comando. Ad esempio, se un utente invia un messaggio con un comando slash, il messaggio è visibile solo all'utente e all'app Chat.

Per decidere se creare comandi e capire come progettare le interazioni degli utenti, vedi Definire tutti i percorsi dell'utente.

Tipi di comandi dell'app di Chat

I comandi dell'app Chat possono essere creati come comandi slash o rapidi. Per scoprire e utilizzare ciascun tipo di comando, gli utenti devono:
  1. Comandi Slash: gli utenti inviano i comandi come messaggi digitando una barra (/) e poi un testo predefinito, ad esempio /about. Le app di chat possono anche richiedere un testo di argomento per il comando slash. Ad esempio, il comando con barra /search può richiedere un testo di argomento utilizzato per una query di ricerca.
  2. Comandi rapidi:per utilizzare i comandi, gli utenti aprono il menu dall'area di risposta di un messaggio di Chat. Per utilizzare un comando, fanno clic su Aggiungi e selezionano un comando dal menu.
Le seguenti immagini mostrano come gli utenti scoprono un menu di comandi slash e comandi rapidi:
  • Un utente scopre i comandi slash.
    Figura 1. Gli utenti scoprono e utilizzano i comandi con barra digitando una barra / nell'area di risposta seguita dal nome del comando.
  • Un utente visualizza i comandi rapidi dal menu.
    Figura 2. Gli utenti scoprono e utilizzano i comandi rapidi dal menu nell'area di risposta di un messaggio di Chat.

Prerequisiti

HTTP

Apps Script

Configura il comando

Questa sezione spiega come completare i seguenti passaggi per configurare un comando:

  1. Crea un nome e una descrizione per il comando.
  2. Configura il comando nella console Google Cloud.

Assegna un nome e una descrizione al comando

Il nome di un comando è quello che gli utenti digitano o selezionano per richiamare l'app Chat. Sotto il nome viene visualizzata anche una breve descrizione per chiedere agli utenti ulteriori informazioni su come utilizzare il comando:

Nome e descrizione del comando barra
Figura 3: il nome e la descrizione di un comando slash.

Quando scegli un nome e una descrizione per il comando, considera questi consigli:

Per assegnare un nome a un comando:

  • Utilizza parole o frasi brevi, descrittive e strategiche per rendere i comandi chiari all'utente. Ad esempio, invece del nome Create a reminder, usa Remind me.
  • Potresti usare un nome univoco o comune per il comando. Se il comando descrive un'interazione o una funzionalità tipica, puoi utilizzare un nome comune che gli utenti riconoscono e si aspettano, ad esempio Settings o Feedback. In caso contrario, prova a utilizzare nomi di comandi univoci perché se il nome del tuo comando è lo stesso di altre app di chat, l'utente deve filtrare comandi simili per trovare e utilizzare i tuoi.

Per descrivere un comando:

  • La descrizione deve essere breve e chiara in modo che gli utenti sappiano cosa aspettarsi quando usano il comando.
  • Informa gli utenti se sono previsti requisiti di formattazione per il comando. Ad esempio, se crei un comando slash che richiede un testo di argomento, imposta la descrizione in modo simile a Remind me to do [something] at [time].
  • Fai sapere agli utenti se l'app Chat risponde a tutti gli utenti nello spazio o in privato all'utente che richiama il comando. Ad esempio, per il comando rapido About, potresti descriverlo come Learn about this app (Only visible to you).

Configura il comando nella console Google Cloud

Per creare una barra o un comando rapido, devi specificare le relative informazioni nella configurazione dell'app di Chat per l'API Google Chat.

Per configurare un comando nell'API Google Chat, completa questi passaggi: o configura un comando slash nell'API Google Chat, completa questi passaggi:

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

    Vai alla pagina dell'API Google Chat

  2. Fai clic su Configurazione.

  3. In Impostazioni di connessione, vai a Trigger e specifica i dettagli dell'endpoint. Devi utilizzare questo trigger nella sezione seguente per rispondere al comando.

    1. URL dell'endpoint HTTP: puoi specificare un URL dell'endpoint HTTP comune qui. In alternativa, per utilizzare endpoint HTTP diversi per trigger differenti, specifica l'endpoint direttamente nel campo Comando app.
    2. Apps Script: inserisci l'ID deployment di Apps Script. Per impostazione predefinita, verrà richiamata la funzione onAppCommand. Per utilizzare una funzione Apps Script diversa, specifica il nome della funzione personalizzata nel campo Comando app.

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

  5. Inserisci le seguenti informazioni sul comando:

    1. ID comando: un numero compreso tra 1 e 1000 utilizzato dall'app Chat per riconoscere il comando e restituire una risposta.
    2. Descrizione: il testo che descrive come utilizzare e formattare il comando. Le descrizioni possono contenere fino a 50 caratteri.
    3. Tipo di comando: seleziona Comando rapido o Comando taglia.
    4. Specifica un nome per il comando rapido o il comando slash:
      • Nome comando rapido: il nome visualizzato che gli utenti selezionano dal menu per richiamare il comando. Può contenere fino a 50 caratteri e includere caratteri speciali. Ad esempio, Remind me.
      • Nome comando di Slash: il testo che gli utenti digitano per richiamare il comando in un messaggio. Deve iniziare con una barra, contenere solo testo e può contenere fino a 50 caratteri. Ad esempio, /remindMe.

  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 è ora configurato per l'app Chat.

Rispondere a un comando

Quando gli utenti utilizzano un comando, l'app Chat riceve un oggetto evento. Il payload dell'evento contiene un oggetto appCommandPayload con i dettagli sul comando che è stato richiamato (inclusi l'ID comando e il tipo di comando), in modo che tu possa restituire una risposta appropriata. L'oggetto evento viene inviato all'endpoint HTTP o alla funzione Apps Script che hai specificato quando hai configurato il trigger di comando app.

Messaggio privato per l'app Chat di Cymbal Labs. Il messaggio dice che l'app Chat è stata creata da Cymbal Labs e condivide un link alla documentazione e un link per contattare il team di assistenza.
Un'app di chat risponde in privato al comando slash /help per spiegare come ricevere assistenza.

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

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

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;

    // 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.'
          }}}}};
  }
}

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

Testa il comando

Per testare il comando e il codice, vedi Testare le funzionalità interattive per le app Google Chat.

Per scoprire come testare e utilizzare il comando nella UI di Chat, vedi Utilizzare le app in Google Chat nella documentazione della Guida di Google Chat.