Andare in vacanza con un'app Google Chat

1. Introduzione

Le app di Google Chat portano servizi e risorse direttamente in Chat, dove gli utenti possono ottenere informazioni e intraprendere azioni senza uscire dalla conversazione.

In questo codelab imparerai a creare un'app di Chat, "Attendance Chat app", che imposta le risposte automatiche in Gmail e pianifica le riunioni in Google Calendar. Creando Attendance Chat app in Google Apps Script, puoi accedere facilmente ad altri servizi Google come Drive, Gmail, Calendar, Documenti, Fogli e molti altri.

Obiettivi didattici

Come aggiungere gestori agli eventi generati in Chat
Come analizzare gli oggetti evento inviati da Chat
Come rispondere a Chat con risposte in formato scheda
Come definire e reagire alle azioni personalizzate per i clic sui pulsanti nelle schede

Che cosa ti serve

Accesso a internet e a un browser web.
Un account Google Workspace con accesso a Google Chat.
Competenze di base in JavaScript: Google Apps Script supporta solo JavaScript.

2. Recupera il codice campione

Puoi scaricare un file ZIP o clonare il repository GitHub per visualizzare il codice di ogni passaggio di questo esempio.

Le cartelle step-NN in apps-script/attendance-chat-app contengono lo stato finale di ogni passaggio di questo codelab. Sono presenti a scopo di riferimento.

Scarica il codice

Per scaricare il codice di questo codelab, fai clic sul pulsante seguente:

Decomprimi il file ZIP scaricato. Viene decompressa una cartella principale (google-chat-samples), che contiene una cartella per ogni passaggio di questo codelab in apps-script/attendance-chat-app.

Clona il repository GitHub

Per clonare il repository GitHub per questo codelab, esegui il comando seguente:

git clone https://github.com/googleworkspace/google-chat-samples

3. Crea i gestori per gli eventi di Google Chat

Crea un progetto Apps Script

Per creare un progetto Apps Script:

Vai a script.new.
Fai clic su Progetto senza titolo.
Rinomina lo script Attendance Chat app e fai clic su Rinomina.

Eventi in Google Chat

La maggior parte delle interazioni di Apps Script con Chat sono basate sugli eventi. L'interazione tra l'utente, l'app di Chat e Chat in genere segue questa sequenza:

Un utente avvia un'azione, ad esempio aggiungendo un'app di Chat a uno spazio, avviando un messaggio diretto (DM) con un'app di Chat o rimuovendo un'app di Chat da uno spazio.
L'azione genera un evento destinato all'app di Chat in Chat.
Chat chiama il gestore di eventi corrispondente definito nello script dell'app di Chat.

Chat genera 4 eventi che la tua app può ascoltare:

ADDED_TO_SPACE: questo evento si verifica quando un utente aggiunge un'app di Chat a uno spazio o a un messaggio diretto (DM). In Apps Script, definisci una funzione onAddToSpace() per gestire questo evento.
REMOVED_FROM_SPACE: questo evento si verifica quando un utente rimuove l'app di Chat da uno spazio o da un messaggio diretto. Questo evento non pubblica una risposta in Chat. In Apps Script, definisci una funzione onRemoveFromSpace() per gestire questo evento.
MESSAGE: questo evento si verifica quando un utente invia un messaggio all'app di Chat, direttamente in un messaggio diretto o come @menzione in uno spazio. In Apps Script, definisci una funzione onMessage() per rispondere a questo evento.
CARD_CLICKED: questo evento si verifica quando l'utente fa clic su un pulsante a cui è assegnata un'azione personalizzata. In Apps Script, definisci una funzione onCardClick() per rispondere a questo evento.

Sostituisci i contenuti del file Code.gs con il seguente codice che definisce i gestori per gli eventi ADDED_TO_SPACE e REMOVE_FROM_SPACE. Aggiungerai i gestori per gli eventi MESSAGE e CARD_CLICKED più avanti in questo codelab.

Code.gs

