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 dans Chat lorsqu'un serveur est hors service. Pour envoyer un message synchrone avec une application Chat, consultez Envoyer un message.

Avec ce type d'architecture, les utilisateurs ne peuvent pas interagir avec le webhook ni avec l'application externe connectée, car la communication est unidirectionnelle. Les webhooks ne sont pas conversationnels. Ils ne peuvent pas répondre aux messages des utilisateurs ni en recevoir, ni recevoir d'événements d'interaction avec l'application Chat. 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 les applications à l'aide de requêtes HTTP standards), cette page y fait référence en tant qu'application Chat pour simplifier les explications. 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 tous les utilisateurs ont activé les applications Chat. Vous ne pouvez pas publier de webhook sur Google Workspace Marketplace.

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

Architecture des webhooks entrants pour envoyer des messages asynchrones à Chat.

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

  1. La logique de l'application Chat reçoit des informations provenant de services tiers externes, tels qu'un système de gestion de projet ou un outil de gestion des tickets.
  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

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 des 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 dans lequel vous souhaitez ajouter un webhook.
  3. À côté du titre de l'espace, cliquez sur la flèche de développement , puis sur Applications et intégrations.

  4. Cliquez sur Ajouter des Webhooks.

  5. Dans le champ 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 du webhook, cliquez sur Plus, puis sur Copier le lien.

Écrire le script du 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 du webhook. L'API Chat répond avec une instance de Message.

Sélectionnez une langue pour découvrir comment 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 du 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 :

    node/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 du 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 code 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épertoire 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 du 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 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 du webhook que vous avez copiée lors de l'enregistrement du webhook.

Exécuter le script webhook

Dans une CLI, exécutez le script :

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 un fil de discussion ou y répondre

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

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

    • Si vous répondez à un fil de discussion, spécifiez le threadKey qui a été défini au début du fil. 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 du webhook. Si vous transmettez ce paramètre d'URL, Chat recherche un fil de discussion existant à l'aide du threadKey spécifié. Si un fil de discussion est trouvé, le message est publié en tant que réponse à ce fil. Si aucun n'est trouvé, le message lance un nouveau fil de discussion correspondant à ce threadKey.

    • Répondez à un fil de discussion ou ne faites rien. Ajoutez le paramètre messageReplyOption=REPLY_MESSAGE_OR_FAIL à l'URL du webhook. Si vous transmettez ce paramètre d'URL, Chat recherche un fil de discussion existant à l'aide du threadKey spécifié. Si un fil de discussion est trouvé, le message est publié en tant que réponse à ce fil. Si aucun n'est trouvé, 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);
}

Gérer les erreurs

Les requêtes de webhook peuvent échouer pour différentes raisons, y compris :

  • Demande incorrecte.
  • Le webhook ou l'espace hébergeant le webhook est supprimé.
  • Problèmes intermittents tels que la connectivité réseau ou les limites de quota.

Lorsque vous créez votre webhook, vous devez gérer correctement les erreurs en procédant comme suit :

L'API Google Chat renvoie les erreurs sous la forme d'un google.rpc.Status, qui inclut une erreur HTTP code indiquant le type d'erreur rencontré : une erreur client (série 400) ou une erreur serveur (série 500). Pour examiner tous les mappages HTTP, consultez google.rpc.Code.

{
    "code": 503,
    "message": "The service is currently unavailable.",
    "status": "UNAVAILABLE"
}

Pour savoir comment interpréter les codes d'état HTTP et gérer les erreurs, consultez Erreurs.

Limites et points à noter

  • Lorsque vous créez un message avec un webhook dans l'API Google Chat, la réponse ne contient pas le message complet. La réponse ne renseigne que les champs name et thread.name.
  • Les webhooks sont soumis au quota par espace pour spaces.messages.create : une requête par seconde, partagée entre tous les webhooks de l'espace. Chat peut également rejeter les requêtes de webhook qui dépassent une requête par seconde dans le même espace. Pour en savoir plus sur les quotas de l'API Chat, consultez Limites d'utilisation.