Développer une application de chat avec Apps Script

Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

Apps Script est l'un des moyens les plus rapides de créer une application de chat pour Google Chat.

  • Vous pouvez configurer une application en quelques minutes directement dans votre navigateur.
  • Vous n'avez pas à vous soucier de l'exécution et de la gestion des serveurs, des coûts de maintenance ou d'exploitation continus, ni même du téléchargement et de la configuration d'un environnement de développement.
  • Il est très facile d'appeler les API Google, en particulier lesGoogle Workspace API. En effet, avec Apps Script, il n'y a ni téléchargement, ni configuration, l'authentification est gérée automatiquement, et les appels d'API Google sont comme des appels de fonctions natives.

Ce guide explique comment créer et enregistrer une application à l'aide d'Apps Script.

Commencer

Cette section vous explique comment créer rapidement une application de chat à l'aide d'Apps Script.

Étape 1: Copiez le modèle Apps Script

Le moyen le plus simple de créer une application Apps Script consiste à utiliser le modèle d'application Google Chat. Un projet Apps Script est alors créé avec les méthodes dont vous avez besoin. Ensuite, renseignez les méthodes requises pour implémenter la logique de votre application ou pour l'intégrer à une application que vous avez créée. Le code suivant présente un exemple de modèle rempli pour une application simple.

/**
 * Responds to a MESSAGE event in Google Chat.
 *
 * @param {Object} event the event object from Google Chat
 */
function onMessage(event) {
  var name = "";

  if (event.space.type == "DM") {
    name = "You";
  } else {
    name = event.user.displayName;
  }
  var message = name + " said \"" + event.message.text + "\"";

  return { "text": message };
}

/**
 * Responds to an ADDED_TO_SPACE event in Google Chat.
 *
 * @param {Object} event the event object from Google Chat
 */
function onAddToSpace(event) {
  var message = "";

  if (event.space.singleUserBotDm) {
    message = "Thank you for adding me to a DM, " + event.user.displayName + "!";
  } else {
    message = "Thank you for adding me to " +
        (event.space.displayName ? event.space.displayName : "this chat");
  }

  if (event.message) {
    // Bot added through @mention.
    message = message + " and you said: \"" + event.message.text + "\"";
  }

  return { "text": message };
}

/**
 * Responds to a REMOVED_FROM_SPACE event in Google Chat.
 *
 * @param {Object} event the event object from Google Chat
 */
function onRemoveFromSpace(event) {
  console.info("Bot removed from ",
      (event.space.name ? event.space.name : "this chat"));
}


Étape 2: Modifiez la fonction onMessage

Par défaut, la fonction onMessage du modèle renvoie un objet Message contenant du texte et une fiche simple. Vous pouvez modifier cette fonction pour qu'elle renvoie du texte ou des widgets spécifiques aux fiches.

function onMessage(e) {
  return { 'text': 'You said: \`' + e.message.text + '\`' };
}

Étape 3: Obtenez l'ID de déploiement

Avant de pouvoir enregistrer votre application, vous devez obtenir l'ID de déploiement de cette application spécifique.

  1. Cliquez sur Déployer > Nouveau déploiement.
  2. Sous Sélectionner un type, cliquez sur Module complémentaire.
  3. Renseignez les options, puis cliquez sur Déployer.
  4. Sous "Deployment ID" (ID de déploiement), cliquez sur Copy (Copier).

Consultez le guide de gestion des versions pour connaître les pratiques recommandées d'utilisation des ID de déploiement.

Étape 4: Enregistrez l'application

Vous pouvez enregistrer votre application depuis la console développeur de Google Cloud. Sur l'écran d'enregistrement de l'application, saisissez son nom, son URL, ainsi que sa description. Pour les tests, vous pouvez activer les options "L'application peut être envoyée directement par SMS" et "L'application fonctionne dans les espaces avec plusieurs utilisateurs". Sous "Paramètres de connexion", sélectionnez "Apps Script" et collez l'ID de déploiement que vous avez copié à l'étape précédente.

Étape 5: Testez votre application