/**
 * Responds to an ADDED_TO_SPACE event in Google Chat.
 * @param {object} event the event object from Google Chat
 * @return {object} JSON-formatted response
 * @see https://developers.google.com/workspace/chat/receive-respond-interactions
 */
function onAddToSpace(event) {
  console.info(event);
  var message = 'Thank you for adding me to ';
  if (event.space.type === 'DM') {
    message += 'a DM, ' + event.user.displayName + '!';
  } else {
    message += event.space.displayName;
  }
  return { text: message };
}

/**
 * Responds to a REMOVED_FROM_SPACE event in Google Chat.
 * @param {object} event the event object from Google Chat
 * @see https://developers.google.com/workspace/chat/receive-respond-interactions
 */
function onRemoveFromSpace(event) {
  console.info(event);
  console.log('Chat app removed from ', event.space.name);
}

4. Pubblica e testa l'app di Chat

Aggiorna il file manifest dello script

Prima di poter pubblicare l'app su Chat, devi aggiornare il manifest dello script.

Fai clic su Impostazioni progetto .
Seleziona la casella di controllo Mostra il file manifest "appsscript.json" nell'editor.
Fai clic su Editor .
Fai clic sul file appsscript.json.
Aggiungi la riga "chat": {} al file manifest.

Il file manifest dovrebbe essere simile al seguente esempio.

appsscript.json

{
  "timeZone": "America/Los_Angeles",
  "dependencies": {
  },
  "chat": {}
}

Crea un progetto Google Cloud

Prima di poter eseguire e testare l'app di Chat, devi creare un progetto Google Cloud, abilitare e configurare l'API Chat e pubblicare l'app di Chat nella tua organizzazione Google Workspace.

Nella console Google Cloud, vai a Menu > IAM e amministrazione > Crea un progetto.
In Nome progetto , inserisci un nome descrittivo.
Se ti viene richiesto, seleziona l'organizzazione e l'account di fatturazione.
Fai clic su Crea.
Al termine della creazione del progetto, viene visualizzata una notifica in alto a destra nella pagina. Fai clic sulla voce Crea progetto: <nome progetto> per aprire il progetto.
Fai clic su Menu > API e servizi > Credenziali.
Fai clic su Schermata consenso OAuth.
In Nome app, inserisci Attendance Chat app.
Se ti viene richiesto, inserisci l'indirizzo email per l'assistenza utente e i dati di contatto dello sviluppatore.
Fai clic su Salva e continua.
Fai clic su Impostazioni e utilità > Impostazioni progetto.
Copia il numero del progetto.
Torna all'editor di App Script e fai clic su Impostazioni progetto .
In Progetto Google Cloud Platform (Google Cloud), fai clic su Cambia progetto.
Fai clic su Numero progetto Google Cloud e inserisci il numero del progetto.
Fai clic su Imposta progetto.

Pubblica l'app su Chat

Per pubblicare l'app di Chat su Google Chat:

Nell'editor di Apps Script, fai clic su Esegui il deployment > Nuovo deployment.
Accanto a Seleziona tipo , fai clic su Abilita tipi di deployment .
Seleziona Componente aggiuntivo e fai clic su Esegui il deployment.
Copia l'ID deployment e fai clic su Fine.
Nella console Google Cloud, vai a Menu > API e servizi > Libreria.
Cerca API Google Chat. Seleziona l'API dall'elenco dei risultati.
Nella pagina dell'API Google Chat, fai clic su Abilita.
Dopo aver abilitato l'API, fai clic su Configurazione. Ignora tutti i messaggi che ti chiedono di creare le credenziali.
Nella pagina Configurazione:

Deseleziona Crea questa app di Chat come componente aggiuntivo di Workspace e fai clic su DISATTIVA per confermare.
In Nome app, inserisci Attendance Chat app.
In URL avatar, inserisci https://goo.gl/kv2ENA.
In Descrizione, inserisci App di Chat del codelab di Apps Script.
In Funzionalità, seleziona Ricevi messaggi individuali.
In Impostazioni di connessione, seleziona Progetto Apps Script e incolla l'ID deployment dello script nella casella di testo.
In Autorizzazioni, seleziona Persone e gruppi specifici nel tuo dominio. Nella casella di testo sotto il menu a discesa, inserisci l'indirizzo email associato alla tua organizzazione Google Workspace.
Fai clic su Salva.

