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

Recevoir des interactions utilisateur et y répondre

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

Cette page explique comment effectuer les opérations suivantes :

Configurez votre application Chat pour recevoir des événements d'interaction.
Traitez l'événement d'interaction sur votre infrastructure.
Le cas échéant, répondez aux événements d'interaction.

Prérequis

Une application Google Chat pour laquelle les fonctionnalités interactives sont activées. Pour créer une application Chat interactive, suivez l'un des guides de démarrage rapide suivants en fonction de l'architecture de l'application que vous souhaitez utiliser :

Service HTTP avec Google Cloud Functions
Google Apps Script
Google Cloud Dialogflow CX
Google Cloud Pub/Sub

Types d'événements d'interaction

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

Lorsque les utilisateurs interagissent avec une application Chat, Google Chat lui envoie 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, y 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 où un utilisateur ajoute l'application Chat à un espace, afin que l'application Chat puisse immédiatement répondre avec 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` qu'elle 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 les applications Chat reçoivent et la manière dont elles répondent généralement :

Interaction de l'utilisateur	`eventType`	Réponse typique d'une application Chat
Un utilisateur appelle une application Chat en la mentionnant 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 `/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'intégration qui explique son fonctionnement et la façon dont 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 tout espace de stockage interne.
Un utilisateur clique sur un bouton d'une fiche à partir d'un message, d'une boîte de dialogue ou de la page d'accueil de l'application Chat.	`CARD_CLICKED`	L'application Chat traite et stocke toutes les données envoyées par l'utilisateur, ou renvoie une autre carte.
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 à partir de la page d'accueil de l'application Chat.	`SUBMIT_FORM`	L'application Chat traite et stocke toutes les données envoyées par l'utilisateur, ou elle renvoie une autre carte.

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

Événements d'interaction à partir de 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.
Le DialogEventType indique 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 utilisateur avec une boîte de dialogue	Type d'événement de boîte de dialogue	Réponse type
Un utilisateur déclenche une requête de boîte de dialogue. Par exemple, ils utilisent une commande avec une 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 mettre à jour 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 avec l'application Chat

Cette section explique comment recevoir et traiter les événements d'interaction pour votre application 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 la section 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 des é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 Configuration :

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

Sous Fonctionnalités interactives, vérifiez 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 l'application Chat peut interagir avec les utilisateurs : Recevoir des messages privés : 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 peut être l'un des éléments 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 implémentant 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 à barre oblique	Facultatif. Commandes pouvant être proposées aux utilisateurs dans Google Chat Permet aux utilisateurs de voir les actions principales de votre application Chat dans Google Chat et de choisir une action spécifique avec laquelle ils souhaitent interagir. Pour en savoir plus, consultez Répondre aux commandes slash en tant qu'application Chat.
Aperçus de liens	Facultatif. Formats d'URL reconnus par l'application Chat et comprenant du contenu supplémentaire pour l'envoi de liens par les utilisateurs Pour en savoir plus, consultez Liens d'aperçu.
Visibilité	Facultatif. Jusqu'à cinq personnes ou un ou plusieurs groupes Google peuvent voir et installer votre application Chat. Utilisez ce champ pour tester votre application Chat ou pour 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, elle 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 à partir de Google Chat.

Gérer les tentatives d'appel HTTP à votre service

Si une requête HTTPS envoyée à votre service échoue (par exemple, en cas de délai avant expiration, de défaillance réseau temporaire ou de code d'état HTTPS autre que 2xx), Google Chat peut réessayer l'envoi plusieurs fois en quelques minutes (mais ce 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 ou répondre aux événements d'interaction

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

Une fois que votre application Chat reçoit un événement d'interaction de Google Chat, elle peut répondre de différentes manières. Dans de nombreux cas, les applications de chat interactives répondent à l'utilisateur par un message. L'application Google Chat peut également rechercher des informations dans une source de données, enregistrer les informations sur l'événement d'interaction ou presque tout autre chose. C'est ce comportement de traitement qui 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 s'est produite. 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 qui représente l'événement. Vous pouvez utiliser ces informations pour traiter une réponse. Pour obtenir des exemples de charges utiles d'événements, consultez la section Types d'événements d'interaction avec l'application Chat.

Le schéma suivant montre comment l'application Google Chat traite généralement différents types d'événements d'interaction ou y répond:

Architecture du traitement des événements d'interaction par les applications Google Chat.

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 en savoir plus sur les bonnes pratiques à suivre pour intégrer des utilisateurs, consultez la section Présenter votre application Chat aux utilisateurs.

Pour envoyer un message lorsqu'un utilisateur ajoute votre application Chat à un espace, votre application Chat répond à un événement d'interaction ADDED_TO_SPACE. Pour répondre aux événements d'interaction ADDED_TO_SPACE avec un message textuel, 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 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 au bout de 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 Chat peut devoir 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 la section 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.