Partez en vacances avec une application Google Chat

1. Introduction

Les applications Google Chat fournissent des services et des ressources directement dans Chat, qui permet aux utilisateurs de chercher des informations et d'effectuer des actions sans quitter la conversation.

Dans cet atelier de programmation, vous allez apprendre à créer une application Chat, "Attendance Bot" (Bot de présence), qui définit des réponses automatiques dans Gmail et planifie des réunions dans Google Agenda. Lorsque vous créez Attendance Bot dans Google Apps Script, vous pouvez facilement accéder à d'autres services Google tels que Drive, Gmail, Agenda, Docs, Sheets, et bien plus encore.

Points abordés

Ajouter des gestionnaires pour les événements déclenchés dans Chat
Analyser des objets d'événement envoyés par Chat
Utiliser des réponses sous forme de fiches pour répondre à Chat
Définir et traiter des actions personnalisées associées aux clics sur les boutons des fiches

Prérequis

Accès à Internet et à un navigateur Web.
Compte Google Workspace ayant accès à Google Chat.
Connaissances de base de JavaScript, Google Apps Script prend en charge uniquement JavaScript.

2. Obtenir l'exemple de code

Vous téléchargez un fichier ZIP ou clonez le dépôt GitHub pour voir le code de chaque étape de cet exemple.

Les dossiers step-NN contiennent l'état final souhaité de chaque étape de cet atelier de programmation. Ils sont fournis à titre de référence.

Télécharger le code

Pour télécharger le code de cet atelier de programmation, cliquez sur le bouton suivant :

Décompressez le fichier ZIP téléchargé. Cette action décompresse le dossier racine (hangouts-chat-apps-script-codelab), qui contient un dossier pour chaque étape de cet atelier de programmation.

Cloner le dépôt GitHub

Pour cloner le dépôt GitHub pour cet atelier de programmation, exécutez la commande suivante :

git clone https://github.com/googleworkspace/hangouts-chat-apps-script-codelab

3. Créer les gestionnaires pour les événements Google Chat

Créer un projet Apps Script

Pour créer un projet Apps Script, procédez comme suit :

Accédez à script.new.
Cliquez sur Projet sans titre.
Renommez le script Attendance Bot et cliquez sur Renommer.

Événements dans Google Chat

La plupart des interactions Apps Script avec Chat sont basées sur des événements. Les interactions entre l'utilisateur, l'application Chat et Chat se déroulent généralement de la manière suivante :

Un utilisateur lance une action, telle que l'ajout d'une application Chat à un espace, le démarrage d'un message privé (MP) avec une application Chat ou la suppression d'une application Chat d'un espace.
Cette action déclenche un événement destiné à l'application Chat dans Chat.
Chat appelle le gestionnaire d'événements correspondant défini dans le script de l'application Chat.

Chat déclenche 4 événements que votre application peut écouter :

ADDED_TO_SPACE : cet événement se produit lorsqu'un utilisateur humain ajoute une application Chat à un espace ou un message privé (MP). Dans Apps Script, la gestion de cet événement s'effectue grâce à une fonction onAddToSpace().
REMOVED_FROM_SPACE : cet événement se produit lorsqu'un utilisateur supprime l'application Chat d'un espace ou d'un MP. Cet événement ne publie aucun message de réponse à l'intention de Chat. Dans Apps Script, la gestion de cet événement s'effectue grâce à une fonction onRemoveFromSpace().
MESSAGE : cet événement se produit lorsqu'un utilisateur envoie un message à l'application Chat, directement dans un MP ou à l'aide d'une @mention dans un espace. Dans Apps Script, la réponse à cet événement s'effectue grâce à une fonction onMessage().
CARD_CLICKED : cet événement se produit lorsque l'utilisateur clique sur un bouton auquel une action personnalisée est attribuée. Dans Apps Script, la réponse à cet événement s'effectue grâce à une fonction onCardClick().

Remplacez le contenu du fichier Code.gs par le code suivant qui définit les gestionnaires pour les événements ADDED_TO_SPACE et REMOVE_FROM_SPACE. (Vous ajouterez les gestionnaires des événements MESSAGE et CARD_CLICKED dans la suite de cet atelier de programmation.)

Code.gs

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

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

4. Publier et tester l'application Chat

Mettre à jour le fichier manifeste du script

Pour pouvoir publier votre application dans Chat, vous devez mettre à jour le fichier manifeste du script.

Cliquez sur Paramètres du projet.
Cochez la case Afficher le fichier manifeste "appsscript.json" dans l'éditeur.
Cliquez sur Éditeur.
Cliquez sur le fichier appsscript.json.
Ajoutez la ligne "chat": {} à votre fichier manifeste.

Votre fichier manifeste doit ressembler à l'exemple suivant.

appsscript.json

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

Créer un projet Google Cloud

Pour pouvoir exécuter et tester l'application Chat, vous devez créer un projet Google Cloud, activer et configurer l'API Chat, et publier votre application Chat dans votre organisation Google Workspace.