Dopo aver salvato le modifiche, verifica che lo stato nella pagina dell'API Google Chat mostri Stato app come LIVE - disponibile per gli utenti.

Testa l'app di Chat

Per testare l'app in Google Chat:

Apri Google Chat.
Invia un nuovo messaggio diretto all'app di Chat facendo clic su Avvia una chat > Trova app.
Nella pagina Trova app, cerca Attendance Chat app.
Accanto a Attendance Chat app, fai clic su Aggiungi > Chat.

Quando si apre la sequenza di messaggi diretti, dovresti visualizzare un messaggio dell'app di Chat che ti ringrazia per averla aggiunta a un messaggio diretto, come mostrato nell'immagine seguente.

5. Definisci una risposta in formato scheda

Nel passaggio precedente, l'app ha risposto agli eventi di Google Chat con una semplice risposta di testo. In questo passaggio, aggiornerai l'app in modo che risponda con le schede.

Risposte con schede

Google Chat supporta l'utilizzo di schede per le risposte. Le schede sono contenitori visivi che consentono di raggruppare insieme set di widget dell'interfaccia utente. Le schede possono visualizzare intestazioni, paragrafi di testo, set di pulsanti, immagini e testo chiave/valore. L'app può definire una o più schede nella risposta JSON a Google Chat, che poi traduce la risposta negli elementi dell'interfaccia utente corrispondenti.

L'immagine seguente mostra una risposta con scheda con tre sezioni, che include un'intestazione, un widget chiave/valore, un widget immagine e un pulsante di testo.

Per rispondere ai messaggi degli utenti con una risposta con scheda, aggiungi il seguente codice al file Code.gs dell'app di Chat.

Code.gs

const DEFAULT_IMAGE_URL = 'https://goo.gl/bMqzYS';
const HEADER = {
  header: {
    title : 'Attendance Chat app',
    subtitle : 'Log your vacation time',
    imageUrl : DEFAULT_IMAGE_URL
  }
};

/**
 * Creates a card-formatted response.
 * @param {object} widgets the UI components to send
 * @return {object} JSON-formatted response
 */
function createCardResponse(widgets) {
  return {
    cards: [HEADER, {
      sections: [{
        widgets: widgets
      }]
    }]
  };
}

/**
 * Responds to a MESSAGE event triggered
 * in Google Chat.
 *
 * @param event the event object from Google Chat
 * @return JSON-formatted response
 */
function onMessage(event) {
  const userMessage = event.message.text;

  const widgets = [{
    "textParagraph": {
      "text": "You said: " + userMessage
    }
  }];

  return createCardResponse(widgets);
}

La funzione onMessage(), aggiunta in questo passaggio, legge il messaggio originale dell'utente e crea una risposta come un semplice widget TextParagragh. La funzione onMessage() chiama quindi createCardResponse(), che inserisce il widget TextParagraph in una sezione di una singola scheda. L'app di Chat restituisce l'oggetto JavaScript creato con la risposta con scheda a Google Chat.

Testa l'app di Chat

Per testare questa app, torna al messaggio diretto con l'app in Google Chat e digita un messaggio (qualsiasi messaggio andrà bene).

Tieni presente che il gestore di eventi onMessage() analizza l'oggetto evento passato da Google Chat per estrarre il messaggio originale dell'utente. Puoi anche ottenere altri tipi di informazioni sull'evento, tra cui il nome dell'utente che ha avviato l'evento, il suo indirizzo email, il nome dello spazio in cui si è verificato l'evento e molto altro.

Per saperne di più sulla struttura degli oggetti evento inviati da Google Chat, consulta la documentazione di riferimento sui formati degli eventi.

