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 à partir de la commande à barre oblique.
    Figure 1. La L'application Chat répond à la commande à barre oblique /about par un message textuel et un bouton qui ouvre un formulaire de contact.
  • Formulaire de contact dans une boîte de dialogue.
    Figure 2 : La L'application Chat ouvre une boîte de dialogue dans laquelle les utilisateurs peuvent saisir des informations sur un contact.
  • Boîte de dialogue "Confirmer et examiner".
    Figure 3 : L'application Chat affiche une boîte de dialogue de confirmation afin que les utilisateurs puissent examiner et confirmer les informations avant de les envoyer.
  • Un SMS 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 sur une fiche.
    Figure 5 : La 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.

L'exemple suivant montre comment un utilisateur peut généralement interagir avec Application de chat:

  1. Un utilisateur ouvre un message privé avec l'application Chat ou ajoute l'application Chat à 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 de différentes manières:

    • 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.
    • Elle répond à la commande à barre oblique /about par un message contenant un Bouton Ajouter un contact sur lequel les utilisateurs peuvent cliquer pour ouvrir une boîte de dialogue contenant 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 des chaînes.
    • Date de naissance: a dateTimePicker widget qui n'accepte que les dates.
    • Type de contact: a selectionInput widget de cases d'option permettant aux utilisateurs de sélectionner et d'envoyer une seule chaîne (Personal ou Work).
    • Bouton Examiner et envoyer: a buttonList tableau avec le widget button sur lequel l'utilisateur clique pour envoyer les valeurs qu'ils saisissent.
  4. L'application Google Chat gère un événement d'interaction CARD_CLICKED pour traiter les valeurs saisies par l'utilisateur, puis affiche les valeurs dans une carte de confirmation.

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

  6. L'application Google Chat envoie un message privé qui confirme l'envoi.

Préparer l'environnement

Cette section explique comment créer et configurer un projet Google Cloud pour le 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 à la page "Créer un projet"

  2. Dans le champ Nom du projet, saisissez un nom descriptif pour votre projet.

    Facultatif: Pour modifier l'ID du projet, cliquez sur Modifier. Impossible de modifier l'ID du projet Une fois le projet créé, choisissez donc un ID qui répond à vos besoins pendant toute la durée de vie 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 console CLI (gcloud):

  • Cloud Shell : pour utiliser un terminal en ligne avec gcloud CLI déjà configuré, 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 l'écran de consentement OAuth, afin que utilisateurs peuvent autoriser votre application dans les applications Google Workspace, y compris Google Chat.

Dans ce tutoriel, vous déployez une application Chat réservée les tests et l'utilisation interne. Vous pouvez donc utiliser des informations d'espace réservé l'écran de consentement. Avant de publier l'application Chat, remplacez les informations d'espace réservé avec 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. (Le L'application Chat ne nécessite aucune habilitation OAuth.)

  8. Examinez le récapitulatif, 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 complet contenant tout le code d'application requis pour votre application Chat. Vous n'avez donc pas besoin de copier et coller chaque fichier.

Vous pouvez éventuellement afficher l'intégralité du projet sur GitHub.

Afficher sur GitHub

Voici un aperçu de chaque fichier:

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: "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

Contient les widgets qui reçoivent les données de formulaire des utilisateurs. Ces données de saisie les widgets 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 le numéro et l'ID de votre 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 Numéro du projet et ID du projet. Toi utilisez-les dans les sections suivantes.

Créer le projet Apps Script

Pour créer un projet Apps Script et l'associer à votre 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 "Vue d'ensemble", cliquez sur Créer une copie Icône pour 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 associés.

Créer un déploiement Apps Script

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

  1. Dans Apps Script, ouvrez le fichier projet.

    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 pour cette version, par exemple Test of Contact Manager

  5. Cliquez sur Déployer. Apps Script indique 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 cliquez 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 contenant des informations sur votre application Chat, y compris ID du déploiement que vous venez de créer à partir de votre script Apps Script projet.

  1. Dans la console Google Cloud, cliquez sur Menu. &gt; Autres produits &gt; Google Workspace &gt; Bibliothèque de produits &gt; API Google Chat &gt; Gérer &gt; 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. Activez l'option Activer les fonctionnalités interactives.

  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 Deployment ID (ID de déploiement), collez l'ID de déploiement Apps Script. que vous avez copiées dans la section précédente lors de la création du Déploiement d'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 le champ 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 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é, sélectionnez l'icône Rendre cette application Chat accessible à des personnes et groupes spécifiques dans YOUR DOMAIN, puis saisissez votre adresse e-mail.

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

  12. Cliquez sur Enregistrer. Un message de configuration 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 direct message 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'affiche, saisissez vos 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 et cliquez sur 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 comme suit :

    • Utilisez la commande à barre oblique /about. L'application de chat répond avec un message texte et un bouton de widget accessoire indiquant Add a contact. Vous pouvez cliquer sur ce bouton pour ouvrir une boîte de dialogue contenant 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

Afin d'éviter que des frais ne soient facturés sur votre compte Google Cloud pour utilisées dans ce tutoriel, nous vous recommandons de supprimer Google 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.