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 :

Prérequis

• Compte Google Workspace Business ou Enterprise ayant accès à Google Chat.
• Créez un projet Google Cloud.

Objectifs

• Concevez et créez des interfaces utilisateur (UI) en tant qu'objets card, puis affichez-les dans des messages et des boîtes de dialogue.
• Recevoir et traiter les informations que les utilisateurs envoient à l'aide de widgets de saisie de formulaire.
• Répondez aux commandes avec des messages contenant du texte, des fiches et des widgets accessoires.

Architecture

L'application Chat est intégrée à Google Apps Script (en tant que module complémentaire Google Workspace qui étend Google Chat) et répond aux interactions des utilisateurs (onMessage, onAppCommand et clics sur les boutons qui appellent openInitialDialog, openConfirmationDialog et submitForm) pour traiter les utilisateurs Chat et leur répondre.

Voici comment un utilisateur peut interagir avec l'application 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 sous la forme d'un objet card. Pour présenter le formulaire de contact, l'application Chat répond aux utilisateurs de la manière suivante :

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

3. Lorsqu'il est invité à remplir le formulaire de contact, l'utilisateur saisit ses coordonnées dans les champs et widgets suivants :

   • Nom et prénom : widget textInput qui accepte les chaînes.
   • Date de naissance : widget dateTimePicker qui n'accepte que les 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 saisit.

4. L'application Google Chat appelle openConfirmationDialog pour traiter les valeurs saisies par l'utilisateur et les afficher dans une fiche de confirmation.

5. L'utilisateur examine la fiche de confirmation et clique sur le bouton Envoyer pour appeler submitForm et finaliser les coordonnées.

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

Préparer l'environnement

Cette section explique comment configurer un projet Google Cloud pour l'application Chat.

Ouvrez votre projet Cloud dans la console Google APIs.

Si ce n'est pas déjà fait, ouvrez le projet Cloud que vous souhaitez utiliser pour cet exemple :

1. Dans la console Google APIs, accédez à la page Sélectionner un projet.

   Sélectionner un projet Cloud

2. Sélectionnez le projet Google Cloud que vous souhaitez utiliser. Vous pouvez également cliquer sur Créer un projet et suivre les instructions à l'écran. Si vous créez un projet Google Cloud, vous devrez peut-être activer la facturation pour ce projet.

Configurer l'authentification et l'autorisation

Les applications Google Chat nécessitent la configuration d'un écran de consentement OAuth pour que les utilisateurs puissent autoriser votre application dans les applications Google Workspace, y compris Google Chat.

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

1. Dans la console Google API, accédez à Menu menu > Plate-forme Google Auth > Branding.

   Accéder à la page "Branding"

2. Si vous avez déjà configuré la plate-forme Google Auth, vous pouvez configurer les paramètres de l'écran de consentement OAuth suivants dans Branding, Audience et Accès aux données. Si le message Google Auth Platform pas encore configuré s'affiche, cliquez sur Premiers pas :

   1. Sous Informations sur l'application, dans Nom de l'application, saisissez Contact Manager.
   2. Dans le champ Adresse e-mail d'assistance utilisateur, sélectionnez votre adresse e-mail ou un groupe Google approprié.
   3. Cliquez sur Suivant.
   4. Sous Audience, sélectionnez Interne. Si vous ne pouvez pas sélectionner Interne, sélectionnez Externe.
   5. Cliquez sur Suivant.
   6. Sous Coordonnées, saisissez une adresse e-mail à laquelle vous recevrez des notifications en cas de modification de votre projet.
   7. Cliquez sur Suivant.
   8. Sous Terminer, consultez le Règlement sur les données utilisateur dans les services d'API Google et, si vous l'acceptez, sélectionnez J'accepte le Règlement sur les données utilisateur dans les services d'API Google.
   9. Cliquez sur Continuer.
   10. Cliquez sur Créer.
   11. Si vous avez sélectionné Externe pour le type d'utilisateur, ajoutez des utilisateurs de test :
       1. Cliquez sur Audience.
       2. Sous Test users (Utilisateurs de test), cliquez sur Add users (Ajouter des utilisateurs).
       3. Saisissez votre adresse e-mail et celles des autres utilisateurs test autorisés, puis cliquez sur Enregistrer.

Créer et déployer l'application Chat

Dans la section suivante, vous allez créer et mettre à jour un projet Apps Script avec le code d'application (Code.gs et appsscript.json) pour votre application Chat.

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

Afficher sur GitHub

Voici un aperçu de chaque fichier :

Code.gs

Gère toute la logique de l'application, y compris les interactions utilisateur (onMessage, onAppCommand, openInitialDialog, openConfirmationDialog et submitForm) et les widgets de saisie de formulaire affichés dans les fiches des messages et des boîtes de dialogue.

Afficher le code Code.gs

apps-script/chat/contact-form-app/Code.gs

Afficher sur GitHub

/**
 * Copyright 2025 Google LLC
 *
 * 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 in Google Chat.
 *
 * @param {Object} event The event object from the Google Workspace add-on.
 * @return {Object} response that handles dialogs.
 */
function onMessage(event) {
  // Reply with a message that contains a button to open the initial dialog
  return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
    text: "To add a contact, use the `ADD CONTACT` button below.",
    accessoryWidgets: [
      { buttonList: { buttons: [{
        text: "ADD CONTACT",
        onClick: { action: {
          function: "openInitialDialog",
          interaction: "OPEN_DIALOG"
        }}
      }]}}
    ]
  }}}}};
}