Pour tester votre application, vous pouvez lui envoyer un MP ou la @mentionner dans un espace. Lorsque vous lui parlez, il répond à la réponse Message à l'étape 2. Et voilà !

Concepts de l'application Apps Script

Événements

Apps Script est compatible avec plusieurs fonctions de gestionnaire d'événements que votre application peut mettre en œuvre. Chaque fonction gère un type d'événement différent, et chaque fonction reçoit un seul argument e, qui est un objet Événement.

onAddToSpace(e)
Cette fonction est exécutée lorsque votre application est ajoutée à un espace. Votre application peut être ajoutée directement à l'espace ou par le biais d'une @mention. Dans le second, l'événement e comporte également une propriété message. Cette fonction doit renvoyer un objet Message, qui est généralement un message de bienvenue pour informer les utilisateurs finaux de l'existence de votre application ou d'une réponse à une @mention.
onMessage(e)
Cette fonction est appelée lorsque votre application se trouve déjà dans l'espace et que l'utilisateur la @mentionne. Elle doit renvoyer un objet Message contenant la réponse de votre application.
onRemoveFromSpace(e)
Cette fonction est appelée lorsque l'utilisateur supprime votre application de sa liste de MP ou d'un espace. La valeur renvoyée par cette fonction est ignorée, car votre application a été supprimée et ne peut plus publier de messages.

L'exemple suivant implémente onAddToSpace et onRemoveFromSpace:

// onAddToSpace() is invoked when the app is added to a space or when
// a user initiates / re-initiates a direct message with the app.
function onAddToSpace(e) {
  if (!e.space.singleUserBotDm) {
    return { 'text': 'Thanks for adding me to "' +
        (e.space.displayName ? e.space.displayName : "this chat") + '"!' };
  } else {
    return { 'text': 'Thanks for adding me to a DM!' };
  }
}
// onRemoveFromSpace() is invoked when app is removed from a space
// or when a user removes a direct message with the app.
function onRemoveFromSpace(e) {}

Notez que e.space.displayName peut ne pas être présent dans les messages privés entre humains.

Fiches interactives

Comme d'autres applications, les applications Apps Script peuvent afficher des fiches interactives. Pour savoir comment rendre les fiches interactives, consultez la documentation sur les fiches interactives. La principale différence pour les applications Apps Script réside dans le fait qu'elles peuvent spécifier une méthode spécifique à appeler lorsque l'événement onClick est déclenché en utilisant les paires clé/valeur action.actionMethodName et action.parameters en tant que paramètres de méthode.

Autorisation

Les applications Apps Script qui accèdent à des ressources protégées doivent demander aux utilisateurs d'autoriser cet accès la première fois qu'ils s'exécutent pour chaque utilisateur. Cette opération ne nécessite aucune action de votre part, mais sachez que les utilisateurs peuvent voir une boîte de dialogue d'autorisation la première fois qu'ils utilisent votre application.

Apps Script gère l'autorisation au niveau du script. Les applications nécessitant une autorisation ne peuvent effectuer aucune action tant que l'utilisateur final n'a pas autorisé l'application. Si vous souhaitez qu'un message de bienvenue s'affiche lorsqu'une application n'a pas été autorisée et qu'elle est directement ajoutée à un espace, vous pouvez spécifier un message de remplacement dans le fichier manifeste. Si votre application nécessite une logique d'initialisation, vous devrez peut-être dupliquer cette logique dans l'action onMessage. Exemple :

function onMessage(event) {
  var userProperties = PropertiesService.getUserProperties();
  if (!userProperties.getProperty('initialized')) {
    // handle the onAddToSpace initialization logic here.
    ...
    userProperties.setProperties({initialized: 'true'});
  }
  // Handle normal onMessage logic.
  ...
}

Messages asynchrones

Certaines applications peuvent avoir besoin d'envoyer des messages dans Google Chat à partir d'un déclencheur externe, tel qu'un déclencheur basé sur l'heure dans Apps Script.

