Collecter et gérer les contacts dans Google Chat

Ce tutoriel explique comment créer une application Google Chat qui aide les utilisateurs de Google Chat à gérer leurs contacts personnels et professionnels. Pour collecter des informations, l'application Chat invite les utilisateurs à remplir un formulaire de contact dans les messages de fiche et les boîtes de dialogue.

Découvrez l'application Chat en action:

  • Formulaire de contact d'une commande à barre oblique.
    Figure 1. L'application Chat répond à la commande à barre oblique /about avec un message texte et un bouton qui ouvre un formulaire de contact.
  • Formulaire de contact dans une boîte de dialogue.
    Figure 2 : L'application Chat ouvre une boîte de dialogue dans laquelle les utilisateurs peuvent saisir des informations sur un contact.
  • Boîte de dialogue de confirmation et d'examen.
    Figure 3. L'application Chat affiche une boîte de dialogue de confirmation afin que les utilisateurs puissent vérifier et confirmer les informations avant de les envoyer.
  • Un message texte confirmant le nouveau contact.
    Figure 4. Une fois que l'utilisateur a envoyé le formulaire, l'application Chat envoie un message privé pour confirmer l'envoi.
  • Formulaire de contact à partir d'un message de carte
    Figure 5 L'application Chat invite également les utilisateurs à ajouter un contact à partir d'une fiche dans un message.

Prérequis

Objectifs

Architecture

L'application Chat est créée dans Google Apps Script et utilise des événements d'interaction pour traiter et répondre aux utilisateurs de Chat.

Voici comment un utilisateur peut généralement interagir avec l'application Chat:

  1. Un utilisateur ouvre un message privé avec l'application Chat ou ajoute cette application à un espace existant.

  2. L'application Chat invite l'utilisateur à ajouter un contact en créant et en affichant un formulaire de contact en tant qu'objet card. Pour présenter le formulaire de contact, l'application Chat répond aux utilisateurs comme suit:

    • Répond aux mentions et aux messages privés avec un message avec fiche contenant le formulaire de contact.
    • Répond à la commande à barre oblique /addContact en ouvrant une boîte de dialogue avec le formulaire de contact.
    • Répond à la commande à barre oblique /about par un message texte avec un bouton Ajouter un contact sur lequel les utilisateurs peuvent cliquer pour ouvrir une boîte de dialogue avec le formulaire de contact.

  3. Lorsqu'il reçoit le formulaire de contact, l'utilisateur saisit ses coordonnées dans les champs et widgets suivants:

    • Prénom et nom: widget textInput qui accepte les chaînes.
    • Date de naissance: widget dateTimePicker qui n'accepte que des dates.
    • Type de contact: widget selectionInput de cases d'option permettant aux utilisateurs de sélectionner et d'envoyer une seule valeur de chaîne (Personal ou Work).
    • Bouton Examiner et envoyer: tableau buttonList avec le widget button sur lequel l'utilisateur clique pour envoyer les valeurs qu'il a saisies.

  4. L'application Google Chat gère un événement d'interaction CARD_CLICKED pour traiter les valeurs saisies par l'utilisateur et les afficher dans une fiche de confirmation.

  5. L'utilisateur examine la carte de confirmation, puis clique sur le bouton Submit (Envoyer) pour finaliser les coordonnées.

  6. L'application Google Chat envoie un message privé pour confirmer l'envoi.

Préparer l'environnement

Cette section explique comment créer et configurer un projet Google Cloud pour l'application Chat.

Créer un projet Google Cloud

console Google Cloud

  1. Dans la console Google Cloud, accédez à Menu > IAM et administration > Créer un projet.

    Accéder à "Créer un projet"

  2. Dans le champ Project Name (Nom du projet), saisissez un nom descriptif pour votre projet.

    Facultatif : Pour modifier l'ID de projet, cliquez sur Modifier. Une fois le projet créé, vous ne pourrez plus modifier l'ID. Choisissez-en donc un qui répond à vos besoins pour toute la durée de vie du projet.

  3. Dans le champ Emplacement, cliquez sur Parcourir pour afficher les emplacements potentiels de votre projet. Cliquez ensuite sur Sélectionner.
  4. Cliquez sur Créer. La console Google Cloud accède à la page "Tableau de bord", et votre projet est créé en quelques minutes.

CLI gcloud

