Raccogliere e gestire i contatti in Google Chat

Questo tutorial mostra come creare un'app Google Chat che ti aiuti Gli utenti di Google Chat gestiscono i propri contatti personali e aziendali. Da raccogliere informazioni, l'app Chat chiede agli utenti di completare un modulo di contatto nei messaggi e nelle finestre di dialogo delle schede.

Guarda l'app Chat in azione:

• 

  Figura 1. La L'app Chat risponde comando slash /about con un messaggio di testo e un pulsante che apre un modulo di contatto.

• 
  Figura 2. La L'app Chat apre una finestra di dialogo in cui gli utenti possono inserire informazioni su un contatto.
• 
  Figura 3. L'app Chat restituisce una finestra di dialogo di conferma in modo che gli utenti possano rivedere e confermare le informazioni prima di inviarle.
• 
  Figura 4. Dopo che l'utente ha inviato il modulo, l'app Chat invia una per confermare l'invio.
• 
  Figura 5. L'app Chat chiede inoltre agli utenti di aggiungere un contatto da una scheda in un messaggio.

Prerequisiti

• Un account Google Workspace Business o Enterprise con accesso a Google Chat.

Obiettivi

• Progetta e crea interfacce utente (UI) come oggetti card e visualizza le UI in messaggi e finestre di dialogo.
• Ricevere ed elaborare le informazioni inviate dagli utenti tramite widget di input modulo.
• Rispondi ai comandi con barra inviando messaggi contenenti testo, schede e widget accessori.

Architettura

L'app Chat è integrata in Google Apps Script e utilizza eventi di interazione per elaborare e rispondere agli utenti di Chat.

Di seguito viene mostrato in che modo un utente solitamente può interagire con App Chat:

1. Un utente apre un messaggio diretto con l'app Chat o aggiunge l'app Chat a uno spazio esistente.

2. L'app Chat chiede all'utente di aggiungere un contatto creando e mostrando un modulo di contatto come card . Per presentare il modulo di contatto, l'app Chat risponde agli utenti nei seguenti modi:

   • Risponde alle @menzioni e ai messaggi diretti con un messaggio della scheda che contiene il modulo di contatto.
   • Risponde al comando barra /addContact aprendo una finestra di dialogo con il modulo di contatto.
   • Risponde al comando slash /about con un messaggio di testo contenente un pulsante Aggiungi un contatto su cui gli utenti possono fare clic per aprire una finestra di dialogo con il modulo di contatto.

3. Quando viene visualizzato il modulo di contatto, l'utente inserisce i dati di contatto nei seguenti campi e widget:

   • Nome e cognome: a textInput widget che accetta stringhe.
   • Data di nascita: a dateTimePicker widget che accetta solo date.
   • Tipo di contatto: a selectionInput widget di pulsanti di opzione che consentono agli utenti di selezionare e inviare una singola stringa (Personal o Work).
   • Pulsante Esamina e invia: un array buttonList con widget button su cui l'utente fa clic per inviare i valori inseriti.

4. L'app Google Chat gestisce un evento di interazione CARD_CLICKED per elaborare i valori inseriti dall'utente e li mostra in una scheda di conferma.

5. L'utente esamina la scheda di conferma e fa clic sul pulsante Invia per finalizzare i dati di contatto.

6. L'app Google Chat invia un SMS privato che conferma l'invio.

prepara l'ambiente

Questa sezione mostra come creare e configurare un progetto Google Cloud App Chat.

Crea un progetto Google Cloud

Console Google Cloud

1. Nella console Google Cloud, vai al Menu > IAM e Amministratore > Crea un progetto.

   Vai a Crea un progetto

2. Nel campo Nome progetto, inserisci un nome descrittivo per il progetto.

   (Facoltativo) Per modificare l'ID progetto, fai clic su Modifica. L'ID progetto non può essere modificato dopo la creazione del progetto, quindi scegli un ID che soddisfi le tue esigenze per l'intera durata del progetto.

