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

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 et y répondre, également appelés événements d'interaction avec l'application Google Chat.

Un événement d'interaction avec une application Google Chat représente toute action effectuée par un utilisateur pour appeler une application Chat ou interagir avec elle, par exemple @mentionner une application Chat ou l'ajouter à 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 l'une des opérations suivantes:

Exemple d'événement d'interaction	Réponse habituelle d'une application Chat
Un utilisateur appelle une application Chat en la mentionnant (@mention) 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'intégration 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 libère de la mémoire de stockage interne.
Un utilisateur clique sur le 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 différent d'événement d'interaction. 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 des é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 webhook 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 lui permet de recevoir, de traiter et d'y répondre des événements d'interaction. Pour en savoir plus sur la conception de votre application Chat, consultez la page Architectures d'implémentation d'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:

Dans la console Google Cloud, ouvrez la page API Google Chat:
Accéder à la page de l'API Google Chat
Cliquez sur l'onglet Configuration.
Dans la section Fonctionnalités interactives, activez l'option Activer les fonctionnalités interactives.
Dans Fonctionnalités, 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 des espaces comptant plus d'une personne. 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 que les utilisateurs mentionnent @ou utilisent une commande à barre oblique dans l'espace.
Dans Paramètres de connexion, indiquez où Google Chat envoie les événements d'interaction avec l'application Chat.
Facultatif: Dans les commandes à barre oblique, ajoutez et configurez une ou plusieurs commandes à barre oblique. Pour en savoir plus, consultez la section Configurer des commandes à barre oblique.
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.
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 de 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:

Java: https://github.com/google/google-api-java-client
Python: https://github.com/google/google-api-python-client
.NET: https://github.com/google/google-api-dotnet-client

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 ne se vérifie pas pour l'application Chat, votre service doit répondre à la requête avec le 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 vers votre service

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

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 de chat interactives répondent à l'utilisateur par un message. L'application Google Chat peut également rechercher certaines informations à partir d'une source de données, enregistrer les informations de l'événement d'interaction ou presque toute autre chose. 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 généralement différents types d'événements d'interaction ou y répond:

Architecture du traitement des événements d'interaction dans 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 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.