Cette page a été traduite par l'API Cloud Translation.

Recevoir des événements d'interaction et y répondre

Cette page explique comment votre application Google Chat peut recevoir des interactions utilisateur et y répondre, également appelées événements d'interaction d'application Google Chat.

Cette page explique comment effectuer les opérations suivantes :

Configurez votre application Chat pour qu'elle reçoive les événements d'interaction.
Traitez l'événement d'interaction sur votre infrastructure.
Si nécessaire, répondez aux événements d'interaction.

Prérequis

Compte Google Workspace Business ou Enterprise ayant accès à Google Chat.
Créez un projet Google Cloud.
Configurez l'écran de consentement OAuth.
Activez l'API Google Chat.

Types d'événements d'interaction

Un événement d'interaction avec une application Google Chat représente toute action entreprise par un utilisateur pour appeler une application Chat ou interagir avec elle, par exemple en mentionnant une application Chat ou en l'ajoutant à un espace.

Lorsque les utilisateurs interagissent avec une application Chat, Google Chat envoie à l'application Chat un événement d'interaction, représenté par un type Event dans l'API Chat. L'application Chat peut utiliser l'événement pour traiter l'interaction et, éventuellement, répondre par un message.

Pour chaque type d'interaction utilisateur, Google Chat envoie un type d'événement d'interaction différent, ce qui aide votre application Chat à gérer chaque type d'événement en conséquence. Le type d'événement d'interaction est représenté à l'aide de l'objet eventType.

Par exemple, Google Chat utilise le type d'événement ADDED_TO_SPACE pour toute interaction au cours de laquelle un utilisateur ajoute l'application Chat à un espace. L'application Chat peut ainsi répondre immédiatement par un message de bienvenue dans l'espace.

L'application de chat publie un message de bienvenue. — **Figure 1** : Lorsqu'un utilisateur ajoute une application Chat à un espace, l'application Chat reçoit un événement d'interaction `ADDED_TO_SPACE` que l'application Chat gère pour envoyer un message de bienvenue dans l'espace.

Le tableau suivant présente les interactions utilisateur courantes, le type d'événement d'interaction que reçoivent les applications Chat et la façon dont les applications Chat répondent généralement :

Interaction de l'utilisateur	`eventType`	Réponse type d'une application Chat
Un utilisateur envoie un message à une application Chat, par exemple en @mentionnant l'application Chat ou en utilisant une commande à barre oblique.	`MESSAGE`	L'application Chat répond en fonction du contenu du message. Par exemple, une application Chat répond à la commande à barre oblique `/about` par un message expliquant les tâches que l'application Chat peut effectuer.
Un utilisateur ajoute une application Chat à un espace.	`ADDED_TO_SPACE`	L'application Chat envoie un message d'accueil qui explique ce qu'elle fait et comment les utilisateurs de l'espace peuvent interagir avec elle.
Un utilisateur supprime une application Chat d'un espace.	`REMOVED_FROM_SPACE`	L'application Chat supprime toutes les notifications entrantes configurées pour l'espace (par exemple, la suppression d'un webhook) et libère de l'espace de stockage interne.
Un utilisateur clique sur un bouton d'une fiche dans un message, une boîte de dialogue ou une page d'accueil d'une application Chat.	`CARD_CLICKED`	L'application Chat traite et stocke les données envoyées par l'utilisateur, ou renvoie une autre fiche.
Un utilisateur ouvre la page d'accueil de l'application Chat en cliquant sur l'onglet Accueil dans un message privé.	`APP_HOME`	L'application Chat renvoie une fiche statique ou interactive depuis la page d'accueil.
Un utilisateur envoie un formulaire depuis la page d'accueil de l'application Chat.	`SUBMIT_FORM`	L'application Chat traite et stocke les données envoyées par l'utilisateur, ou renvoie une autre fiche.
Un utilisateur appelle une commande à l'aide d'une commande rapide.	`APP_COMMAND`	L'application Chat répond en fonction de la commande invoquée. Par exemple, une application Chat répond à la commande About par un message expliquant les tâches qu'elle peut effectuer.

Pour afficher tous les événements d'interaction compatibles, consultez la documentation de référence sur EventType.

Événements d'interaction provenant des boîtes de dialogue

Si votre application Chat ouvre des boîtes de dialogue, l'événement d'interaction contient les informations supplémentaires suivantes que vous pouvez utiliser pour traiter une réponse :

La valeur de isDialogEvent est définie sur true.
DialogEventType précise si l'interaction déclenche l'ouverture d'une boîte de dialogue, envoie des informations à partir d'une boîte de dialogue ou ferme une boîte de dialogue.