3. Nel campo Località, fai clic su Sfoglia per visualizzare le località potenziali per il tuo progetto. Poi, fai clic su Seleziona.
   Attenzione: non riesci a trovare la tua organizzazione Google Workspace?
   Ciò significa che non hai eseguito l'accesso a un account Google Workspace. Alcune delle funzionalità descritte nella documentazione per gli sviluppatori di Google Workspace sono disponibili solo per i progetti associati a un'organizzazione.
4. Fai clic su Crea. La console Google Cloud accede alla pagina Dashboard e il progetto viene creato entro pochi minuti.

Interfaccia a riga di comando gcloud

In uno dei seguenti ambienti di sviluppo, accedi a Google Cloud Interfaccia a riga di comando (gcloud):

• Cloud Shell: per utilizzare un terminale online con gcloud CLI è già configurato, attiva Cloud Shell.
  Attiva Cloud Shell
• Shell locale: per utilizzare un ambiente di sviluppo locale, install e inizializzare con gcloud CLI.
  Per creare un progetto Cloud, utilizza il comando gcloud projects create:

  gcloud projects create PROJECT_ID

  Sostituisci PROJECT_ID impostando l'ID del progetto che vuoi creare.

Configura autenticazione e autorizzazione

Le app Google Chat richiedono la configurazione di Schermata consenso OAuth in modo che gli utenti possono autorizzare la tua app nelle applicazioni di Google Workspace, tra cui Google Chat.

In questo tutorial eseguirai il deployment di un'app di Chat riservata test e uso interno, quindi è corretto usare informazioni segnaposto per schermata per il consenso. Prima di pubblicare l'app Chat, sostituisci informazioni segnaposto con informazioni reali.

1. Nella console Google Cloud, vai a Menu > API e Servizi > Schermata consenso OAuth.

   Vai alla schermata per il consenso OAuth

2. In Tipo di utente, seleziona Interno e poi fai clic su Crea.

3. In Nome app, digita Contact Manager.

4. In Indirizzo email dell'assistenza utente, seleziona il tuo indirizzo email o un gruppo Google appropriato.

5. In Dati di contatto dello sviluppatore, inserisci il tuo indirizzo email.

6. Fai clic su Salva e continua.

7. Nella pagina Ambiti, fai clic su Salva e continua. L'app Chat non richiede ambiti OAuth.

8. Esamina il riepilogo, poi fai clic su Torna alla dashboard.

Creare e implementare l'app Chat

Nella sezione seguente, copi e aggiorni un'intera Progetto Apps Script contenente tutte le applicazioni richieste per la tua app Chat, quindi non è necessario copiare e incollare ciascun file.

Se vuoi, puoi visualizzare l'intero progetto su GitHub.

Visualizza su GitHub

Ecco una panoramica di ogni file:

main.gs

Gestisce tutta la logica dell'app, inclusi gli eventi di interazione relativi a quando gli utenti inviano di messaggi diretti all'app Chat, fai clic sui pulsanti un messaggio dell'app Chat o aprire e chiudere finestre di dialogo.

Visualizza il codice main.gs

apps-script/contact-form-app/main.gs

Visualizza su GitHub

/**
 * Copyright 2024 Google Inc.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

/**
 * Responds to a MESSAGE interaction event in Google Chat.
 *
 * @param {Object} event the MESSAGE interaction event from Chat API.
 * @return {Object} message response that opens a dialog or sends private
 *                          message with text and card.
 */
function onMessage(event) {
  if (event.message.slashCommand) {
    switch (event.message.slashCommand.commandId) {
      case 1:
        // If the slash command is "/about", responds with a text message and button
        // that opens a dialog.
        return {
          text: "Manage your personal and business contacts 📇. To add a " +
                  "contact, use the slash command `/addContact`.",
          accessoryWidgets: [{ buttonList: { buttons: [{
            text: "Add Contact",
            onClick: { action: {
              function: "openDialog",
              interaction: "OPEN_DIALOG"
            }}
          }]}}]
        }
      case 2:
        // If the slash command is "/addContact", opens a dialog.
        return openDialog(event);
    }
  }

  // If user sends the Chat app a message without a slash command, the app responds
  // privately with a text and card to add a contact.
  return {
    privateMessageViewer: event.user,
    text: "To add a contact, try `/addContact` or complete the form below:",
    cardsV2: [{
      cardId: "addContactForm",
      card: {
        header: { title: "Add a contact" },
        sections:[{ widgets: CONTACT_FORM_WIDGETS.concat([{
          buttonList: { buttons: [{
            text: "Review and submit",
            onClick: { action: { function : "openNextCard" }}
          }]}
        }])}]
      }
    }]
  };
}

