Créer une application Google Chat en tant que webhook

Cette page explique comment configurer un webhook pour envoyer des messages asynchrones dans un espace Chat à l'aide de déclencheurs externes. Par exemple, vous pouvez configurer une application de surveillance pour avertir le personnel d'astreinte sur Chat lorsqu'un serveur tombe en panne. Pour envoyer un message synchrone avec une application Chat, consultez Envoyer un message.

Avec ce type de conception d'architecture, les utilisateurs ne peuvent pas interagir avec le webhook ni avec l'application externe connectée, car la communication est à sens unique. Les webhooks ne sont pas conversationnels. Ils ne peuvent pas répondre aux messages des utilisateurs ni aux événements d'interaction avec l'application Chat, ni en recevoir de ces derniers. Pour répondre aux messages, créez une application Chat au lieu d'un webhook.

Bien qu'un webhook ne soit pas techniquement une application Chat (les webhooks connectent des applications à l'aide de requêtes HTTP standards), cette page le désigne par le terme "application Chat" pour plus de simplicité. Chaque webhook ne fonctionne que dans l'espace Chat dans lequel il est enregistré. Les webhooks entrants fonctionnent dans les messages privés, mais uniquement lorsque les applications Chat sont activées pour tous les utilisateurs. Vous ne pouvez pas publier de webhooks sur Google Workspace Marketplace.

Le schéma suivant illustre l'architecture d'un webhook connecté à Chat:

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

Dans le schéma précédent, une application Chat comporte le flux d'informations suivant:

  1. La logique de l'application Chat reçoit des informations de services tiers externes, tels qu'un système de gestion de projet ou un outil de billetterie.
  2. La logique de l'application Chat est hébergée dans un système cloud ou sur site qui peut envoyer des messages à un espace Chat spécifique à l'aide d'une URL de webhook.
  3. Les utilisateurs peuvent recevoir des messages de l'application Chat dans cet espace Chat spécifique, mais ne peuvent pas interagir avec l'application Chat.

Prérequis

Python

  • Python 3.10.7 ou version ultérieure.
  • Un compte Google Workspace ayant accès à Chat
  • Un espace Chat existant
  • 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

Java

Apps Script ;

Créer un webhook

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

Enregistrer le webhook entrant

  1. Dans un navigateur, ouvrez Chat. Les webhooks ne sont pas configurables depuis l'application mobile Chat.
  2. Accédez à l'espace auquel vous souhaitez ajouter un webhook.
  3. À côté du titre de l'espace, cliquez sur la flèche de développement , puis sur Applis et intégrations.
  4. Cliquez sur Ajouter des webhooks.
  5. Dans le champ Name (Nom), saisissez Quickstart Webhook.
  6. Dans le champ URL de l'avatar, saisissez https://developers.google.com/chat/images/chat-product-icon.png.
  7. Cliquez sur Enregistrer.
  8. Pour copier l'URL de webhook, cliquez sur Plus, puis sur Copier le lien.

Écrire le script de webhook

L'exemple de script de webhook envoie un message à l'espace dans lequel le webhook est enregistré en envoyant une requête POST à l'URL de webhook. L'API Chat répond avec une instance de Message.

Sélectionnez un langage pour apprendre à créer un script de webhook:

