Google Chat-App als Webhook erstellen

Auf dieser Seite wird beschrieben, wie Sie einen Webhook einrichten, um asynchrone Nachrichten mithilfe externer Trigger an einen Chatbereich zu senden. Sie können beispielsweise eine Überwachungsanwendung konfigurieren, die das Bereitschaftspersonal in Chat benachrichtigt, wenn ein Server ausfällt. Informationen zum Senden einer synchronen Nachricht mit einer Chat-Anwendung finden Sie unter Nachricht senden.

Bei dieser Art von Architekturdesign können Nutzer nicht mit dem Webhook oder der verbundenen externen Anwendung interagieren, da die Kommunikation in eine Richtung erfolgt. Webhooks sind nicht dialogorientiert. Sie können weder auf Nachrichten von Nutzern noch auf Interaktionsereignisse der Chat-App reagieren oder diese empfangen. Wenn Sie auf Nachrichten antworten möchten, erstellen Sie eine Chat-App anstelle eines Webhooks.

Obwohl ein Webhook technisch gesehen keine Chat-Anwendung ist – Webhooks verbinden Anwendungen über Standard-HTTP-Anfragen – wird er auf dieser Seite zur Vereinfachung als Chat-Anwendung bezeichnet. Webhooks funktionieren nur in dem Chatbereich, in dem er registriert ist. Eingehende Webhooks funktionieren in Direktnachrichten, jedoch nur, wenn alle Nutzer Chat-Apps aktiviert haben. Sie können keine Webhooks im Google Workspace Marketplace veröffentlichen.

Das folgende Diagramm zeigt die Architektur eines Webhooks, der mit Google Chat verbunden ist:

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

Im obigen Diagramm hat eine Chat-App den folgenden Informationsfluss:

  1. Die Chat-Anwendungslogik empfängt Informationen von externen Diensten von Drittanbietern, z. B. von einem Projektmanagementsystem oder einem Tickettool.
  2. Die Chat-Anwendungslogik wird entweder in einem Cloud- oder lokalen System gehostet, das Nachrichten über eine Webhook-URL an einen bestimmten Chatbereich senden kann.
  3. Nutzer können in diesem Chatbereich Nachrichten aus der Chat-App empfangen, aber nicht mit der Chat-App interagieren.

Voraussetzungen

Python

  • Python 3.10.7 oder höher.
  • Ein Google Workspace-Konto mit Zugriff auf Chat.
  • Ein vorhandener Chatbereich.
  • Die httplib2-Bibliothek. Führen Sie gegebenenfalls den folgenden Befehlszeilenbefehl aus, um die Bibliothek mit pip zu installieren:

    pip install httplib2
    

Node.js

Java

Apps Script

Webhook erstellen

Registrieren Sie einen Webhook im Chatbereich, in dem Sie Nachrichten empfangen möchten, und schreiben Sie dann ein Skript, das Nachrichten sendet.

Eingehenden Webhook registrieren

  1. Öffnen Sie Google Chat in einem Browser. Webhooks können in der mobilen Google Chat App nicht konfiguriert werden.
  2. Rufen Sie den Gruppenbereich auf, dem Sie einen Webhook hinzufügen möchten.
  3. Klicken Sie neben dem Titel des Gruppenbereichs auf den und dann auf das Dreipunkt-Menü und dann auf Apps und Integrationen.
  4. Klicken Sie auf Webhooks hinzufügen.
  5. Geben Sie im Feld Name Quickstart Webhook ein.
  6. Geben Sie im Feld Avatar-URL den Wert https://developers.google.com/chat/images/chat-product-icon.png ein.
  7. Klicken Sie auf Speichern.
  8. Klicken Sie zum Kopieren der Webhook-URL auf Mehr und dann auf Link kopieren.

Webhook-Script schreiben

Das Beispiel-Webhook-Skript sendet eine Nachricht an den Bereich, in dem der Webhook registriert ist. Dazu wird eine POST-Anfrage an die Webhook-URL gesendet. Die Chat API antwortet mit einer Instanz von Message.

Wählen Sie eine Sprache aus, um zu erfahren, wie Sie ein Webhook-Script erstellen:

Python

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

  2. Fügen Sie den folgenden Code in quickstart.py ein:

    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. Ersetzen Sie den Wert für die Variable url durch die Webhook-URL, die Sie bei der Registrierung des Webhooks kopiert haben.

Node.js

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

  2. Fügen Sie den folgenden Code in index.js ein:

    Knoten/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. Ersetzen Sie den Wert für die Variable url durch die Webhook-URL, die Sie bei der Registrierung des Webhooks kopiert haben.

Java

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

  2. Kopieren Sie den folgenden Code und fügen Sie ihn in pom.xml 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.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. 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. Fügen Sie den folgenden Code in App.java ein:

    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. Ersetzen Sie den Wert für die Variable URL durch die Webhook-URL, die Sie bei der Registrierung des Webhooks kopiert haben.

Apps Script

  1. Rufen Sie in einem Browser Apps Script auf.

  2. Klicken Sie auf Neues Projekt.

  3. Fügen Sie den folgenden Code ein:

    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. Ersetzen Sie den Wert für die Variable url durch die Webhook-URL, die Sie bei der Registrierung des Webhooks kopiert haben.

Webhook-Script ausführen

Führen Sie das Skript in einer Befehlszeile aus:

Python

  python3 quickstart.py

Node.js

  node index.js

Java

  mvn compile exec:java -Dexec.mainClass=App

Apps Script

  • Klicken Sie auf Ausführen.

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

Unterhaltung starten oder beantworten

  1. Geben Sie spaces.messages.thread.threadKey als Teil des Nachrichtenanfragetextes an. Je nachdem, ob Sie einen Thread starten oder darauf antworten, verwenden Sie die folgenden Werte für threadKey:

    • Wenn Sie einen Thread starten, legen Sie threadKey auf einen beliebigen String fest. Notieren Sie sich diesen Wert, um eine Antwort auf den Thread zu posten.

    • Wenn Sie auf einen Thread antworten, geben Sie den threadKey an, der beim Start des Threads festgelegt wurde. Wenn Sie beispielsweise eine Antwort auf den Thread posten möchten, in dem die ursprüngliche Nachricht MY-THREAD verwendet hat, legen Sie MY-THREAD fest.

  2. Definieren Sie das Threadverhalten, wenn die angegebene threadKey nicht gefunden wird:

    • Auf einen Thread antworten oder einen neuen Thread starten. Fügen Sie der Webhook-URL den Parameter messageReplyOption=REPLY_MESSAGE_FALLBACK_TO_NEW_THREAD hinzu. Wenn dieser URL-Parameter übergeben wird, sucht Chat mit dem angegebenen threadKey nach einem vorhandenen Thread. Wird eine gefunden, wird die Nachricht als Antwort auf diesen Thread gepostet. Wenn keiner gefunden wird, startet die Nachricht einen neuen Thread, der diesem threadKey entspricht.

    • Auf einen Thread antworten oder nichts unternehmen. Fügen Sie der Webhook-URL den Parameter messageReplyOption=REPLY_MESSAGE_OR_FAIL hinzu. Wenn dieser URL-Parameter übergeben wird, sucht Chat mit dem angegebenen threadKey nach einem vorhandenen Thread. Wird eine gefunden, wird die Nachricht als Antwort auf diesen Thread gepostet. Wird keiner gefunden, wird die Nachricht nicht gesendet.

    Weitere Informationen findest du unter messageReplyOption.

Mit dem folgenden Codebeispiel wird ein Nachrichten-Thread gestartet oder beantwortet:

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);
}