/**
 * Responds to CARD_CLICKED interaction events in Google Chat.
 *
 * @param {Object} event the CARD_CLICKED interaction event from Google Chat
 * @return {Object} message responses specific to the dialog handling.
 */
function onCardClick(event) {
  // Initial dialog form page
  if (event.common.invokedFunction === "openDialog") {
    return openDialog(event);
  // Second dialog form page
  } else if (event.common.invokedFunction === "openNextCard") {
    return openNextCard(
      event.user,
      fetchFormValue(event, "contactName"),
      fetchFormValue(event, "contactBirthdate"),
      fetchFormValue(event, "contactType"),
      event.isDialogEvent
    );
  // Dialog form submission
  } else if (event.common.invokedFunction === "submitForm") {
    const userInputs = event.common.parameters;
    return submitForm(event.user, userInputs, event.dialogEventType);
  }
}

/**
 * Extracts form input value for a given widget.
 *
 * @param {Object} event the CARD_CLICKED interaction event from Google Chat.
 * @param {String} widgetName a unique ID for the widget, specified in the widget's name field.
 * @returns the value inputted by the user, null if no value can be found.
 */
function fetchFormValue(event, widgetName) {
  const formItem = event.common.formInputs[widgetName][""];
  // For widgets that receive StringInputs data, the value input by the user.
  if (formItem.hasOwnProperty("stringInputs")) {
    const stringInput = event.common.formInputs[widgetName][""].stringInputs.value[0];
    if (stringInput != null) {
      return stringInput;
    }
  // For widgets that receive dateInput data, the value input by the user.
  } else if (formItem.hasOwnProperty("dateInput")) {
    const dateInput = event.common.formInputs[widgetName][""].dateInput.msSinceEpoch;
     if (dateInput != null) {
       return dateInput;
     }
  }

  return null;
}

/**
 * Opens a dialog that prompts users to add details about a contact.
 *
 * @return {Object} a message with an action response to open a dialog.
 */
function openDialog() {
  return { actionResponse: {
    type: "DIALOG",
    dialogAction: { dialog: { body: { sections: [{
      header: "Add new contact",
      widgets: CONTACT_FORM_WIDGETS.concat([{
        buttonList: { buttons: [{
          text: "Review and submit",
          onClick: { action: { function: "openNextCard" }}
        }]}
      }])
    }]}}}
  }};
}

/**
 * Returns a dialog or card message that displays a confirmation of contact
 * details before users submit.
 *
 * @param {String} user the user who submitted the information.
 * @param {String} contactName the contact name from the previous dialog or card.
 * @param {String} contactBirthdate the birthdate from the previous dialog or card.
 * @param {String} contactType the contact type from the previous dialog or card.
 * @param {boolean} fromDialog whether the information was submitted from a dialog.
 *
 * @return {Object} returns a dialog or private card message.
 */
function openNextCard(user, contactName, contactBirthdate, contactType, fromDialog) {
  const name = contactName ?? "<i>Not provided</i>";
  const birthdate = contactBirthdate ?? "<i>Not provided</i>";
  const type = contactType ?? "<i>Not provided</i>";
  const cardConfirmation = {
    header: "Your contact",
    widgets: [{
      textParagraph: { text: "Confirm contact information and submit:" }}, {
      textParagraph: { text: "<b>Name:</b> " + name }}, {
      textParagraph: {
        text: "<b>Birthday:</b> " + convertMillisToDateString(birthdate)
      }}, {
      textParagraph: { text: "<b>Type:</b> " + type }}, {
      buttonList: { buttons: [{
        text: "Submit",
        onClick: { action: {
          function: "submitForm",
          parameters: [{
            key: "contactName", value: name }, {
            key: "contactBirthdate", value: birthdate }, {
            key: "contactType", value: type
          }]
        }}
      }]}
    }]
  };

  // Returns a dialog with contact information that the user input.
  if (fromDialog) {
    return { action_response: {
      type: "DIALOG",
      dialogAction: { dialog: { body: { sections: [ cardConfirmation ]}}}
    }};
  }

  // Updates existing card message with contact information that the user input.
  return {
    actionResponse: { type: "UPDATE_MESSAGE" },
    privateMessageViewer: user,
    cardsV2: [{
      card: { sections: [cardConfirmation]}
    }]
  }
}