/**
 * Opens the initial step of the dialog that lets users add contact details.
 *
 * @param {Object} event The event object from the Google Workspace add-on.
 * @return {Object} open the dialog.
 */
function openInitialDialog(event) {
  return { action: { navigations: [{ pushCard: { sections: [{ 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 }
      ]
    }},
    { buttonList: { buttons: [{
      text: "NEXT",
      onClick: { action: { function : "openConfirmationDialog" }}
    }]}}
  ]}]}}]}};
}

/**
 * Opens the second step of the dialog that lets users confirm details.
 *
 * @param {Object} event The event object from the Google Workspace add-on.
 * @return {Object} update the dialog.
 */
function openConfirmationDialog(event) {
  // Retrieve the form input values
  const name = event.commonEventObject.formInputs["contactName"].stringInputs.value[0];
  const birthdate = event.commonEventObject.formInputs["contactBirthdate"].dateInput.msSinceEpoch;
  const type = event.commonEventObject.formInputs["contactType"].stringInputs.value[0];
  // Display the input values for confirmation
  return { action: { navigations: [{ pushCard: { sections: [{ widgets: [
    { textParagraph: { text: "Confirm contact information and submit:" }},
    { textParagraph: { text: "<b>Name:</b> " + name }},
    { textParagraph: { text: "<b>Birthday:</b> " + new Date(birthdate) }},
    { textParagraph: { text: "<b>Type:</b> " + type }},
    { buttonList: { buttons: [{
      text: "SUBMIT",
      onClick: { action: {
        function: "submitDialog",
        // Pass input values as parameters for last dialog step (submission)
        parameters: [
          { key: "contactName", value: name },
          { key: "contactBirthdate", value: birthdate },
          { key: "contactType", value: type }
        ]
      }}
    }]}}
  ]}]}}]}};
}

/**
 * Handles submission and closes the dialog.
 *
 * @param {Object} event The event object from the Google Workspace add-on.
 * @return {Object} close the dialog with a status in text notification or message.
 */
function submitDialog(event) {
  // Validate the parameters.
  if (!event.commonEventObject.parameters["contactName"]) {
    return { action: {
      navigations: [{ endNavigation: { action: "CLOSE_DIALOG"}}],
      notification: { text: "Failure, the contact name was missing!" }
    }};
  }

  return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
    text: "✅ " + event.commonEventObject.parameters["contactName"] + " has been added to your contacts."
  }}}}};
}

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/chat/contact-form-app/appsscript.json

Afficher sur GitHub

{
  "timeZone": "America/Los_Angeles",
  "dependencies": {},
  "exceptionLogging": "STACKDRIVER",
  "runtimeVersion": "V8",
  "addOns": {
    "common": {
      "name": "Contact Form app",
      "logoUrl": "https://developers.google.com/workspace/add-ons/images/contact-icon.png"
    },
    "chat": {}
  }
}

Créer le projet Apps Script

Pour créer un projet Apps Script à partir des fichiers Code.gs et appsscript.json :

1. Accédez à Google Apps Script, puis cliquez sur Nouveau projet.

2. Nommez votre projet Apps Script :

   1. Cliquez sur Projet sans titre.

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

   3. Cliquez sur Renommer.

3. Remplacez le contenu de Code.gs par l'exemple de code Code.gs ci-dessus.

4. Cliquez sur Paramètres du projet , puis sélectionnez Afficher le fichier manifeste "appsscript.json" dans l'éditeur.

5. Revenez à l'éditeur et remplacez le contenu de appsscript.json par le code manifeste appsscript.json ci-dessus, puis enregistrez votre projet.

À l'avenir, si vous souhaitez utiliser certaines Google APIs ou publier votre application, vous devrez associer votre projet Cloud à votre projet Apps Script. Pour ce guide, vous n'avez pas besoin de le faire. Pour en savoir plus, consultez le guide sur les projets Google Cloud.

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é, à côté de Sélectionner le type, cliquez sur les types de déploiement , 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 content_copy Copier pour copier l'ID de déploiement, puis cliquez sur OK.

Configurer l'application Chat dans la console Google APIs

Cette section explique comment configurer l'API Google Chat dans la console Google APIs 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 API, cliquez sur Menu menu > API et services > API et services activés > API Google Chat > Configuration.

   Accéder à la configuration de l'API Chat

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

3. Dans 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é, sélectionnez 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 Déclencheurs, configurez les fonctions qui répondent aux interactions utilisateur :

   • Pour le déclencheur Message, saisissez onMessage.
   • Pour le déclencheur Commande d'application, saisissez onAppCommand.

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

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

11. 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.

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

13. Cliquez sur Enregistrer. Un message de confirmation de l'enregistrement de la configuration 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 message privé 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 add Nouvelle discussion.
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 et 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 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 fournies, puis cliquez sur Envoyer. L'application Chat répond par un message texte indiquant ✅ CONTACT NAME has been added to your contacts..

5. Vous pouvez également tester et envoyer le formulaire de contact de différentes manières :

   • Utilisez la commande à barre oblique /about. L'application de chat répond par un message texte et un bouton de widget accessoire indiquant Add a contact. Vous pouvez cliquer sur le 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 APIs, accédez à la page Gérer les ressources. Cliquez sur Menu menu > IAM et administration > Gérer les ressources.

   Accéder au gestionnaire de ressources

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

Articles associés

• Répondre aux commandes
• Collecter et traiter les informations des utilisateurs Google Chat
• Ouvrir des boîtes de dialogue interactives
• Explorer d'autres exemples d'applications Google Chat