Le tableau suivant présente les interactions courantes avec les boîtes de dialogue, les types d'événements de boîte de dialogue correspondants et une description de la façon dont les applications Chat répondent généralement :

Interaction de l'utilisateur avec une boîte de dialogue	Type d'événement de boîte de dialogue	Réponse type
Un utilisateur déclenche une demande de boîte de dialogue. Par exemple, ils utilisent une commande à barre oblique ou cliquent sur un bouton dans un message.	`REQUEST_DIALOG`	L'application Chat ouvre la boîte de dialogue.
Un utilisateur envoie des informations dans la boîte de dialogue en cliquant sur un bouton.	`SUBMIT_DIALOG`	L'application Chat accède à une autre boîte de dialogue ou la ferme pour terminer l'interaction.
Un utilisateur quitte ou ferme la boîte de dialogue avant d'envoyer des informations.	`CANCEL_DIALOG`	L'application Chat peut éventuellement répondre par un nouveau message, ou modifier le message ou la fiche à partir desquels l'utilisateur a ouvert la boîte de dialogue.

Pour en savoir plus, consultez Ouvrir des boîtes de dialogue interactives.

Recevoir les événements d'interaction de l'application Chat

Cette section explique comment recevoir et traiter les événements d'interaction pour votre application de chat.

Configurer votre application Chat pour recevoir des événements d'interaction

Toutes les applications Chat ne sont pas interactives. Par exemple, les webhooks entrants ne peuvent envoyer que des messages sortants et ne peuvent pas répondre aux utilisateurs. Si vous créez une application Chat interactive, vous devez choisir un point de terminaison qui permet à votre application Chat de recevoir, de traiter et de répondre aux événements d'interaction. Pour en savoir plus sur la conception de votre application Chat, consultez Architectures d'implémentation des applications Chat.

Pour chacune des fonctionnalités interactives que vous souhaitez créer, vous devez mettre à jour votre configuration dans l'API Chat afin que Google Chat puisse envoyer les événements d'interaction associés à votre application Chat :

Dans la console Google Cloud, accédez à la page de l'API Chat, puis cliquez sur la page Configuration :

Accéder à la page de configuration de l'API Chat

Sous Fonctionnalités interactives, examinez les paramètres et mettez-les à jour en fonction des fonctionnalités que vous souhaitez créer :

Champ	Description
Fonctionnalité	Obligatoire. Ensemble de champs qui déterminent comment une application Chat peut interagir avec les utilisateurs. Par défaut, les utilisateurs peuvent trouver l'application Chat et lui envoyer un message privé directement dans Google Chat. Rejoindre des espaces et des conversations de groupe : les utilisateurs peuvent ajouter l'application Chat à des espaces et des conversations de groupe.
Paramètres de connexion	Obligatoire. Point de terminaison de l'application Chat, qui est l'un des suivants : URL du point de terminaison HTTP : point de terminaison HTTPS qui héberge l'implémentation de l'application Chat. Apps Script : ID de déploiement d'un projet Apps Script qui implémente une application Chat. Nom du sujet Cloud Pub/Sub : sujet Pub/Sub auquel l'application Chat s'abonne en tant que point de terminaison. Dialogflow : enregistre l'application Chat avec une intégration Dialogflow. Pour en savoir plus, consultez Créer une application Google Chat Dialogflow qui comprend le langage naturel.
Commandes	Facultatif. Commandes à barre oblique et commandes rapides pour l'application Chat. Les commandes permettent aux utilisateurs de demander une action ou d'utiliser une fonctionnalité spécifique de votre application Chat. Pour en savoir plus, consultez Répondre aux commandes de l'application Google Chat.
Aperçus de liens	Facultatif. Formats d'URL reconnus par l'application Chat qui peuvent fournir un contenu supplémentaire lorsque les utilisateurs envoient des liens. Pour en savoir plus, consultez Liens d'aperçu.
Visibilité	Facultatif. Jusqu'à cinq personnes ou un ou plusieurs groupes Google pouvant afficher et installer votre application Chat. Utilisez ce champ pour tester votre application Chat ou la partager avec votre équipe. Pour en savoir plus, consultez Tester les fonctionnalités interactives.

Cliquez sur Enregistrer. Lorsque vous enregistrez la configuration de l'application Chat, celle-ci est disponible pour les utilisateurs spécifiés de votre organisation Google Workspace.

Votre application Chat est maintenant configurée pour recevoir des événements d'interaction de Google Chat.

Gérer les nouvelles tentatives d'appels HTTP à votre service

