Nachrichten mit eingehenden Webhooks an Google Chat senden

Mit eingehenden Webhooks können Sie asynchrone Nachrichten von Anwendungen senden, die keine Chat-Apps sind. So können Sie beispielsweise eine Monitoring-Anwendung so konfigurieren, dass das Bereitschaftsteam in Google Chat benachrichtigt wird, wenn ein Server ausfällt.

Wie Sie eine Nachricht in einem Chatbereich mit einer Chat-App asynchron senden, aktualisieren oder löschen, erfahren Sie unter Nachrichten erstellen, lesen, aktualisieren, löschen.

Architektur für eingehende Webhooks zum Senden asynchroner Nachrichten an Google Chat

Vorbereitung

Zum Ausführen des Beispiels in diesem Leitfaden benötigen Sie:

Python

  • Python 3.10.7 oder höher
  • Zugriff auf das Internet und einen Webbrowser.
  • Ein Google Workspace-Konto mit Zugriff auf Google Chat
  • Ein bestehender Google Chat-Bereich.
  • Die httplib2-Bibliothek. Führen Sie bei Bedarf den folgenden Befehlszeilenbefehl aus, um die Bibliothek mit „pip“ zu installieren:

    pip install httplib2
    

Node.js

Apps Script

Java

Webhook erstellen

Registrieren Sie den Webhook in dem Google Chat-Bereich, in den Sie Nachrichten senden möchten. Erstellen Sie dann ein Skript, über das Nachrichten gesendet werden.

Schritt 1: Eingehenden Webhook registrieren

  1. Öffnen Sie Google Chat in einem Webbrowser.
  2. Rufen Sie den Gruppenbereich auf, für den Sie einen Webhook hinzufügen möchten.
  3. Klicken Sie oben neben dem Titel des Gruppenbereichs auf den Drop-down-Pfeil > Apps & Integrationen.
  4. Klicken Sie auf Webhooks verwalten.
  5. Wenn dieser Gruppenbereich bereits andere Webhooks hat, klicken Sie auf Weitere hinzufügen. Andernfalls überspringen Sie diesen Schritt.
  6. Geben Sie unter Name „Kurzanleitungs-Webhook“ ein.
  7. Geben Sie für Avatar-URL https://developers.google.com/chat/images/chat-product-icon.png ein.
  8. Klicke auf SPEICHERN.
  9. Klicken Sie zum Kopieren der vollständigen Webhook-URL auf Kopieren.
  10. Klicken Sie außerhalb des Felds, um das Dialogfeld „Eingehende Webhooks“ zu schließen.

Schritt 2: Webhook-Skript schreiben

Das Webhook-Beispielskript sendet eine Nachricht an den Gruppenbereich, in dem der Webhook registriert wird. Dazu wird eine create message-Anfrage an die Webhook-URL gesendet. Die Google Chat API antwortet mit einer Instanz von Message.

Wählen Sie unten eine Sprache aus, um spezifische Informationen zum Erstellen des Webhook-Skripts zu erhalten:

Python

  1. Erstellen Sie in Ihrem Arbeitsverzeichnis eine Datei mit dem Namen quickstart.py.

  2. Kopieren Sie in quickstart.py den folgenden Code und fügen Sie ihn ein:

    python/webhook/quickstart.py
    from json import dumps
    
    from httplib2 import Http
    
    WEBHOOK_URL = "[URL FROM WEBHOOK]"
    
    def main():
        """Google Chat incoming webhook quickstart."""
        url = WEBHOOK_URL
        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. Ersetzen Sie den Wert für die Variable url durch die Webhook-URL, die Sie in Schritt 1 kopiert haben: Eingehenden Webhook registrieren.

Node.js

  1. Erstellen Sie in Ihrem Arbeitsverzeichnis eine Datei mit dem Namen index.js.

  2. Kopieren Sie in index.js den folgenden Code und fügen Sie ihn ein:

    Knoten/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. Ersetzen Sie den Wert für die Variable webhookURL durch die Webhook-URL, die Sie in Schritt 1 kopiert haben: Eingehenden Webhook registrieren.