Nous prévoyons d'intégrer de manière native l'API Google Chat dans Apps Script pour ce cas d'utilisation. En attendant, le seul moyen d'y parvenir consiste à utiliser l'API HTTP externe (consultez la documentation). Cela nécessite l'utilisation d'un compte de service Cloud (consultez la documentation) via la bibliothèque OAuth2 pour Apps Script.

L'exemple complet d'application suivant qui publie un message toutes les minutes dans chaque espace où il se trouve:

// Example app for Google Chat that demonstrates app-initiated messages
// by spamming the user every minute.
//
// This app makes use of the Apps Script OAuth2 library at:
//     https://github.com/googlesamples/apps-script-oauth2
//
// Follow the instructions there to add the library to your script.

// When added to a space, we store the space's ID in ScriptProperties.
function onAddToSpace(e) {
  PropertiesService.getScriptProperties()
      .setProperty(e.space.name, '');
  return {
    'text': 'Hi! I\'ll post a message here every minute. ' +
            'Please remove me after testing or I\'ll keep spamming you!'
  };
}

// When removed from a space, we remove the space's ID from ScriptProperties.
function onRemoveFromSpace(e) {
  PropertiesService.getScriptProperties()
      .deleteProperty(e.space.name);
}

// Add a trigger that invokes this function every minute via the
// "Edit > Current Project's Triggers" menu. When it runs, it will
// post in each space the app was added to.
function onTrigger() {
  var spaceIds = PropertiesService.getScriptProperties()
      .getKeys();
  var message = { 'text': 'Hi! It\'s now ' + (new Date()) };
  for (var i = 0; i < spaceIds.length; ++i) {
    postMessage(spaceIds[i], message);
  }
}
var SCOPE = 'https://www.googleapis.com/auth/chat.bot';
// The values below are copied from the JSON file downloaded upon
// service account creation.
// For SERVICE_ACCOUNT_PRIVATE_KEY, remember to include the BEGIN and END lines of the private key
var SERVICE_ACCOUNT_PRIVATE_KEY = '...';
var SERVICE_ACCOUNT_EMAIL = 'service-account@project-id.iam.gserviceaccount.com';

// Posts a message into the given space ID via the API, using
// service account authentication.
function postMessage(spaceId, message) {
  var service = OAuth2.createService('chat')
      .setTokenUrl('https://accounts.google.com/o/oauth2/token')
      .setPrivateKey(SERVICE_ACCOUNT_PRIVATE_KEY)
      .setClientId(SERVICE_ACCOUNT_EMAIL)
      .setPropertyStore(PropertiesService.getUserProperties())
      .setScope(SCOPE);
  if (!service.hasAccess()) {
    Logger.log('Authentication error: %s', service.getLastError());
    return;
  }
  var url = 'https://chat.googleapis.com/v1/' + spaceId + '/messages';
  UrlFetchApp.fetch(url, {
    method: 'post',
    headers: { 'Authorization': 'Bearer ' + service.getAccessToken() },
    contentType: 'application/json',
    payload: JSON.stringify(message),
  });
}

Fichier manifeste

Voici un exemple de fichier manifeste Apps Script qui doit accompagner votre script. Si vous n'avez pas démarré votre projet à partir du modèle d'application Google Chat, vous devez modifier le fichier manifeste pour y ajouter l'objet "chat": {}.

{
  "timeZone": "America/Los_Angeles",
  "dependencies": {},
  "chat": {
    "addToSpaceFallbackMessage": "Thank you for adding me!"
  },
  "exceptionLogging": "STACKDRIVER"
}

Un utilisateur peut ajouter votre application à un espace avant d'autoriser cette dernière. Dans ce cas, votre application ne peut pas répondre à l'événement "ajouter à l'espace". Si cela se produit, vous pouvez afficher un message de bienvenue à l'aide du champ addToSpaceFallbackMessage.

Le fichier manifeste est nommé appsscript.json et fait partie de votre projet Apps Script. Pour afficher le fichier manifeste dans l'éditeur Apps Script, sélectionnez Afficher > Afficher le fichier manifeste.