Google Chat-App als Webhook erstellen

Auf dieser Seite wird beschrieben, wie Sie einen Webhook einrichten, um asynchrone Nachrichten mithilfe externer Trigger in einen Chat-Bereich zu senden. Sie können beispielsweise eine Überwachungsanwendung so konfigurieren, dass sie den Bereitschaftsdienst in Google Chat benachrichtigt, 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 unidirektional ist. Webhooks sind nicht konversationell. Sie können nicht auf Nachrichten von Nutzern oder Ereignisse der Chat-App-Interaktion antworten oder Nachrichten von ihnen 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 Standard-HTTP-Anfragen. Auf dieser Seite wird er jedoch zur Vereinfachung als Chat-App bezeichnet. Jeder Webhook funktioniert nur in dem Chat-Bereich, in dem er registriert ist. Eingehende Webhooks funktionieren in Direktnachrichten, aber nur, wenn alle Nutzer Chat-Apps aktiviert haben. Sie können Webhooks nicht im Google Workspace Marketplace veröffentlichen.

Das folgende Diagramm zeigt die Architektur eines mit Google Chat verbundenen Webhooks:

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

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

  1. Die Chat-App-Logik empfängt Informationen von externen Drittanbieterdiensten wie einem Projektmanagementsystem oder einem Ticketsystem.
  2. Die Chat-App-Logik wird entweder in einem Cloud- oder einem lokalen System gehostet, das Nachrichten über eine Webhook-URL an einen bestimmten Chat-Bereich senden kann.
  3. Nutzer können in diesem bestimmten Chat-Bereich Nachrichten von der Chat-App empfangen, aber nicht mit der Chat-App interagieren.

Vorbereitung

Node.js

Python

  • Ein Google Workspace-Konto für Unternehmen oder ein Google Workspace Enterprise-Konto mit Zugriff auf Google Chat. Ihre Google Workspace-Organisation muss Nutzern das Hinzufügen und Verwenden eingehender Webhooks erlauben.
  • Python 3.6 oder höher
  • Das Paketverwaltungstool pip

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

    pip install httplib2

  • Ein Google Chat-Bereich. Informationen zum Erstellen eines Bereichs mit der Google Chat API finden Sie unter Bereich erstellen. Informationen zum Erstellen eines Bereichs in Google Chat finden Sie in der Hilfe. Besuchen Sie die Hilfe.

Java

Apps Script

Webhook erstellen

Wenn Sie einen Webhook erstellen möchten, registrieren Sie ihn im Chat-Bereich, in dem Sie Nachrichten empfangen möchten, und schreiben Sie dann ein Skript, das Nachrichten sendet.

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 Bereich auf, in dem Sie einen Webhook hinzufügen möchten.
  3. Klicken Sie neben dem Titel des Bereichs auf den Pfeil für „Maximieren“ expand_more und dann auf Apps und Integrationen.

  4. Klicken Sie auf „Hinzufügen“ und dann auf **Webhooks hinzufügen**.

  5. Geben Sie im Feld Name Quickstart Webhook ein.

  6. Geben Sie im Feld Avatar-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 Mehr und dann auf Link kopieren.

    Die Webhook-URL enthält zwei Parameter: key, ein gemeinsamer Wert für Webhooks, und token ein eindeutiger Wert, der geheim gehalten werden muss, um die Sicherheit Ihres Webhooks zu gewährleisten.

Webhook-Skript schreiben

Das Beispiel-Webhook-Skript sendet eine Nachricht an den Bereich, 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:

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:

    solutions/webhook-chat-app/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?key=KEY&token=TOKEN"
  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.

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:

    solutions/webhook-chat-app/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.

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:

    solutions/webhook-chat-app/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>webhook-app</artifactId>
  <version>0.1.0</version>
  <name>webhook-app</name>

  <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 in App.java den folgenden Code ein:

    solutions/webhook-chat-app/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/SPACE_ID/messages?key=KEY&token=TOKEN";
  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:

    solutions/webhook-chat-app/webhook.gs
    function webhook() {
  const url = "https://chat.googleapis.com/v1/spaces/SPACE_ID/messages?key=KEY&token=TOKEN"
  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 beim Registrieren des Webhooks kopiert haben.

Webhook-Skript ausführen

Führen Sie das Skript in einer Befehlszeilenschnittstelle aus:

Node.js

  node index.js

Python

  python3 quickstart.py

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.

Nachrichtenthread starten oder darauf antworten

  1. Geben Sie spaces.messages.thread.threadKey als Teil des Anfragetexts der Nachricht 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 für threadKey eine beliebige Zeichenfolge 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 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. Definieren Sie das Threadverhalten, wenn der 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 Sie diesen URL-Parameter übergeben, sucht Google Chat nach einem vorhandenen Thread mit dem angegebenen threadKey. Wenn ein Thread gefunden wird, wird die Nachricht als Antwort auf diesen Thread gepostet. Wenn kein Thread gefunden wird, wird mit der Nachricht ein neuer Thread mit diesem threadKey gestartet.

    • 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 nach einem vorhandenen Thread mit dem angegebenen threadKey. Wenn ein Thread gefunden wird, wird die Nachricht als Antwort auf diesen Thread gepostet. Wenn kein Thread gefunden wird, wird die Nachricht nicht gesendet.

    Weitere Informationen finden Sie unter messageReplyOption.

Das folgende Codebeispiel startet einen Nachrichtenthread oder antwortet darauf:

Node.js

solutions/webhook-chat-app/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));

Python

solutions/webhook-chat-app/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()

Java

solutions/webhook-chat-app/src/main/java/com/google/chat/webhook/AppThread.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/SPACE_ID/messages?key=KEY&token=TOKEN&messageReplyOption=REPLY_MESSAGE_FALLBACK_TO_NEW_THREAD";
  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!",
      "thread", Map.of(
        "threadKey", "THREAD_KEY_VALUE"
      )
    ));

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

Apps Script

solutions/webhook-chat-app/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, z. B.:

  • Ungültige Anfrage.
  • Webhook oder Bereich, in dem der Webhook gehostet wird, wurde gelöscht.
  • Zeitweise auftretende Probleme wie Netzwerkverbindung oder Kontingentlimits.

Beim Erstellen Ihres Webhooks sollten Sie Fehler entsprechend behandeln:

  • Fehler protokollieren.
  • Bei zeitbasierten Fehlern, Kontingentfehlern oder Fehlern bei der Netzwerkverbindung die Anfrage mit exponentiellem Backoff wiederholen.
  • Nichts tun. Dies ist angemessen, wenn das Senden der Webhook-Nachricht nicht wichtig ist.

Die Google Chat API gibt Fehler als google.rpc.Status, die einen HTTP-Fehler code enthält, der den Typ des aufgetretenen Fehlers angibt: ein Clientfehler (400er-Reihe) oder ein Serverfehler (500er-Reihe). Eine Übersicht über alle HTTP-Zuordnungen finden Sie unter google.rpc.Code.

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

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

Einschränkungen und Überlegungen

  • Wenn Sie mit einem Webhook in der Google Chat API eine Nachricht erstellen, enthält die Antwort nicht die vollständige Nachricht. In der Antwort werden nur die Felder name und thread.name ausgefüllt.
  • Für Webhooks gilt das Kontingent pro Bereich für spaces.messages.create: 1 Anfrage pro Sekunde, aufgeteilt auf alle Webhooks im Bereich. Google Chat lehnt möglicherweise auch Webhook-Anfragen ab, die 1 Anfrage pro Sekunde im selben Bereich überschreiten. Weitere Informationen zu den Kontingenten der Chat API finden Sie unter Nutzungslimits.