/**
  * Submits information from a dialog or card message.
  *
  * @param {Object} user the person who submitted the information.
  * @param {Object} userInputs the form input values from event parameters.
  * @param {boolean} dialogEventType "SUBMIT_DIALOG" if from a dialog.
  * @return {Object} a message response that opens a dialog or posts a private
  *                  message.
  */
function submitForm(user, userInputs, dialogEventType) {
  const contactName = userInputs["contactName"];
  // Checks to make sure the user entered a contact name.
  // If no name value detected, returns an error message.
  if (!contactName) {
    const errorMessage = "Don't forget to name your new contact!";
    if (dialogEventType === "SUBMIT_DIALOG") {
      return { actionResponse: {
        type: "DIALOG",
        dialogAction: { actionStatus: {
          statusCode: "INVALID_ARGUMENT",
          userFacingMessage: errorMessage
        }}
      }};
    } else {
      return {
        privateMessageViewer: user,
        text: errorMessage
      };
    }
  }

  // The Chat app indicates that it received form data from the dialog or card.
  // Sends private text message that confirms submission.
  const confirmationMessage = "✅ " + contactName + " has been added to your contacts.";
  if (dialogEventType === "SUBMIT_DIALOG") {
    return {
      actionResponse: {
        type: "NEW_MESSAGE",
        dialogAction: { actionStatus: {
          statusCode: "OK",
          userFacingMessage: "Success " + JSON.stringify(contactName)
        }}
      },
      privateMessageViewer: user,
      text: confirmationMessage
    }
  } else {
    return {
      actionResponse: { type: "NEW_MESSAGE" },
      privateMessageViewer: user,
      text: confirmationMessage
    };
  }
}

/**
 * Converts date in milliseconds since epoch to user-friendly string.
 *
 * @param {Object} millis the milliseconds since epoch time.
 * @return {string} Display-friend date (English US).
 */
function convertMillisToDateString(millis) {
  const date = new Date(millis);
  const options = { year: 'numeric', month: 'long', day: 'numeric' };
  return date.toLocaleDateString('en-US', options);
}

contactForm.gs

Contiene i widget che ricevono dati del modulo dagli utenti. Questi widget di input del modulo vengono visualizzati nelle schede che appaiono in messaggi e finestre di dialogo.

Visualizza il codice di contactForm.gs

apps-script/contact-form-app/contactForm.gs

Visualizza su GitHub

/**
 * Copyright 2024 Google Inc.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

/**
 * The section of the contact card that contains the form input widgets. Used in a dialog and card message.
 * To add and preview widgets, use the Card Builder: https://addons.gsuite.google.com/uikit/builder
 */
const CONTACT_FORM_WIDGETS = [
  {
    "textInput": {
      "name": "contactName",
      "label": "First and last name",
      "type": "SINGLE_LINE"
    }
  },
  {
    "dateTimePicker": {
      "name": "contactBirthdate",
      "label": "Birthdate",
      "type": "DATE_ONLY"
    }
  },
  {
    "selectionInput": {
      "name": "contactType",
      "label": "Contact type",
      "type": "RADIO_BUTTON",
      "items": [
        {
          "text": "Work",
          "value": "Work",
          "selected": false
        },
        {
          "text": "Personal",
          "value": "Personal",
          "selected": false
        }
      ]
    }
  }
];

appsscript.json

La File manifest di Apps Script che definisce e configura il progetto Apps Script per App Chat.