Apps Script

  1. Rufen Sie die Seite Apps Script auf.

  2. Klicken Sie auf Neues Projekt.

  3. Kopieren Sie den folgenden Code und fügen Sie ihn ein:

    apps-script/webhook/webhook
    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. Ersetzen Sie den Wert für die Variable url durch die Webhook-URL, die Sie in Schritt 1 kopiert haben: Eingehenden Webhook registrieren.

Java

  1. Erstellen Sie in Ihrem Arbeitsverzeichnis eine Datei mit dem Namen pom.xml.

  2. Kopieren Sie in pom.xml Folgendes und fügen Sie es ein:

    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. Erstellen Sie in Ihrem Arbeitsverzeichnis die folgende Verzeichnisstruktur: src/main/java.

  4. Erstellen Sie im Verzeichnis src/main/java eine Datei mit dem Namen App.java.

  5. Kopieren Sie in App.java den folgenden Code und fügen Sie ihn ein:

    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. Ersetzen Sie den Wert für die Variable URL durch die Webhook-URL, die Sie in Schritt 1 kopiert haben: Eingehenden Webhook registrieren.

Schritt 3: Webhook-Skript ausführen

Führen Sie das Beispiel mit dem folgenden Befehl in Ihrem Arbeitsverzeichnis in der Befehlszeile aus:

Python

  python3 quickstart.py

Node.js

  node index.js

Apps Script

  • Klicken Sie auf Ausführen.

Java

  mvn compile exec:java -Dexec.mainClass=App

Wenn Sie den Beispielcode ausführen, sendet der Webhook eine Nachricht an den Gruppenbereich, in dem Sie ihn registriert haben.

Nachrichtenthread starten oder beantworten

Sie können eine Unterhaltung starten oder auf eine Nachricht antworten, indem Sie der Webhook-URL den Parameter threadKey hinzufügen. Jedes threadKey-Element ist eindeutig und gilt nur für die App, von der es festgelegt wird. Wenn zwei verschiedene Chat-Apps oder Webhooks denselben threadKey-Wert festlegen, werden zwei verschiedene Threads gestartet.

Konversation starten

Wenn Sie die erste Nachricht einer Unterhaltung mit einem Webhook posten möchten, hängen Sie die Parameter threadKey und messageReplyOption an die Webhook-URL an. Legen Sie für threadKey einen beliebigen String fest, aber denken Sie daran, was der String ist. Sie müssen ihn noch einmal angeben, um eine Antwort an den Thread zu senden.

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

Auf eine Unterhaltung antworten

Wenn Sie eine Nachricht an einen vorhandenen Nachrichtenthread senden möchten, hängen Sie die Parameter threadKey und messageReplyOption an die Webhook-URL an, die auf den Wert festgelegt ist, der zum Starten des Threads verwendet werden soll. Wenn Sie beispielsweise eine Nachricht an die folgende URL senden, wird eine Antwort an die Unterhaltung gesendet, in der threadKey MY-THREAD und messageReplyOption REPLY_MESSAGE_FALLBACK_TO_NEW_THREAD ist:

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

Limits und Überlegungen

Beachten Sie beim Konfigurieren von Webhooks die folgenden Limits und Hinweise:

  • Jeder Webhook funktioniert nur in dem Chatbereich, in dem er registriert ist.

  • Sie können keine Webhooks im Google Workspace Marketplace veröffentlichen.

  • Webhooks sind nicht dialogorientiert. Sie können keine Nachrichten von Nutzern oder Termine aus Google Chat beantworten oder empfangen.

  • Wenn nur Organisationseinheiten (OE) in Ihrer Domain Chat-Apps aktiviert sind, geben eingehende Webhooks den folgenden Fehler zurück:

    {
      "error": {
        "code": 403,
        "message": "The caller does not have permission",
        "status": "PERMISSION_DENIED"
      }
    }
    
  • Eingehende Webhooks funktionieren in Direktnachrichten, aber nur, wenn alle Nutzer Chat-Apps aktiviert haben.

  • Da Das Symbol zum Verwalten von Webhooks Webhooks verwalten nur über einen Webbrowser verfügbar sind, müssen Webhooks über die Chat-Web-App eingerichtet werden. Webhooks können über die mobile Chat App nicht konfiguriert werden.