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 de l'application Google Chat.

Cette page explique comment effectuer les opérations suivantes :

• Configurer votre application Chat pour qu'elle reçoive des événements d'interaction.
• Traiter l'événement d'interaction sur votre infrastructure.
• Le cas échéant, répondre aux événements d'interaction.

Prérequis

• Un compte Google Workspace Business ou Enterprise avec accès à Google Chat.
• Créez un projet Google Cloud.
• Configurez l'écran d'autorisation OAuth.
• Activez l'API Google Chat.

Types d'événements d'interaction

Un événement d'interaction de l'application Google Chat représente toute action qu'un utilisateur effectue pour appeler une application Chat ou interagir avec elle, par exemple en mentionnant une application Chat avec le symbole @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 Event type 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 permet à votre application Chat de gérer chaque type d'événement en conséquence. Le type d'événement d'interaction est représenté à l'aide de l' eventType objet.

Par exemple, Google Chat utilise le type d'événement ADDED_TO_SPACE pour toute interaction dans laquelle un utilisateur ajoute l' application Chat à un espace, afin que l' application Chat puisse immédiatement répondre par 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 les applications Chat répondent généralement :

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

É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 manière dont les applications Chat répondent généralement :

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

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

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

Configurer votre application Chat pour qu'elle reçoive 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 des événements d'interaction associés à votre application Chat :

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

2. 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 l'application Chat peut interagir avec les utilisateurs. Par défaut, les utilisateurs peuvent trouver l'application Chat et lui envoyer des messages 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 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. Modèles d'URL que l'application Chat reconnaît et pour lesquels elle fournit du contenu supplémentaire lorsque les utilisateurs envoient des liens. Pour en savoir plus, consultez Aperçu des liens.
   Visibilité	Facultatif. Jusqu'à cinq personnes, ou un ou plusieurs groupes Google qui peuvent afficher 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.

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

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

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

Si une requête HTTPS adressée à votre service échoue (par exemple, en cas de délai d'attente, de défaillance temporaire du réseau ou de code d'état HTTPS autre que 2xx), Google Chat peut réessayer la livraison 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 retente pas la requête.

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 reçoit un événement d'interaction de Google Chat, elle peut répondre de nombreuses 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 de l'événement d'interaction ou effectuer toute autre action. Ce comportement de traitement est essentiellement ce qui définit 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 de 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 :

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 Message objet. Pour répondre par un message dans l'espace, l'objet Message peut contenir text, cardsV2 et accessoryWidgets objets. Pour l'utiliser avec d'autres types de réponses, consultez les guides suivants :

• Ouvrir des boîtes de dialogue interactives
• Aperçu des liens
• Traiter les informations envoyées par les utilisateurs

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 d' intégration des utilisateurs, consultez Présenter votre application Chat aux utilisateurs.

Pour envoyer un message texte lorsqu'un 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 par un message texte, utilisez le code suivant :

/**
 * 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.
 */
exports.cymbalApp = function cymbalApp(req, res) {
  // 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`.'
    });
  }
};

from flask import Flask, request, json
app = Flask(__name__)

@app.route('/', methods=['POST'])
def cymbal_app():
  """Sends an onboarding message when the Chat app is added to a space.

  Returns:
    Mapping[str, Any]: The response object from the Chat app.
  """
  event = request.get_json()
  if event['type'] == 'ADDED_TO_SPACE':
    return json.jsonify({
      '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`.'
    })
  return json.jsonify({})

@SpringBootApplication
@RestController
public class App {
  public static void main(String[] args) {
    SpringApplication.run(App.class, args);
  }

  /*
   * Sends an onboarding message when the Chat app is added to a space.
   *
   * @return The response object from the Chat app.
   */
  @PostMapping("/")
  @ResponseBody
  public Message onEvent(@RequestBody JsonNode event) {
    switch (event.get("type").asText()) {
      case "ADDED_TO_SPACE":
        return new Message().setText(
          "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`.");
      default:
        return new Message();
    }
  }
}

/**
 * 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.
 */
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 :

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

Articles associés

• Envoyer un message
• Ouvrir des boîtes de dialogue interactives
• Aperçu des liens
• Lire les données de formulaire saisies par les utilisateurs sur les fiches
• Répondre aux commandes
• Créer une page d'accueil pour une application Chat
• Valider les requêtes de Chat
• Tester les fonctionnalités interactives des applications Google Chat