Dans la console Google Cloud, accédez à Menu > IAM et administration > Créer un projet.
Dans Nom du projet, entrez un nom descriptif.
Si vous y êtes invité, sélectionnez l'organisation et le compte de facturation.
Cliquez sur Créer.
Une fois le projet créé, une notification apparaît dans l'angle supérieur droit de la page. Cliquez sur l'entrée Créer un projet : <Project name> pour ouvrir le projet.
Cliquez sur Menu > API et services > Identifiants.
Cliquez sur l'écran de consentement OAuth.
Dans Nom de l'application, saisissez Attendance Bot.
Si vous y êtes invité, saisissez l'adresse e-mail d'assistance utilisateur et les coordonnées du développeur.
Cliquez sur Enregistrer et continuer.
Cliquez sur Paramètres et utilitaires > Paramètres du projet.
Copiez le numéro du projet.
Dans l'éditeur Apps Script, cliquez sur Paramètres du projet .
Sous Projet Google Cloud Platform (GCP), cliquez sur Changer de projet.
Cliquez sur Numéro de projet GCP et saisissez le numéro du projet.
Cliquez sur Définir un projet.

Publier l'application dans Chat

Pour publier votre application Chat dans Google Chat, procédez comme suit :

Dans l'éditeur Apps Script, cliquez sur Déployer > Nouveau déploiement.
En regard de Sélectionner le type, cliquez sur "Activer les types de déploiement" .
Sélectionnez Module complémentaire et cliquez sur Déployer.
Copiez l'ID de déploiement et cliquez sur OK.
Dans la console Google Cloud, accédez à Menu > API et services > Bibliothèque.
Recherchez API Google Chat. Sélectionnez l'API dans la liste des résultats.
Sur la page API Google Chat, cliquez sur Activer.
Une fois l'API activée, cliquez sur Configuration. Ignorez tous les messages vous demandant de créer des identifiants.
Sur la page Configuration, procédez comme suit :

Dans Nom de l'application, saisissez Attendance Bot.
Pour URL de l'avatar, entrez https://goo.gl/kv2ENA.
Pour Description, entrez Atelier de programmation Apps Script et application Chat.
Sous Fonctionnalités, sélectionnez Recevoir des messages privés.
Sous Paramètres de connexion, sélectionnez Projet Apps Script et collez l'ID de déploiement de votre script dans la zone de texte.
Sous Autorisations, sélectionnez Utilisateurs et groupes spécifiques de votre domaine. Dans la zone de texte située sous le menu déroulant, saisissez l'adresse e-mail associée à votre organisation Google Workspace.
Cliquez sur Enregistrer.

Après avoir enregistré vos modifications, vérifiez que la zone État de l'application est définie sur EN COURS - disponible pour les utilisateurs sur la page API Google Chat.

Tester l'application Chat

Pour tester votre application dans Google Chat, procédez comme suit :

Ouvrez Google Chat.
Envoyez un nouveau message privé à l'application Chat en cliquant sur Démarrer un chat > Rechercher des applications.
Sur la page "Rechercher des applications", recherchez Attendance Bot.
En regard de Attendance Bot, cliquez sur Ajouter > Chat.

Lorsque le fil de discussion de messages privés s'affiche, vous devez recevoir un message dans lequel l'application Chat vous remercie de l'avoir ajoutée à un MP, comme illustré ci-dessous.

5. Définir une réponse sous forme de fiche

À l'étape précédente, votre application répondait aux événements Google Chat par un texte simple. Vous allez à présent mettre à jour votre application pour qu'elle réponde par des fiches.

Réponses sous forme de fiches

Google Chat accepte l'envoi de réponses sous forme de fiches. Les fiches sont des conteneurs visuels qui vous permettent de regrouper des ensembles de widgets d'interface utilisateur. Elles peuvent afficher des en-têtes, des paragraphes de texte, des ensembles de boutons, des images, ainsi que du texte d'attribut valeur/clé. Votre application peut définir une ou plusieurs fiches dans la réponse JSON qu'elle adresse à Google Chat. Celle-ci convertit alors votre réponse en éléments d'interface utilisateur correspondants.

L'image ci-après illustre une réponse sous forme de fiche comportant trois sections et comprenant un en-tête, un widget de clé/valeur, un widget d'image, ainsi qu'un bouton de texte.

Pour répondre aux messages des utilisateurs sous la forme d'une fiche, ajoutez le code suivant au fichier Code.gs de votre application Chat.

Code.gs

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

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

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

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

  return createCardResponse(widgets);
}

La fonction onMessage(), ajoutée à cette étape, lit le message d'origine de l'utilisateur et élabore une réponse sous forme de widget TextParagragh simple. Ensuite, la fonction onMessage() appelle createCardResponse(), qui place le widget TextParagraph dans une section d'une fiche spécifique. Le bot renvoie à Google Chat l'objet JavaScript construit avec la réponse sous forme de fiche.

Tester l'application Chat

Pour tester cette application, revenez à votre message privé avec l'application dans Google Chat et saisissez un message quelconque.