Si une requête HTTPS envoyée à votre service échoue (par exemple, en cas de délai d'attente, de défaillance réseau temporaire ou de code d'état HTTPS non 2xx), Google Chat peut réessayer de l'envoyer plusieurs fois en quelques minutes (mais cela n'est pas garanti). Par conséquent, une application Chat peut recevoir le même message plusieurs fois dans certaines situations. Si la requête aboutit, mais renvoie une charge utile de message non valide, Google Chat ne la relance pas.

Traiter les événements d'interaction ou y répondre

Cette section explique comment les applications Google Chat peuvent traiter les événements d'interaction et y répondre.

Une fois que votre application Chat a reçu un événement d'interaction de Google Chat, elle peut répondre de différentes manières. Dans de nombreux cas, les applications Chat interactives répondent à l'utilisateur par un message. L'application Google Chat peut également rechercher des informations à partir d'une source de données, enregistrer les informations sur l'événement d'interaction ou effectuer à peu près n'importe quelle autre tâche. Ce comportement de traitement définit essentiellement l'application Google Chat.

Pour répondre de manière synchrone, une application Chat doit répondre dans les 30 secondes, et la réponse doit être publiée dans l'espace où l'interaction a eu lieu. Sinon, l'application Chat peut répondre de manière asynchrone.

Pour chaque événement d'interaction, les applications Chat reçoivent un corps de requête, qui correspond à la charge utile JSON représentant l'événement. Vous pouvez utiliser ces informations pour traiter une réponse. Pour obtenir des exemples de charges utiles d'événements, consultez Types d'événements d'interaction avec une application Chat.

Le diagramme suivant montre comment une application Google Chat traite ou répond généralement à différents types d'événements d'interaction :

Architecture de la façon dont les applications Google Chat traitent les événements d'interaction.

Réponse en temps réel

Les événements d'interaction permettent aux applications Chat de répondre en temps réel ou de manière synchrone. Les réponses synchrones ne nécessitent pas d'authentification.

Pour répondre en temps réel, l'application Chat doit renvoyer un objet Message. Pour répondre avec un message dans l'espace, l'objet Message peut contenir des objets text, cardsV2 et accessoryWidgets. Pour l'utiliser avec d'autres types de réponses, consultez les guides suivants :

Répondre par un message

Dans cet exemple, votre application Chat crée et envoie un message texte chaque fois qu'elle est ajoutée à un espace. Pour découvrir les bonnes pratiques concernant l'intégration des utilisateurs, consultez Présenter votre application Chat aux utilisateurs.

Pour envoyer un message lorsque l'utilisateur ajoute votre application Chat à un espace, votre application Chat répond à un ADDED_TO_SPACE événement d'interaction. Pour répondre aux événements d'interaction ADDED_TO_SPACE avec un message texte, utilisez le code suivant :

Node.js

/**
 * Sends an onboarding message when the Chat app is added to a space.
 *
 * @param {Object} req The event object from Chat API.
 * @param {Object} res The response object from the Chat app. An onboarding message that
 * introduces the app and helps people get started with it.
 */
exports.onMessage = function onMessage(req, res) {
  if (req.method === 'GET' || !req.body.message) {
    res.send(
      'Hello! This function is meant to be used in a Google Chat space.');
  }

  // Send an onboarding message when added to a Chat space
  if (req.body.type === 'ADDED_TO_SPACE') {
    res.json({
      'text': 'Hi, Cymbal at your service. I help you manage your calendar
      from Google Chat. Take a look at your schedule today by typing
      `/checkCalendar`, or schedule a meeting with `/scheduleMeeting`. To
      learn what else I can do, type `/help`.'
    });
  }
};

Apps Script

/**
 * Sends an onboarding message when the Chat app is added to a space.
 *
 * @param {Object} event The event object from Chat API.
 * @return {Object} Response from the Chat app. An onboarding message that
 * introduces the app and helps people get started with it.
 */
function onAddToSpace(event) {

  return {
    'text': 'Hi, Cymbal at your service. I help you manage your calendar
    from Google Chat. Take a look at your schedule today by typing
    `/checkCalendar`, or schedule a meeting with `/scheduleMeeting`. To learn
    what else I can do, type `/help`.'
  }
}

L'exemple de code renvoie le message texte suivant :

Exemple de message d'intégration.

Répondre de manière asynchrone

Parfois, les applications Chat doivent répondre à un événement d'interaction après 30 secondes ou effectuer des tâches en dehors de l'espace où l'événement d'interaction a été généré. Par exemple, une application de chat peut avoir besoin de répondre à l'utilisateur après avoir terminé une tâche de longue durée. Dans ce cas, les applications Chat peuvent répondre de manière asynchrone en appelant l'API Google Chat.

Pour créer un message à l'aide de l'API Chat, consultez Créer un message. Pour obtenir des guides sur l'utilisation d'autres méthodes de l'API Chat, consultez la présentation de l'API Chat.