Visualizza il codice di appsscript.json

apps-script/contact-form-app/appsscript.json

Visualizza su GitHub

{
  "timeZone": "America/Los_Angeles",
  "dependencies": {},
  "exceptionLogging": "STACKDRIVER",
  "runtimeVersion": "V8",
  "chat": {}
}

Trovare il numero e l'ID del progetto Cloud

1. Nella console Google Cloud, vai al tuo progetto Cloud.

   Vai alla console Google Cloud

2. Fai clic su Impostazioni e utilità > Impostazioni progetto.

3. Prendi nota dei valori nei campi Numero progetto e ID progetto. Puoi usarli nelle sezioni seguenti.

Crea il progetto Apps Script

Per creare un progetto Apps Script e collegarlo al tuo Progetto cloud:

1. Fai clic sul pulsante seguente per aprire il progetto Apps Script Gestisci contatti in Google Chat.
   Apri il progetto
2. Fai clic su Panoramica.
3. Nella pagina Panoramica, fai clic su Crea una copia.

4. Assegna un nome alla copia del progetto Apps Script:

   1. Fai clic su Copia di Gestisci contatti in Google Chat.

   2. In Titolo progetto, digita Contact Manager - Google Chat app

   3. Fai clic su Rinomina.

Imposta il progetto cloud del progetto Apps Script

1. Nel tuo progetto Apps Script, fai clic su Impostazioni progetto.
2. In Progetto Google Cloud (Google Cloud), fai clic su Cambia progetto.
3. In Numero di progetto Google Cloud, incolla il numero del tuo progetto Cloud.
4. Fai clic su Imposta progetto. Il progetto Cloud e il progetto Apps Script sono ora collegati.

Creare un deployment Apps Script

Ora che il codice è al suo posto, esegui il deployment di Apps Script progetto. Devi usare l'ID deployment quando configuri Chat in Google Cloud.

1. In Apps Script, apri la sezione progetto.

   Vai ad Apps Script

2. Fai clic su Esegui il deployment > Nuovo deployment.

3. Se Componente aggiuntivo non è già selezionato, accanto a Seleziona tipo, fai clic sui tipi di implementazione e seleziona Componente aggiuntivo.

4. In Descrizione, inserisci una descrizione per questa versione, ad esempio Test of Contact Manager.

5. Fai clic su Esegui il deployment. Apps Script segnala il deployment riuscito e fornisce un ID deployment.

6. Fai clic su Copia per copiare l'ID deployment e fai clic su Fine.

Configurare l'app Chat nella console Google Cloud

Questa sezione mostra come configurare l'API Google Chat nella console Google Cloud con informazioni sulla tua app Chat, tra cui ID del deployment che hai appena creato da Apps Script progetto.

1. Nella console Google Cloud, fai clic su Menu > Altri prodotti > Google Workspace > Libreria di prodotti > API Google Chat > Gestisci > Configurazione.

   Vai alla configurazione dell'API Chat

2. In Nome app, digita Contact Manager.

3. In URL avatar, digita https://developers.google.com/chat/images/contact-icon.png.

4. In Descrizione, digita Manage your personal and business contacts.

5. Fai clic sul pulsante di attivazione/disattivazione Abilita le funzionalità interattive per attivare le funzionalità.

6. In Funzionalità, seleziona le caselle di controllo Ricevi messaggi 1:1 e Partecipa a spazi e conversazioni di gruppo.

7. Nella sezione Impostazioni di connessione, seleziona Apps Script.

8. In Deployment ID (ID deployment), incolla l'ID deployment di Apps Script che hai copiato nella sezione precedente quando hai creato il deployment di Apps Script.

9. In Comandi slash, configura i comandi slash /about e /addContact:

   1. Fai clic su Aggiungi un comando slash per configurare il primo comando slash.
   2. In Nome, digita /about.
   3. In ID comando, digita 1.
   4. In Descrizione, digita Learn how to use this Chat app to manage your contacts.
   5. Seleziona Apre una finestra di dialogo.
   6. Fai clic su Fine.
   7. Fai clic su Aggiungi un comando slash per configurare un altro comando slash.
   8. In Nome, digita /addContact.
   9. In ID comando, digita 2.
   10. In Descrizione, digita Submit information about a contact.
   11. Seleziona Apre una finestra di dialogo.
   12. Fai clic su Fine.