Dans l'un des environnements de développement suivants, accédez à la Google Cloud CLI (gcloud) :

  • Cloud Shell: pour utiliser un terminal en ligne avec la CLI gcloud configurée, activez Cloud Shell.
    Activer Cloud Shell
  • Shell local : pour utiliser un environnement de développement local, installez et initialisez gcloud CLI.
    Pour créer un projet Cloud, utilisez la commande gcloud projects create: 
    gcloud projects create PROJECT_ID
     Remplacez PROJECT_ID en définissant l'ID du projet que vous souhaitez créer.

Configurer l'authentification et l'autorisation

Les applications Google Chat nécessitent que vous configuriez un écran de consentement OAuth afin que les utilisateurs puissent autoriser votre application dans les applications Google Workspace, y compris Google Chat.

Dans ce tutoriel, vous déployez une application Chat réservée aux tests et à un usage interne. Vous pouvez donc utiliser des informations d'espace réservé pour l'écran de consentement. Avant de publier l'application Chat, remplacez toutes les informations d'espace réservé par des informations réelles.

  1. Dans la console Google Cloud, accédez à Menu > API et services > Écran de consentement OAuth.

    Accéder à l'écran de consentement OAuth

  2. Sous Type d'utilisateur, sélectionnez Interne, puis cliquez sur Créer.

  3. Dans le champ Nom de l'application, saisissez Contact Manager.

  4. Dans Adresse e-mail d'assistance utilisateur, sélectionnez votre adresse e-mail ou un groupe Google approprié.

  5. Sous Coordonnées du développeur, saisissez votre adresse e-mail.

  6. Cliquez sur Enregistrer et continuer.

  7. Sur la page Champs d'application, cliquez sur Enregistrer et continuer. (L'application Chat ne nécessite aucune habilitation OAuth.)

  8. Vérifiez le résumé, puis cliquez sur Revenir au tableau de bord.

Créer et déployer l'application Chat

Dans la section suivante, vous allez copier et mettre à jour un projet Apps Script entier contenant tout le code d'application requis pour votre application Chat. Il n'est donc pas nécessaire de copier et coller chaque fichier.

Vous pouvez également consulter l'intégralité du projet sur GitHub.

Afficher sur GitHub

Voici un aperçu de chacun d'eux :

main.gs

Gère toute la logique de l'application, y compris les événements d'interaction lorsque les utilisateurs envoient des messages à l'application Chat, cliquent sur des boutons à partir d'un message de l'application Chat ou ouvrent et ferment des boîtes de dialogue.

Afficher le code main.gs

apps-script/contact-form-app/main.gs
/**
 * 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: "openInitialDialog",
                interaction: "OPEN_DIALOG"
              }}
            }]}
          }]
        }
      case 2:
        // If the slash command is "/addContact", opens a dialog.
        return openInitialDialog();
    }
  }

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

/**
 * 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 === "openInitialDialog") {
    return openInitialDialog();
  // Confirmation dialog form page
  } else if (event.common.invokedFunction === "openConfirmation") {
    return openConfirmation(event);
  // Submission dialog form page
  } else if (event.common.invokedFunction === "submitForm") {
    return submitForm(event);
  }
}

/**
 * Opens the initial step of the dialog that lets users add contact details.
 *
 * @return {Object} a message with an action response to open a dialog.
 */
function openInitialDialog() {
  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: "openConfirmation" }}
        }]}
      }])
    }]}}}
  }};
}

/**
 * Returns the second step as a dialog or card message that lets users confirm details.
 *
 * @param {Object} event the interactive event with form inputs.
 * @return {Object} returns a dialog or private card message.
 */
function openConfirmation(event) {
  const name = fetchFormValue(event, "contactName") ?? "";
  const birthdate = fetchFormValue(event, "contactBirthdate") ?? "";
  const type = fetchFormValue(event, "contactType") ?? "";
  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 (event.isDialogEvent) {
    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: event.user,
    cardsV2: [{
      card: { sections: [cardConfirmation]}
    }]
  }
}

/**
  * Validates and submits information from a dialog or card message
  * and notifies status.
  *
  * @param {Object} event the interactive event with parameters.
  * @return {Object} a message response that opens a dialog or posts a private
  *                  message.
  */