Python

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

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

    python/webhook/quickstart.py
    from json import dumps
    from httplib2 import Http
    
    # Copy the webhook URL from the Chat space where the webhook is registered.
    # The values for SPACE_ID, KEY, and TOKEN are set by Chat, and are included
    # when you copy the webhook URL.
    
    def main():
        """Google Chat incoming webhook quickstart."""
        url = "https://chat.googleapis.com/v1/spaces/SPACE_ID/messages?key=KEY&token=TOKEN"
        app_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(app_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 lors de l'enregistrement du webhook.

Node.js

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

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

    nœud/webhook/index.js
    /**
     * Sends asynchronous message to Google Chat
     * @return {Object} response
     */
    async function webhook() {
      const url = "https://chat.googleapis.com/v1/spaces/SPACE_ID/messages"
      const res = await fetch(url, {
        method: "POST",
        headers: {"Content-Type": "application/json; charset=UTF-8"},
        body: JSON.stringify({text: "Hello from a Node script!"})
      });
      return await res.json();
    }
    
    webhook().then(res => console.log(res));
  3. Remplacez la valeur de la variable url par l'URL de webhook que vous avez copiée lors de l'enregistrement du webhook.

Java

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

  2. Dans pom.xml, copiez et collez le contenu suivant:

    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.chat.webhook</groupId>
      <artifactId>java-webhook-app</artifactId>
      <version>0.1.0</version>
    
      <name>java-webhook-app</name>
      <url>https://github.com/googleworkspace/google-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épertoires suivante : src/main/java.

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

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

    java/webhook/src/main/java/com/google/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 lors de l'enregistrement du webhook.

Apps Script ;

  1. Dans un navigateur, accédez à Apps Script.

  2. Cliquez sur New Project (Nouveau projet).

  3. Collez le code suivant :

    apps-script/webhook/webhook.gs
    function webhook() {
      const url = "https://chat.googleapis.com/v1/spaces/SPACE_ID/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);
      console.log(response);
    }
  4. Remplacez la valeur de la variable url par l'URL de webhook que vous avez copiée lors de l'enregistrement du webhook.

Exécuter le script de webhook

Dans une CLI, exécutez le script suivant:

Python

  python3 quickstart.py

Node.js

  node index.js

Java

  mvn compile exec:java -Dexec.mainClass=App

Apps Script ;

  • Cliquez sur Exécuter.

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

Démarrer une conversation ou y répondre

  1. Spécifiez spaces.messages.thread.threadKey dans le corps de la requête de message. Selon que vous démarrez un fil de discussion ou que vous y répondez, utilisez les valeurs suivantes pour threadKey:

    • Si vous démarrez un thread, définissez threadKey sur une chaîne arbitraire, mais notez cette valeur pour publier une réponse au fil de discussion.

    • Si vous répondez à un thread, spécifiez l'threadKey qui a été défini au démarrage du thread. Par exemple, pour publier une réponse dans le fil de discussion où le message initial utilisait MY-THREAD, définissez MY-THREAD.

  2. Définissez le comportement du thread si le threadKey spécifié est introuvable:

    • Répondez à un fil de discussion ou créez-en un. Ajoutez le paramètre messageReplyOption=REPLY_MESSAGE_FALLBACK_TO_NEW_THREAD à l'URL de webhook. La transmission de ce paramètre d'URL oblige Chat à rechercher un thread existant à l'aide du threadKey spécifié. Si l'une d'elles est trouvée, le message est publié en réponse à ce fil de discussion. Si ce n'est pas le cas, le message démarre un nouveau thread correspondant à ce threadKey.

    • Répondre à un fil de discussion ou ne rien faire. Ajoutez le paramètre messageReplyOption=REPLY_MESSAGE_OR_FAIL à l'URL de webhook. La transmission de ce paramètre d'URL oblige Chat à rechercher un thread existant à l'aide du threadKey spécifié. Si l'une d'elles est trouvée, le message est publié en réponse à ce fil de discussion. Si aucun résultat n'est détecté, le message n'est pas envoyé.

    Pour en savoir plus, consultez messageReplyOption.

L'exemple de code suivant démarre un fil de discussion ou y répond:

Python

python/webhook/thread-reply.py
from json import dumps
from httplib2 import Http

# Copy the webhook URL from the Chat space where the webhook is registered.
# The values for SPACE_ID, KEY, and TOKEN are set by Chat, and are included
# when you copy the webhook URL.
#
# Then, append messageReplyOption=REPLY_MESSAGE_FALLBACK_TO_NEW_THREAD to the
# webhook URL.


def main():
    """Google Chat incoming webhook that starts or replies to a message thread."""
    url = "https://chat.googleapis.com/v1/spaces/SPACE_ID/messages?key=KEY&token=TOKEN&messageReplyOption=REPLY_MESSAGE_FALLBACK_TO_NEW_THREAD"
    app_message = {
        "text": "Hello from a Python script!",
        # To start a thread, set threadKey to an arbitratry string.
        # To reply to a thread, specify that thread's threadKey value.
        "thread": {"threadKey": "THREAD_KEY_VALUE"},
    }
    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(app_message),
    )
    print(response)


if __name__ == "__main__":
    main()

Node.js

node/webhook/thread-reply.js
/**
 * Sends asynchronous message to Google Chat
 * @return {Object} response
 */
async function webhook() {
  const url = "https://chat.googleapis.com/v1/spaces/SPACE_ID/messages?key=KEY&token=TOKEN&messageReplyOption=REPLY_MESSAGE_FALLBACK_TO_NEW_THREAD"
  const res = await fetch(url, {
    method: "POST",
    headers: {"Content-Type": "application/json; charset=UTF-8"},
    body: JSON.stringify({
      text: "Hello from a Node script!",
      thread: {threadKey: "THREAD_KEY_VALUE"}
    })
  });
  return await res.json();
}

webhook().then(res => console.log(res));

Apps Script ;

apps-script/webhook/thread-reply.gs
function webhook() {
  const url = "https://chat.googleapis.com/v1/spaces/SPACE_ID/messages?key=KEY&token=TOKEN&messageReplyOption=REPLY_MESSAGE_FALLBACK_TO_NEW_THREAD"
  const options = {
    "method": "post",
    "headers": {"Content-Type": "application/json; charset=UTF-8"},
    "payload": JSON.stringify({
      "text": "Hello from Apps Script!",
      "thread": {"threadKey": "THREAD_KEY_VALUE"}
    })
  };
  const response = UrlFetchApp.fetch(url, options);
  console.log(response);
}