Recevoir des interactions avec l'application Google Chat et y répondre

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

Un événement d'interaction dans une application Google Chat représente toute action effectuée par un utilisateur pour appeler une application Chat ou interagir avec celle-ci, par exemple en @mentionnant une application Chat ou en l'ajoutant à un espace. Lorsque les utilisateurs interagissent avec une application Chat, Google Chat envoie un événement d'interaction à cette application. L'application Chat peut utiliser l'événement pour traiter l'interaction et créer une réponse.

Par exemple, les applications Chat utilisent des événements d'interaction pour effectuer les opérations suivantes:

Exemple d'événement d'interaction Réponse type d'une application Chat
Un utilisateur appelle une application Chat en la mentionnant ou en utilisant une commande à barre oblique. L'application Chat traite ce que dit le message pour créer un message. Par exemple, une application Chat répond à la commande /about par un message expliquant les tâches qu'elle peut effectuer.
Un utilisateur ajoute une application Chat à un espace. 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. L'application Chat supprime toutes les notifications entrantes configurées pour l'espace (par exemple, la suppression d'un webhook) et efface toute mémoire de stockage interne.
Un utilisateur clique sur un bouton d'une fiche ou d'une boîte de dialogue envoyée par l'application Chat. L'application Chat traite et stocke toutes les données envoyées par l'utilisateur, ou renvoie une autre carte ou une autre boîte de dialogue.

Pour chaque type d'interaction utilisateur, Google Chat envoie un type d'événement d'interaction différent. Par exemple, Google Chat utilise le type d'événement MESSAGE pour toute interaction où un utilisateur appelle l'application Chat dans un message. Pour en savoir plus, consultez Types d'événements d'interaction avec les applications Google Chat.

Cette page explique comment effectuer les opérations suivantes :

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

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 les événements d'interaction

Les applications Chat ne sont pas toutes interactives. Par exemple, les webhooks entrants peuvent uniquement envoyer 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 lui permet de recevoir, traiter et répondre aux événements d'interaction. Pour en savoir plus sur la conception de votre application Chat, consultez la page Architectures d'implémentation des applications Chat.

Si vous avez créé une application Chat interactive, vous devez configurer l'API Google Chat pour que Google Chat puisse vous envoyer des événements d'interaction:

  1. Dans la console Google Cloud, ouvrez la page de l'API Google Chat:

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

  2. Cliquez sur l'onglet Configuration.
  3. Dans la section Fonctionnalités interactives, activez l'option Activer les fonctionnalités interactives.
  4. Dans Fonctionnalité, cochez l'une des cases suivantes ou les deux :
    1. Recevoir des messages privés : permet aux utilisateurs d'interagir avec votre application Chat dans des espaces de messages privés (MP). Votre application Chat reçoit des événements d'interaction chaque fois qu'un utilisateur envoie un message dans l'espace MP.
    2. Rejoindre des espaces et des conversations de groupe: permet aux utilisateurs d'ajouter et de supprimer votre application Chat dans les espaces comptant plusieurs personnes. Votre application Chat reçoit des événements d'interaction chaque fois qu'elle est ajoutée ou supprimée de l'espace, et chaque fois qu'un utilisateur @mentionne ou utilise une commande à barre oblique dans l'espace.
  5. Dans Paramètres de connexion, indiquez où Google Chat envoie les événements d'interaction avec les applications Chat.
  6. Facultatif: Dans Commandes à barre oblique, ajoutez et configurez une ou plusieurs commandes à barre oblique. Pour en savoir plus, consultez la section Configurer des commandes à barre oblique.
  7. Facultatif: Dans Aperçus des liens, ajoutez et configurez un ou plusieurs formats d'URL prévisualisés par votre application Chat. Pour en savoir plus, consultez Prévisualiser les liens.
  8. Cliquez sur Enregistrer.

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

Authentifier les requêtes provenant de Google Chat

Pour les applications basées sur des points de terminaison HTTP, cette section explique comment vérifier que les requêtes adressées à votre point de terminaison proviennent de Google Chat.

Pour envoyer des événements d'interaction au point de terminaison de votre application Chat, Google envoie des requêtes à votre service. Pour vérifier que la requête provient de Google, Google Chat inclut un jeton de support dans l'en-tête Authorization de chaque requête HTTPS adressée à votre point de terminaison. Exemple :

POST
Host: yourappurl.com
Authorization: Bearer AbCdEf123456
Content-Type: application/json
User-Agent: Google-Dynamite

La chaîne AbCdEf123456 dans l'exemple ci-dessus est le jeton d'autorisation du support. Il s'agit d'un jeton cryptographique produit par Google. Vous pouvez vérifier votre jeton de support à l'aide d'une bibliothèque cliente Open Source de l'API Google:

Pour les jetons de support envoyés dans les requêtes Google Chat, l'émetteur est chat@system.gserviceaccount.com, et le champ audience est défini sur le numéro du projet Google Cloud que vous avez utilisé pour créer votre application Chat. Par exemple, si le numéro de projet Cloud de votre application Chat est 1234567890, le champ audience du jeton de support est 1234567890.

Si le jeton n'est pas validé pour l'application Chat, votre service doit répondre à la requête avec un code de réponse HTTPS 401 (Unauthorized).

Java

import java.io.IOException;
import java.security.GeneralSecurityException;
import java.util.Collections;

import com.google.api.client.googleapis.auth.oauth2.GoogleIdToken;
import com.google.api.client.googleapis.auth.oauth2.GoogleIdTokenVerifier;
import com.google.api.client.googleapis.auth.oauth2.GooglePublicKeysManager;
import com.google.api.client.http.apache.ApacheHttpTransport;
import com.google.api.client.json.JsonFactory;
import com.google.api.client.json.jackson.JacksonFactory;

/** Tool for verifying JWT Tokens for Apps in Google Chat. */
public class JWTVerify {
  // Bearer Tokens received by apps will always specify this issuer.
  static String CHAT_ISSUER = "chat@system.gserviceaccount.com";

  // Url to obtain the public certificate for the issuer.
  static String PUBLIC_CERT_URL_PREFIX =
      "https://www.googleapis.com/service_accounts/v1/metadata/x509/";

  // Intended audience of the token, which is the project number of the app.
  static String AUDIENCE = "1234567890";

  // Get this value from the request's Authorization HTTPS header.
  // For example, for "Authorization: Bearer AbCdEf123456" use "AbCdEf123456"
  static String BEARER_TOKEN = "AbCdEf123456";

  public static void main(String[] args) throws GeneralSecurityException, IOException {
    JsonFactory factory = new JacksonFactory();

    GooglePublicKeysManager.Builder keyManagerBuilder =
        new GooglePublicKeysManager.Builder(new ApacheHttpTransport(), factory);

    String certUrl = PUBLIC_CERT_URL_PREFIX + CHAT_ISSUER;
    keyManagerBuilder.setPublicCertsEncodedUrl(certUrl);

    GoogleIdTokenVerifier.Builder verifierBuilder =
        new GoogleIdTokenVerifier.Builder(keyManagerBuilder.build());
    verifierBuilder.setIssuer(CHAT_ISSUER);
    GoogleIdTokenVerifier verifier = verifierBuilder.build();

    GoogleIdToken idToken = GoogleIdToken.parse(factory, BEARER_TOKEN);
    if (idToken == null) {
      System.out.println("Token cannot be parsed");
      System.exit(-1);
    }

    // Verify valid token, signed by CHAT_ISSUER.
    if (!verifier.verify(idToken)
        || !idToken.verifyAudience(Collections.singletonList(AUDIENCE))
        || !idToken.verifyIssuer(CHAT_ISSUER)) {
      System.out.println("Invalid token");
      System.exit(-1);
    }

    // Token originates from Google and is targeted to a specific client.
    System.out.println("The token is valid");
  }
}

Python

import sys

from oauth2client import client

# Bearer Tokens received by apps will always specify this issuer.
CHAT_ISSUER = 'chat@system.gserviceaccount.com'

# Url to obtain the public certificate for the issuer.
PUBLIC_CERT_URL_PREFIX = 'https://www.googleapis.com/service_accounts/v1/metadata/x509/'

# Intended audience of the token, which will be the project number of the app.
AUDIENCE = '1234567890'

# Get this value from the request's Authorization HTTPS header.
# For example, for 'Authorization: Bearer AbCdEf123456' use 'AbCdEf123456'.
BEARER_TOKEN = 'AbCdEf123456'

try:
  # Verify valid token, signed by CHAT_ISSUER, intended for a third party.
  token = client.verify_id_token(
      BEARER_TOKEN, AUDIENCE, cert_uri=PUBLIC_CERT_URL_PREFIX + CHAT_ISSUER)

  if token['iss'] != CHAT_ISSUER:
    sys.exit('Invalid issuee')
except:
  sys.exit('Invalid token')

# Token originates from Google and is targeted to a specific client.
print 'The token is valid'

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

Si une requête HTTPS auprès de votre service échoue (par exemple, en cas d'expiration du délai, d'échec temporaire du réseau ou de code d'état HTTPS autre que 2xx), Google Chat peut réessayer la distribution 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 tente pas de la relancer.

traiter des é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.

Lorsque 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 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 les événements d'interaction ou presque. Ce comportement de traitement est essentiellement ce qui définit l'application Google Chat.

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énement, consultez la section Types d'événements d'interaction avec les applications Chat.

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

Architecture de la manière 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 créer des réponses synchrones à des événements d'interaction, consultez les guides suivants:

Pour répondre de manière synchrone, une application Chat doit répondre dans un délai de 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.

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 dans lequel 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 effectué 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.