function submitForm(event) {
  const contactName = event.common.parameters["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 (event.dialogEventType === "SUBMIT_DIALOG") {
      return { actionResponse: {
        type: "DIALOG",
        dialogAction: { actionStatus: {
          statusCode: "INVALID_ARGUMENT",
          userFacingMessage: errorMessage
        }}
      }};
    } else {
      return {
        privateMessageViewer: event.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 (event.dialogEventType === "SUBMIT_DIALOG") {
    return {
      actionResponse: {
        type: "DIALOG",
        dialogAction: { actionStatus: {
          statusCode: "OK",
          userFacingMessage: "Success " + contactName
        }}
      }
    }
  } else {
    return {
      actionResponse: { type: "NEW_MESSAGE" },
      privateMessageViewer: event.user,
      text: confirmationMessage
    };
  }
}

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

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

Contient les widgets qui reçoivent les données de formulaire des utilisateurs. Ces widgets de saisie de formulaire s'affichent dans des fiches qui apparaissent dans les messages et les boîtes de dialogue.

Afficher le code contactForm.gs

apps-script/contact-form-app/contactForm.gs
/**
 * 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

Le fichier manifeste Apps Script qui définit et configure le projet Apps Script pour l'application Chat.

Afficher le code appsscript.json

apps-script/contact-form-app/appsscript.json
{
  "timeZone": "America/Los_Angeles",
  "dependencies": {},
  "exceptionLogging": "STACKDRIVER",
  "runtimeVersion": "V8",
  "chat": {}
}

Trouver votre numéro et votre ID de projet Cloud

  1. Dans la console Google Cloud, accédez à votre projet Cloud.

    Accéder à Google Cloud Console

  2. Cliquez sur Paramètres et utilitaires  > Paramètres du projet.

  3. Notez les valeurs des champs Project number (Numéro de projet) et Project ID (ID du projet). Vous les utiliserez dans les sections suivantes.

Créer le projet Apps Script

Pour créer un projet Apps Script et l'associer à votre projet Cloud:

  1. Cliquez sur le bouton suivant pour ouvrir le projet Apps Script Gérer les contacts dans Google Chat.
    Ouvrir le projet
  2. Cliquez sur  Vue d'ensemble.
  3. Sur la page de présentation, cliquez sur Icône pour créer une copie Créer une copie.

  4. Nommez votre copie du projet Apps Script:

    1. Cliquez sur Copie de "Gérer les contacts dans Google Chat".

    2. Dans Titre du projet, saisissez Contact Manager - Google Chat app.

    3. Cliquez sur Renommer.

Définir le projet Cloud du projet Apps Script

  1. Dans votre projet Apps Script, cliquez sur Icône des paramètres du projet Paramètres du projet.
  2. Sous Projet Google Cloud Platform (GCP), cliquez sur Changer de projet.
  3. Dans Numéro de projet GCP, collez le numéro de votre projet Cloud.
  4. Cliquez sur Définir un projet. Le projet Cloud et le projet Apps Script sont maintenant connectés.

Créer un déploiement Apps Script

Maintenant que tout le code est en place, déployez le projet Apps Script. Vous utilisez l'ID de déploiement lorsque vous configurez l'application Chat dans Google Cloud.

  1. Dans Apps Script, ouvrez le projet de l'application Chat.

    Accéder à Apps Script

  2. Cliquez sur Déployer > Nouveau déploiement.

  3. Si Module complémentaire n'est pas déjà sélectionné, en regard de Sélectionner le type, cliquez sur "Types de déploiement" Icône des paramètres du projet, puis sélectionnez Module complémentaire.

  4. Dans Description, saisissez une description de cette version, par exemple Test of Contact Manager.

  5. Cliquez sur Déployer. Apps Script signale que le déploiement a réussi et fournit un ID de déploiement.

  6. Cliquez sur  Copier pour copier l'ID de déploiement, puis sur OK.

Configurer l'application Chat dans la console Google Cloud

Cette section explique comment configurer l'API Google Chat dans la console Google Cloud avec des informations sur votre application Chat, y compris l'ID du déploiement que vous venez de créer à partir de votre projet Apps Script.

  1. Dans la console Google Cloud, cliquez sur Menu > Autres produits > Google Workspace > Bibliothèque de produits > API Google Chat > Gérer > Configuration.

    Accéder à la configuration de l'API Chat

  2. Dans le champ Nom de l'application, saisissez Contact Manager.

  3. Dans le champ URL de l'avatar, saisissez https://developers.google.com/chat/images/contact-icon.png.

  4. Dans Description, saisissez Manage your personal and business contacts.

  5. Cliquez sur le bouton Activer les fonctionnalités interactives pour l'activer.

  6. Sous Fonctionnalité, cochez les cases Recevoir des messages privés et Rejoindre des espaces et des conversations de groupe.

  7. Sous Paramètres de connexion, sélectionnez Apps Script.

  8. Dans ID de déploiement, collez l'ID de déploiement Apps Script que vous avez copié dans la section précédente lorsque vous avez créé le déploiement Apps Script.

  9. Sous Commandes à barre oblique, configurez les commandes à barre oblique /about et /addContact:

    1. Cliquez sur Ajouter une commande à barre oblique pour configurer la première commande à barre oblique.
    2. Dans Nom, saisissez /about.
    3. Dans ID de commande, saisissez 1.
    4. Dans Description, saisissez Learn how to use this Chat app to manage your contacts.
    5. Sélectionnez Ouvre une boîte de dialogue.
    6. Cliquez sur OK.
    7. Cliquez sur Ajouter une commande à barre oblique pour configurer une autre commande à barre oblique.
    8. Dans le champ Nom, saisissez /addContact.
    9. Dans ID de commande, saisissez 2.
    10. Dans Description, saisissez Submit information about a contact.
    11. Sélectionnez Ouvre une boîte de dialogue.
    12. Cliquez sur OK.

  10. Sous Visibilité, cochez la case Rendre cette application de chat accessible à certains utilisateurs et groupes du domaine YOUR DOMAIN, puis saisissez votre adresse e-mail.

  11. Sous Journaux, sélectionnez Consigner les erreurs dans Logging.

  12. Cliquez sur Enregistrer. Un message indiquant que la configuration a été enregistrée s'affiche.

L'application Chat est prête à être installée et testée dans Chat.

Tester l'application Chat

Pour tester votre application Chat, ouvrez un espace de messages privés avec l'application Chat et envoyez un message:

  1. Ouvrez Google Chat avec le compte Google Workspace que vous avez fourni lorsque vous vous êtes ajouté en tant que testeur de confiance.

    Accéder à Google Chat

  2. Cliquez sur  Nouveau chat.
  3. Dans le champ Ajouter une ou plusieurs personnes, saisissez le nom de votre application Chat.

  4. Sélectionnez votre application Chat dans les résultats. Un message privé s'ouvre.

  1. Dans le nouveau message privé avec l'application Chat, saisissez /addContact, puis appuyez sur Entrée.

  2. Dans la boîte de dialogue qui s'ouvre, saisissez les coordonnées:

    1. Dans le champ de texte Prénom et nom, saisissez un nom.
    2. Dans le sélecteur de date de date de naissance, sélectionnez une date.
    3. Sous Type de contact, sélectionnez la case d'option Professionnel ou Personnel.

  3. Cliquez sur Vérifier et envoyer.

  4. Dans la boîte de dialogue de confirmation, vérifiez les informations que vous avez envoyées, puis cliquez sur Submit (Envoyer). L'application Chat répond par un message de texte indiquant ✅ CONTACT NAME has been added to your contacts..

  5. Vous pouvez également tester et envoyer le formulaire de contact de la manière suivante:

    • Utilisez la commande à barre oblique /about. L'application Chat répond par un message et un bouton de widget accessoire indiquant Add a contact. Vous pouvez cliquer sur ce bouton pour ouvrir une boîte de dialogue contenant le formulaire de contact.
    • Envoyez un message privé à l'application Chat sans commande à barre oblique, par exemple Hello. L'application Chat répond avec un texte et une fiche contenant le formulaire de contact.

Effectuer un nettoyage

Pour éviter que les ressources utilisées dans ce tutoriel soient facturées sur votre compte Google Cloud, nous vous recommandons de supprimer le projet Cloud.

  1. Dans la console Google Cloud, accédez à la page Gérer les ressources. Cliquez sur Menu  > IAM et administration > Gérer les ressources.

    Accédez au gestionnaire de ressources.

  2. Dans la liste des projets, sélectionnez celui que vous souhaitez supprimer, puis cliquez sur Supprimer .
  3. Dans la boîte de dialogue, saisissez l'ID du projet, puis cliquez sur Arrêter pour supprimer le projet.