Google Chat-App als Webhook erstellen

Auf dieser Seite wird beschrieben, wie Sie einen Webhook einrichten, um asynchrone Nachrichten mithilfe externer Trigger in einen Chatbereich zu senden. Sie können beispielsweise eine Monitoringanwendung so konfigurieren, dass Bereitschaftsmitarbeiter in Google Chat benachrichtigt werden, wenn ein Server ausfällt. Informationen zum Senden einer synchronen Nachricht mit einer Chat-App 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 konversationell. Sie können nicht auf Nachrichten von Nutzern antworten oder Nachrichten von Nutzern oder Interaktionsereignisse der Chat-App empfangen. Wenn Sie auf Nachrichten antworten möchten, erstellen Sie stattdessen eine Chat-App.

Ein Webhook ist technisch gesehen keine Chat-App. Webhooks verbinden Anwendungen über standardmäßige HTTP-Anfragen. Auf dieser Seite wird er jedoch zugunsten der Verständlichkeit als Chat-App bezeichnet. Jeder Webhook funktioniert nur in dem Chatbereich, in dem er registriert ist. Eingehende Webhooks funktionieren in Direktnachrichten, aber 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 vorherigen Diagramm sieht der Informationsfluss in einer Chat-App so aus:

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

Vorbereitung

Python

  • Ein Google Workspace-Konto für Unternehmen oder Organisationen mit Zugriff auf Google Chat. Ihre Google Workspace-Organisation muss Nutzern erlauben, eingehende Webhooks hinzuzufügen und zu verwenden.
  • Python 3.6 oder höher
  • Das Paketverwaltungstool pip

  • Die httplib2-Bibliothek Führen Sie den folgenden Befehl in der Befehlszeile aus, um die Bibliothek zu installieren:

    pip install httplib2

  • Einen Google Chat-Bereich Informationen zum Erstellen eines Gruppenbereichs mit der Google Chat API finden Sie unter Gruppenbereich erstellen. Eine Anleitung zum Erstellen in Google Chat finden Sie in der Hilfe.

Node.js

Java

Apps Script

Webhook erstellen

Registrieren Sie einen Webhook in dem Chatbereich, in dem Sie Nachrichten erhalten möchten, und schreiben Sie dann ein Script, mit dem Nachrichten gesendet werden.

Eingehenden Webhook registrieren

  1. Öffnen Sie Chat in einem Browser. Webhooks können nicht über die mobile Chat-App 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 Pfeil , um das Menü zu maximieren, 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 die URL https://developers.google.com/chat/images/chat-product-icon.png ein.

  7. Klicken Sie auf Speichern.

  8. Wenn Sie die Webhook-URL kopieren möchten, klicken Sie auf das Dreipunkt-Menü  Mehr und dann auf Link kopieren.

Webhook-Script schreiben

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

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

Python

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

  2. Fügen Sie in quickstart.py den folgenden Code 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 beim Registrieren des Webhooks kopiert haben.

Node.js

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

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

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

Java

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

  2. Kopieren Sie folgenden Text 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 Verzeichnisstruktur src/main/java.

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

  5. Fügen Sie in App.java den folgenden Code 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 beim Registrieren 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 Script 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 Bereich, in dem Sie ihn registriert haben.

Nachrichtenthreads starten oder beantworten

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

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

    • Wenn Sie auf einen Thread antworten, geben Sie die threadKey an, die beim Starten 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. Hier können Sie festlegen, was passieren soll, wenn die angegebene threadKey nicht gefunden wird:

    • Antworten Sie auf einen Thread oder starten Sie einen neuen. Fügen Sie der Webhook-URL den Parameter messageReplyOption=REPLY_MESSAGE_FALLBACK_TO_NEW_THREAD hinzu. Wenn Sie diesen URL-Parameter übergeben, sucht Google Chat mithilfe der angegebenen threadKey nach einem vorhandenen Thread. Wenn ein solcher Thread gefunden wird, wird die Nachricht als Antwort auf diesen Thread gepostet. Wenn keine gefunden wird, wird mit der Nachricht ein neuer Thread für diese threadKey gestartet.

    • Sie können auf einen Thread antworten oder nichts tun. Fügen Sie der Webhook-URL den Parameter messageReplyOption=REPLY_MESSAGE_OR_FAIL hinzu. Wenn Sie diesen URL-Parameter übergeben, sucht Google Chat mithilfe der angegebenen threadKey nach einem vorhandenen Thread. Wird eine gefunden, wird die Nachricht als Antwort auf diesen Thread gepostet. Wenn keine gefunden wird, wird die Nachricht nicht gesendet.

    Weitere Informationen finden Sie unter messageReplyOption.

Im folgenden Codebeispiel wird ein Nachrichten-Thread gestartet oder auf eine Nachricht geantwortet:

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

Fehler verarbeiten

Webhook-Anfragen können aus verschiedenen Gründen fehlschlagen, darunter:

  • Ungültige Anfrage.
  • Der Webhook oder der Gruppenbereich, in dem er gehostet wird, wird gelöscht.
  • Gelegentliche Probleme wie Netzwerkverbindungs- oder Kontingentlimits

Beim Erstellen Ihres Webhooks sollten Sie Fehler entsprechend behandeln:

Die Google Chat API gibt Fehler als google.rpc.Status zurück. Dieser enthält einen HTTP-Fehler code, der die Art des Fehlers angibt: einen Clientfehler (400er-Reihe) oder einen Serverfehler (500er-Reihe). Eine Liste aller HTTP-Zuordnungen findest du unter google.rpc.Code.

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

Informationen zum Interpretieren von HTTP-Statuscodes und zum Umgang mit Fehlern finden Sie unter Fehler.

Einschränkungen und Überlegungen