Envoyer des messages à Google Chat avec des webhooks entrants

Les web webhooks entrants vous permettent d'envoyer des messages asynchrones dans Google Chat à partir d'applications autres que des applications de chat. Par exemple, vous pouvez configurer une application de surveillance pour avertir le personnel d'astreinte sur Google Chat lorsqu'un serveur tombe en panne.

Pour savoir comment envoyer, mettre à jour ou supprimer de manière asynchrone un message dans un espace Chat à l'aide d'une application Chat, consultez Créer, lire, mettre à jour ou supprimer des messages.

Architecture des webhooks entrants permettant d'envoyer des messages asynchrones à Google Chat.

Prérequis

Pour exécuter l'exemple de ce guide, vous avez besoin des éléments suivants:

Python

  • Python 3.10.7 ou version ultérieure
  • Un accès à Internet et à un navigateur Web
  • Un compte Google Workspace avec accès à Google Chat
  • Espace Google Chat existant.
  • La bibliothèque httplib2 Si nécessaire, exécutez la commande d'interface de ligne de commande (CLI) suivante pour installer la bibliothèque à l'aide de pip:

    pip install httplib2
    

Node.js

Apps Script

Java

Créer un webhook

Pour créer un webhook, enregistrez-le dans l'espace Google Chat où vous souhaitez recevoir des messages, puis rédigez un script qui en envoie.

Étape 1: Enregistrez le webhook entrant

  1. Dans un navigateur Web, ouvrez Google Chat.
  2. Accédez à l'espace auquel vous souhaitez ajouter un webhook.
  3. En haut, à côté du titre de l'espace, cliquez sur la flèche vers le bas > Applications et intégrations.
  4. Cliquez sur Gérer les webhooks.
  5. Si cet espace contient déjà d'autres webhooks, cliquez sur Ajouter. Sinon, ignorez cette étape.
  6. Dans le champ Nom, saisissez "quickstart Webhook".
  7. Dans le champ URL de l'avatar, saisissez https://developers.google.com/chat/images/chat-product-icon.png.
  8. Cliquez sur ENREGISTRER.
  9. Pour copier l'URL complète du webhook, cliquez sur Copier.
  10. Cliquez en dehors de la boîte de dialogue pour fermer la boîte de dialogue des webhooks entrants.

Étape 2: Écrivez le script webhook

L'exemple de script de webhook publie un message dans l'espace dans lequel le webhook est enregistré. Il envoie une requête create message à l'URL de webhook. L'API Google Chat répond par une instance de Message.

Choisissez un langage ci-dessous pour obtenir des instructions spécifiques sur la création du script webhook:

Python

  1. Dans votre répertoire de travail, créez un fichier nommé quickstart.py.

  2. Dans quickstart.py, copiez et collez le code suivant:

    python/webhook/quickstart.py
    from json import dumps
    
    from httplib2 import Http
    
    
    def main():
        """Hangouts Chat incoming webhook quickstart."""
        url = 'https://chat.googleapis.com/v1/spaces/7D8la4AAAAE/messages?key=' \
              'AIzaSyDdI0hCZtE6vySjMm-WEfRq3CPzqKqqsHI&token=' \
              'HulDviWFMz6R5FW-GwlO4INCW1cZGDDExuWVaEbbr_g%3D'
        bot_message = {
            'text': 'Hello from a Python script!'}
        message_headers = {'Content-Type': 'application/json; charset=UTF-8'}
        http_obj = Http()
        response = http_obj.request(
            uri=url,
            method='POST',
            headers=message_headers,
            body=dumps(bot_message),
        )
        print(response)
    
    
    if __name__ == '__main__':
        main()
  3. Remplacez la valeur de la variable url par l'URL de webhook que vous avez copiée à l'étape 1: Enregistrez le webhook entrant.

Node.js

  1. Dans votre répertoire de travail, créez un fichier nommé index.js.

  2. Dans index.js, copiez et collez le code suivant:

    node/webhook/index.js
    /**
     * Sends asynchronous message into Google Chat
     * @return{obj} response
     */
    function webhook() {
      const fetch = require('node-fetch');
      const webhookURL = 'https://chat.googleapis.com/v1/spaces/AAAAGCYeSRY/messages?key=AIzaSyDdI0hCZtE6vySjMm-WEfRq3CPzqKqqsHI&token=u9IG_MuTBXw-tnqupPrPNinY2spKFcRBDp6dSldGUAw%3D';
    
      const data = JSON.stringify({
        'text': 'Hello from a Node script!',
      });
      let resp;
      fetch(webhookURL, {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json; charset=UTF-8',
        },
        body: data,
      }).then((response) => {
        resp = response;
        console.log(response);
      });
      return resp;
    }
    
  3. Remplacez la valeur de la variable webhookURL par l'URL de webhook que vous avez copiée à l'étape 1: Enregistrez le webhook entrant.

Apps Script

  1. Accédez à la page Apps Script.

  2. Cliquez sur Nouveau projet.

  3. Copiez et collez le code suivant:

    apps-script/webhook/webhook.gs
    function webhook() {
      const url = "https://chat.googleapis.com/v1/spaces/AAAAGCYeSRY/messages";
      const options = {
        "method": "post",
        "headers": {
          "Content-Type": "application/json; charset=UTF-8"
        },
        "payload": JSON.stringify({
          "text": "Hello from Apps Script!"
        })
      };
      const response = UrlFetchApp.fetch(url, options);
      Logger.log(response);
    }
  4. Remplacez la valeur de la variable url par l'URL de webhook que vous avez copiée à l'étape 1: Enregistrez le webhook entrant.