10. In Visibilità, seleziona la cassella di controllo Rendi disponibile l'app di chat a utenti e gruppi specifici in YOUR DOMAIN e inserisci il tuo indirizzo email.

11. In Log, seleziona Errori di log in Logging.

12. Fai clic su Salva. Viene visualizzato un messaggio relativo alla configurazione salvata.

L'app Chat è pronta per essere installata e testata Chatta.

Testare l'app Chat

Per testare l'app Chat, apri uno spazio di messaggi diretti con l'app Chat e invia un messaggio:

1. Apri Google Chat utilizzando l'account Google Workspace fornito quando hai aggiunto te stesso come tester attendibile.

   Vai a Google Chat

2. Fai clic su Nuova chat.
3. Nel campo Aggiungi 1 o più persone, digita il nome della tua app Chat.

4. Seleziona la tua app Chat dai risultati. Un annuncio diretto si apre il messaggio.

   Nota:se non vedi l'app Chat nell'elenco di risultati, assicurati di aver incluso il tuo account Google Workspace nell' Impostazioni di visibilità della configurazione dell'API Chat nella console Google Cloud.

1. Nel nuovo messaggio diretto con l'app Chat, digita /addContacte premi Invio.

2. Nella finestra di dialogo che si apre, inserisci i dati di contatto:

   1. Nel campo di testo Nome e cognome, inserisci un nome.
   2. Nel selettore della data di Data di nascita, seleziona una data.
   3. In Tipo di contatto, seleziona il pulsante di opzione Lavoro o Personale.

3. Fai clic su Rivedi e invia.

4. Nella finestra di dialogo di conferma, rivedi le informazioni che hai inviato e fai clic su Invia. L'app Chat risponde con un messaggio che dice ✅ CONTACT NAME has been added to your contacts..

5. Se vuoi, puoi anche testare e inviare il modulo di contatto nei seguenti modi:

   • Utilizza il comando slash /about. L'app Chat risponde con un messaggio e un pulsante del widget dell'accessorio con il testo Add a contact. Puoi fare clic sul pulsante per aprire una finestra di dialogo con il modulo di contatto.
   • Invia un messaggio diretto all'app Chat senza un comando barra, ad esempio Hello. L'app Chat risponde con un messaggio e una scheda contenente il modulo di contatto.

Esegui la pulizia

Per evitare che al tuo account Google Cloud vengano addebitati costi relativi alla utilizzate in questo tutorial, ti consigliamo di eliminare progetto cloud.

Attenzione:l'eliminazione di un progetto ha i seguenti effetti:

• L'intero contenuto del progetto viene eliminato. Se hai utilizzato un progetto esistente per questo tutorial, quando lo elimini elimini anche tutto il lavoro effettuato nel progetto.
• Gli ID progetto personalizzati non sono più disponibili. Quando hai creato il progetto, potresti aver creato un ID progetto personalizzato che vuoi utilizzare in futuro. Per conservare gli URL che utilizzano l'ID progetto, ad esempio un URL su appspot.com, elimina le risorse selezionate all'interno del progetto anziché eliminare l'intero progetto.

Se prevedi di esplorare più tutorial e guide rapide, il riutilizzo dei progetti può aiutarti a evitare di superare i limiti di quota.

1. Nella console Google Cloud, vai alla pagina Gestisci risorse. Fai clic su Menu > IAM e amministrazione > Gestisci risorse.

   Vai a Resource Manager

2. Nell'elenco dei progetti, seleziona il progetto che vuoi eliminare e fai clic su Elimina .
3. Nella finestra di dialogo, digita l'ID progetto e fai clic su Chiudi per eliminare il progetto.

Argomenti correlati

• Rispondere ai comandi slash
• Raccogliere ed elaborare informazioni dagli utenti di Google Chat
• Aprire finestre di dialogo interattive
• Esplorare altri esempi di app Google Chat