6. Reagisci ai clic sui pulsanti nelle schede

Nel passaggio precedente, l'app di Chat ha risposto a un messaggio di un utente, un evento MESSAGE, con una semplice scheda contenente un widget TextParagragh. In questo passaggio, creerai una risposta che include pulsanti, ognuno con un'azione personalizzata definita.

Schede interattive

Le risposte con schede possono contenere uno dei due tipi di pulsanti: widget pulsanti di testo, che visualizzano pulsanti solo di testo; e widget ImageButton, che visualizzano un pulsante con una semplice icona o immagine senza testo. I widget TextButton e ImageButton supportano uno dei due comportamenti onClick (come definito nella risposta JSON inviata a Google Chat): openLink o action. Come suggerisce il nome, openLink apre un link specificato in una nuova scheda del browser.

L'oggetto action specifica un'azione personalizzata da eseguire per il pulsante. Puoi specificare diversi valori arbitrari nell'oggetto azione, tra cui un actionMethodName univoco e un insieme di coppie di parametri chiave / valore.

Se specifichi un oggetto action per il pulsante, crei una scheda interattiva. Quando l'utente fa clic sul pulsante nel messaggio, Google Chat genera un evento CARD_CLICKED e invia una richiesta all'app che ha inviato il messaggio originale. L'app deve quindi gestire l'evento generato da Google Chat e restituire una risposta allo spazio.

Sostituisci la onMessage() funzione in Code.gs con il seguente codice. Questo codice crea due pulsanti, Imposta risposta automatica in Gmail e Blocca giorno in Calendar , nella scheda inviata a Google Chat.

Code.gs

const REASON = {
  SICK: 'Out sick',
  OTHER: 'Out of office'
};
/**
 * Responds to a MESSAGE event triggered in Google Chat.
 * @param {object} event the event object from Google Chat
 * @return {object} JSON-formatted response
 */
function onMessage(event) {
  console.info(event);
  const reason = REASON.OTHER;
  const name = event.user.displayName;
  const userMessage = event.message.text;

  // If the user said that they were 'sick', adjust the image in the
  // header sent in response.
  if (userMessage.indexOf('sick') > -1) {
    // Hospital material icon
    HEADER.header.imageUrl = 'https://goo.gl/mnZ37b';
    reason = REASON.SICK;
  } else if (userMessage.indexOf('vacation') > -1) {
    // Spa material icon
    HEADER.header.imageUrl = 'https://goo.gl/EbgHuc';
  }

  const widgets = [{
    textParagraph: {
      text: 'Hello, ' + name + '.<br/>Are you taking time off today?'
    }
  }, {
    buttons: [{
      textButton: {
        text: 'Set vacation in Gmail',
        onClick: {
          action: {
            actionMethodName: 'turnOnAutoResponder',
            parameters: [{
              key: 'reason',
              value: reason
            }]
          }
        }
      }
    }, {
      textButton: {
        text: 'Block out day in Calendar',
        onClick: {
          action: {
            actionMethodName: 'blockOutCalendar',
            parameters: [{
              key: 'reason',
              value: reason
            }]
          }
        }
      }
    }]
  }];
  return createCardResponse(widgets);
}

Per gestire l'evento CARD_CLICKED, devi aggiungere la funzione onCardClick() allo script dell'app di Chat. Aggiungi il seguente codice che definisce la onCardClick() funzione Code.gs.

Code.gs

/**
 * Responds to a CARD_CLICKED event triggered in Google Chat.
 * @param {object} event the event object from Google Chat
 * @return {object} JSON-formatted response
 * @see https://developers.google.com/workspace/chat/receive-respond-interactions
 */
function onCardClick(event) {
  console.info(event);
  let message = '';
  const reason = event.action.parameters[0].value;
  if (event.action.actionMethodName == 'turnOnAutoResponder') {
    turnOnAutoResponder(reason);
    message = 'Turned on vacation settings.';
  } else if (event.action.actionMethodName == 'blockOutCalendar') {
    blockOutCalendar(reason);
    message = 'Blocked out your calendar for the day.';
  } else {
    message = "I'm sorry; I'm not sure which button you clicked.";
  }
  return { text: message };
}