Notez que le gestionnaire d'événements onMessage() analyse l'objet d'événement que lui a transmis Google Chat pour extraire le message d'origine de l'utilisateur. Vous pouvez également obtenir d'autres types d'informations concernant l'événement, tels que le nom et l'adresse e-mail de l'utilisateur ayant déclenché l'événement, le nom de l'espace dans lequel l'événement s'est produit, etc.

Pour en savoir plus sur la structure des objets d'événement envoyés par Google Chat, consultez la documentation de référence consacrée au format des événements.

6. Réagir aux clics sur les boutons des fiches

À l'étape précédente, votre application Chat répondait au message d'un utilisateur (événement MESSAGE) par une fiche simple qui contenait un widget TextParagraph. Dans cette étape, vous allez créer une réponse incluant différents boutons pour lesquels des actions personnalisées distinctes ont été définies.

Fiches interactives

Les réponses sous forme de fiches peuvent contenir l'un des deux types de boutons suivants : widgets TextButton, qui affichent des boutons de texte seul, ou widgets ImageButton, qui présentent un bouton avec une simple icône ou image sans texte. Les widgets TextButton et ImageButton prennent en charge l'un des deux comportements onClick (tel que défini dans la réponse JSON renvoyée à Google Chat) : openLink ou action. Comme son nom l'implique, openLink ouvre un lien spécifié dans un nouvel onglet du navigateur.

En revanche, l'objet action spécifie une action personnalisée que le bouton doit effectuer. Vous pouvez spécifier plusieurs valeurs arbitraires dans l'objet d'action (par exemple, un actionMethodName unique et un ensemble de paires de paramètres clé/valeur).

La spécification d'un objet action pour le bouton crée une fiche interactive. Lorsque l'utilisateur clique sur le bouton figurant dans le message, Google Chat déclenche un événement CARD_CLICKED et renvoie une requête à l'application ayant envoyé le message d'origine. L'application doit ensuite gérer l'événement déclenché par Google Chat et renvoyer une réponse à l'espace.

Remplacez la fonction onMessage() dans le code Code.gs par le code suivant : Ce code crée 2 boutons dans la fiche envoyée à Google Chat : Définir la réponse automatique dans Gmail et Bloquer la journée dans l'agenda.

Code.gs

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

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

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

Pour gérer l'événement CARD_CLICKED, vous devez ajouter la fonction onCardClick() au script de votre application Chat. Ajoutez le code suivant pour définir la fonction onCardClick() dans Code.gs.

Code.gs

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

En réponse aux clics des utilisateurs, l'application Chat effectue désormais l'une des deux opérations suivantes : elle définit la réponse automatique de l'utilisateur dans Gmail sur un message "out of office" (absent du bureau), ou elle planifie une réunion portant sur la journée entière dans l'agenda de l'utilisateur. Pour accomplir ces tâches, l'application appelle le service avancé de Gmail et le service Agenda

Ajoutez le code suivant à votre script pour intégrer l'application Chat à Gmail et Agenda.

Code.gs

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

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

Pour finir, vous devez activer le service avancé de Gmail dans le projet. Pour activer l'API Gmail, procédez comme suit :

Dans l'éditeur Apps Script, en regard de Services, cliquez sur Ajouter un service .
Sélectionnez API Gmail.
Cliquez sur le tableau de bord des API Google Cloud Platform, comme illustré ci-dessous, afin d'ouvrir la console Google Cloud.
Cliquez sur Activer les API et les services.
Recherchez l'API Gmail, puis cliquez dessus.
Sur la page de l'API Gmail, cliquez sur Activer.

Tester l'application Chat

Pour tester cette version de votre application Chat, ouvrez le MP que vous avez démarré aux étapes précédentes dans Google Chat et saisissez Je pars en vacances. L'application doit répondre par une fiche semblable à celle illustrée ci-dessous.

Remarque : Si vous êtes invité à donner accès à votre application, vous devrez peut-être saisir votre message une deuxième fois.

7. Félicitations !

Votre application Chat peut désormais répondre aux messages des utilisateurs, définir leur réponse automatique dans Gmail et insérer un événement portant sur la journée entière dans leur agenda.

Points abordés

Créer et publier une application Google Chat à l'aide d'Apps Script
Répondre aux messages des utilisateurs par une réponse simple
Interagir avec d'autres services Google Workspace à la place de l'utilisateur via l'application Chat

Partez en vacances avec une application Google Chat

1. Introduction

Points abordés

Prérequis

2. Obtenir l'exemple de code

Télécharger le code

Cloner le dépôt GitHub

3. Créer les gestionnaires pour les événements Google Chat

Créer un projet Apps Script

Événements dans Google Chat

Code.gs

4. Publier et tester l'application Chat

Mettre à jour le fichier manifeste du script

appsscript.json

Créer un projet Google Cloud

Publier l'application dans Chat

Tester l'application Chat

5. Définir une réponse sous forme de fiche

Réponses sous forme de fiches

Code.gs

Tester l'application Chat

6. Réagir aux clics sur les boutons des fiches

Fiches interactives

Code.gs

Code.gs

Code.gs

Tester l'application Chat

7. Félicitations !

Points abordés

En savoir plus