Java

  1. Dans votre répertoire de travail, créez un fichier nommé pom.xml.

  2. Dans pom.xml, copiez et collez les éléments suivants:

    java/webhook/pom.xml
    <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
      <modelVersion>4.0.0</modelVersion>
    
      <groupId>com.google.hangouts.chat.webhook</groupId>
      <artifactId>java-webhook-app</artifactId>
      <version>0.1.0</version>
    
      <name>java-webhook-app</name>
      <url>https://github.com/googleworkspace/hangouts-chat-samples/tree/main/java/webhook</url>
    
      <properties>
        <maven.compiler.target>11</maven.compiler.target>
        <maven.compiler.source>11</maven.compiler.source>
      </properties>
    
      <dependencies>
        <dependency>
            <groupId>com.google.code.gson</groupId>
            <artifactId>gson</artifactId>
            <version>2.9.1</version>
        </dependency>
      </dependencies>
    
      <build>
        <pluginManagement>
          <plugins>
            <plugin>
              <artifactId>maven-compiler-plugin</artifactId>
              <version>3.8.0</version>
            </plugin>
          </plugins>
        </pluginManagement>
      </build>
    </project>
  3. Dans votre répertoire de travail, créez la structure de répertoire src/main/java.

  4. Dans le répertoire src/main/java, créez un fichier nommé App.java.

  5. Dans App.java, copiez et collez le code suivant:

    java/webhook/src/main/java/com/google/hangouts/chat/webhook/App.java
    import com.google.gson.Gson;
    import java.net.http.HttpClient;
    import java.net.http.HttpRequest;
    import java.net.http.HttpResponse;
    import java.util.Map;
    import java.net.URI;
    
    public class App {
      private static final String URL = "https://chat.googleapis.com/v1/spaces/AAAAGCYeSRY/messages";
      private static final Gson gson = new Gson();
      private static final HttpClient client = HttpClient.newHttpClient();
    
      public static void main(String[] args) throws Exception {
        String message = gson.toJson(Map.of("text", "Hello from Java!"));
    
        HttpRequest request = HttpRequest.newBuilder(
            URI.create(URL))
            .header("accept", "application/json; charset=UTF-8")
            .POST(HttpRequest.BodyPublishers.ofString(message))
            .build();
    
        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
    
        System.out.println(response.body());
      }
    }
  6. Remplacez la valeur de la variable URL par l'URL de webhook que vous avez copiée à l'étape 1: Enregistrez le webhook entrant.

Étape 3: Exécutez le script webhook

Exécutez l'exemple en exécutant la commande suivante depuis votre répertoire de travail dans la CLI:

Python

  python3 quickstart.py

Node.js

  node index.js

Apps Script

  • Cliquez sur Run (Exécuter).

Java

  mvn compile exec:java -Dexec.mainClass=App

Lorsque vous exécutez l'exemple de code, le webhook envoie un message à l'espace dans lequel vous l'avez enregistré.

Démarrer un fil de discussion ou y répondre

Vous pouvez démarrer un fil de discussion ou y répondre en ajoutant le paramètre threadKey à l'URL du webhook. Chaque threadKey est propre à l'application qui la définit. Si deux applications ou webhooks de chat différents définissent le même threadKey, deux threads différents démarrent.

Démarrer un fil de discussion

Pour publier le premier message d'un thread avec un webhook, ajoutez les paramètres threadKey et messageReplyOption à l'URL du webhook. Définissez threadKey sur une chaîne arbitraire, mais n'oubliez pas de l'indiquer : vous devrez la spécifier à nouveau pour publier une réponse au thread.

  https://chat.googleapis.com/v1/spaces/SPACE_ID/messages?threadKey=ARBITRARY_STRING&messageReplyOption=REPLY_MESSAGE_FALLBACK_TO_NEW_THREAD

Répondre à un fil de discussion

Pour envoyer un message à un thread de message existant, ajoutez les paramètres threadKey et messageReplyOption à l'URL du webhook définie sur la valeur utilisée pour démarrer le thread. Par exemple, l'envoi d'un message à l'URL suivante publie une réponse au fil de discussion où threadKey est MY-THREAD et messageReplyOption est REPLY_MESSAGE_FALLBACK_TO_NEW_THREAD:

  https://chat.googleapis.com/v1/spaces/SPACE_ID/messages?threadKey=MY-THREAD&messageReplyOption=REPLY_MESSAGE_FALLBACK_TO_NEW_THREAD

Limites et considérations

Lorsque vous configurez des webhooks, tenez compte des limites et des points suivants:

  • Chaque webhook ne fonctionne que dans l'espace Chat dans lequel il est enregistré.

  • Vous ne pouvez pas publier de webhooks sur Google Workspace Marketplace.

  • Les webhooks ne sont pas des conversations. Ils ne peuvent pas répondre aux messages des utilisateurs ni aux événements Google Chat, ni y répondre.

  • Si seules les unités organisationnelles de votre domaine ont activé les applications de chat, les webhooks entrants renvoient l'erreur suivante:

    {
      "error": {
        "code": 403,
        "message": "The caller does not have permission",
        "status": "PERMISSION_DENIED"
      }
    }
    
  • Les webhooks entrants fonctionnent dans les messages privés, mais uniquement lorsque les applications de chat sont activées pour tous les utilisateurs.

  • Icône pour gérer les webhooks Gérer les webhooks n'est disponible que depuis un navigateur Web. Les webhooks doivent donc être configurés à partir de l'application Web Chat. Vous ne pouvez pas configurer les webhooks depuis l'application mobile Chat.