Quando risponde ai clic degli utenti, l'app di Chat esegue una delle due operazioni seguenti: imposta la risposta automatica dell'utente in Gmail su un messaggio "Fuori ufficio" oppure pianifica una riunione di un giorno intero nel calendario dell'utente. Per eseguire queste attività, l'app chiama il servizio avanzato Gmail e il servizio Calendar.

Aggiungi il seguente codice allo script per integrare l'app di Chat con Gmail e Calendar.

Code.gs

const ONE_DAY_MILLIS = 24 * 60 * 60 * 1000;
/**
 * Turns on the user's vacation response for today in Gmail.
 * @param {string} reason the reason for vacation, either REASON.SICK or REASON.OTHER
 */
function turnOnAutoResponder(reason) {
  let currentTime = (new Date()).getTime();
  Gmail.Users.Settings.updateVacation({
    enableAutoReply: true,
    responseSubject: reason,
    responseBodyHtml: "I'm out of the office today; will be back on the next business day.<br><br><i>Created by Attendance Chat app!</i>",
    restrictToContacts: true,
    restrictToDomain: true,
    startTime: currentTime,
    endTime: currentTime + ONE_DAY_MILLIS
  }, 'me');
}

/**
 * Places an all-day meeting on the user's Calendar.
 * @param {string} reason the reason for vacation, either REASON.SICK or REASON.OTHER
 */
function blockOutCalendar(reason) {
  CalendarApp.createAllDayEvent(reason, new Date(), new Date(Date.now() + ONE_DAY_MILLIS));
}

Infine, devi abilitare il servizio avanzato Gmail nel progetto. Per abilitare l'API Gmail:

Nell'editor di Apps Script, accanto a Servizi, fai clic su Aggiungi un servizio .
Seleziona API Gmail.
Fai clic su Dashboard API Google Cloud Platform di seguito per aprire la console Google Cloud.
Fai clic su Abilita API e servizi.
Cerca API Gmail e fai clic sull'API Gmail.
Nella pagina dell'API Gmail, fai clic su Abilita.

Testa l'app di Chat

Per testare questa versione dell'app di Chat, apri il messaggio diretto che hai avviato nei passaggi precedenti in Google Chat e digita I'm going on vacation. L'app dovrebbe rispondere con una scheda simile all'immagine riportata di seguito.

Nota: se ti viene chiesto di fornire l'accesso all'app, potresti dover digitare il messaggio una seconda volta.

7. Complimenti!

L'app di Chat ora può rispondere ai messaggi degli utenti, impostare la risposta automatica in Gmail e inserire un evento di un giorno intero nel calendario.

Argomenti trattati

Creazione e pubblicazione di un'app di Google Chat con Apps Script
Risposta ai messaggi degli utenti con una semplice risposta
Interazione con altri servizi Google Workspace per conto dell'utente tramite l'app di Chat

Andare in vacanza con un'app Google Chat Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

1. Introduzione

Obiettivi didattici

Che cosa ti serve

2. Recupera il codice campione

Scarica il codice

Clona il repository GitHub

3. Crea i gestori per gli eventi di Google Chat

Crea un progetto Apps Script

Eventi in Google Chat

Code.gs

4. Pubblica e testa l'app di Chat

Aggiorna il file manifest dello script

appsscript.json

Crea un progetto Google Cloud

Pubblica l'app su Chat

Testa l'app di Chat

5. Definisci una risposta in formato scheda

Risposte con schede

Code.gs

Testa l'app di Chat

6. Reagisci ai clic sui pulsanti nelle schede

Schede interattive

Code.gs

Code.gs

Code.gs

Testa l'app di Chat

7. Complimenti!

Argomenti trattati

Scopri di più

Andare in vacanza con un'app Google Chat