Google Chat API konfigurieren

Für jede Google Chat-App, die Sie erstellen, ist ein eigenes Google Cloud-Projekt mit aktivierter und konfigurierter Chat API erforderlich.

Wenn Sie schreibgeschützte API-Aufrufe mit Nutzerauthentifizierung ausführen möchten, z. B. um Spaces abzurufen und Nachrichten aufzulisten, müssen Sie nur die API aktivieren und einen OAuth-Client erstellen.

Wenn Sie API-Aufrufe zum Erstellen, Aktualisieren und Löschen ausführen oder eine interaktive Chat-App bereitstellen und testen möchten, die als Google Workspace-Add-on erstellt wurde und Google Chat erweitert, müssen Sie auch die Chat API konfigurieren. In den Konfigurationseinstellungen der Chat API geben Sie alle Details zur Chat-App an, einschließlich Anzeigename, Avatar, Bereitstellungsendpunkte und interaktive Funktionen.

Vorbereitung

• Ein Google Workspace-Konto für Unternehmen mit Zugriff auf Google Chat.
• Google Cloud-Projekt erstellen
• Konfigurieren Sie den OAuth-Zustimmungsbildschirm.
• Aktivieren Sie die Google Chat API.

Anzeigenamen, Avatar und Beschreibung für Ihre Chat-App auswählen

Wenn Sie die Chat API aktivieren, konfigurieren Sie die Details zu Ihrer Chat-App, die Nutzern in Google Chat angezeigt werden, einschließlich Anzeigename, Avatar und Beschreibung. Diese Details werden nur in Google Chat angezeigt. Wenn Sie Ihre Chat-App im Marketplace veröffentlichen möchten, müssen Sie auch die Details angeben, die im Marketplace-Eintrag Ihrer Chat-App angezeigt werden.

Bevor Sie eine Chat-App konfigurieren, bereiten Sie die folgenden Informationen vor:

Der Name, der Avatar und die Beschreibung der Chat-App werden Nutzern in der Chat-Benutzeroberfläche angezeigt. Bei einigen Schreibanfragen an die Chat API verwendet Google Chat diese Informationen, um die Aktionen, die eine Chat-App in Google Chat ausführt, zuzuordnen.

Wenn Sie beispielsweise die Methode spaces.create() aufrufen, fügt Google Chat den Namen der Chat-App in die Beschreibung ein, die angibt, wer den Gruppenbereich erstellt hat, wie in der folgenden Abbildung zu sehen:

Nutzer sehen oder verwenden diese Informationen auch auf folgende Weise, um mit Chat-Apps zu interagieren:

• Erwähnen Sie die Chat-App mit @, um sie einem Gruppenbereich hinzuzufügen oder ihr eine Nachricht zu senden.
• Suchen Sie die Chat-App und starten Sie eine Direktnachricht mit ihr. Im Menü Apps werden bei Direktnachrichten der Name und der Avatar der Chat-App angezeigt.
• Über die Eingabezeile können Nutzer Chat-Apps durchsuchen und deren Namen, Avatar und Beschreibung sehen.

Chat-App in der Google Cloud Console konfigurieren

Wenn Sie die Details Ihrer Chat-App haben, öffnen Sie Ihr Cloud-Projekt und konfigurieren Sie die Chat API:

1. Rufen Sie in der Google Cloud Console die Seite „Chat API“ auf und klicken Sie auf die Seite Konfiguration:

   Zur Seite „Chat API-Konfiguration“

2. Geben Sie unter Anwendungsinformationen den Anwendungsnamen, die Avatar-URL und die Beschreibung ein.

3. Optional: Wählen Sie im Menü Markup-Syntax die Standard-Markup-Syntax (Markdown oder Chat) für die Nachrichten Ihrer Chat-App aus. Weitere Informationen zur Textformatierung und dazu, wie in Google Chat die Markup-Syntax für API-Anfragen bestimmt wird, finden Sie unter Nachrichten formatieren.

4. Konfigurieren Sie unter Interaktive Funktionen, ob Ihre Chat-App auf Nutzerinteraktionen reagiert:

   Wenn Sie eine interaktive Chat-App erstellen möchten, aktivieren Sie Interaktive Funktionen aktivieren und führen Sie die folgenden Schritte aus:

   1. Unter Funktionalität:
      • Optional: Wählen Sie Support App Home aus, um eine Startseitenkarte auf dem Tab Startseite von 1:1-Direktnachrichten mit der Chat-App anzuzeigen.
      • Wählen Sie Gruppenbereichen und Gruppenunterhaltungen beitreten aus, damit Ihre Chat-App installiert und verwendet werden kann. Standardmäßig können Nutzer die Chat-App in einem eigenen Bereich zwischen dem Nutzer und der Chat-App installieren und Nachrichten mit ihr austauschen. Nutzer können die Chat-App auch in Bereichen mit mehreren Personen hinzufügen und mit ihr interagieren.

   2. Wählen Sie unter Verbindungseinstellungen die Architektur aus, die Sie zum Empfangen von Ereignisobjekten aus Google Chat verwenden möchten:

      • Wenn Sie einen HTTP-Dienst verwenden möchten, wählen Sie HTTP-Endpunkt-URL aus und geben Sie eine URL an.
      • Wenn Sie ein Google Apps Script-Projekt verwenden möchten, wählen Sie Apps Script aus und geben Sie eine Bereitstellungs-ID für das Projekt an.
      • Wenn Sie einen Dialogflow-Agenten verwenden möchten, wählen Sie Dialogflow, dann Dialogflow CX oder Dialogflow ES aus und geben Sie den Ressourcennamen des Agenten an.
      • Wenn Sie Pub/Sub verwenden möchten, wählen Sie Cloud Pub/Sub aus und geben Sie den Themennamen ein.

   3. Optional: Wenn Sie Ereignisobjekte an bestimmte Endpunkte oder Funktionen weiterleiten möchten, rufen Sie die Verbindungseinstellungen > Trigger auf und geben Sie die Callback-Endpunkte oder ‑Funktionen für die folgenden Chat-Trigger an oder aktualisieren Sie sie:

      • App-Startseite (wenn App-Startseite unterstützen aktiviert ist): Ein Nutzer öffnet den Tab Startseite in einer 1:1-Direktnachricht mit der Chat-App.
      • Zu Gruppenbereich hinzugefügt: Ein Nutzer fügt die Chat-App einer Gruppenunterhaltung oder einem Gruppenbereich hinzu oder installiert die Chat-App für Direktnachrichten.
      • Nachricht: Ein Nutzer sendet eine Nachricht an die Chat-App. Beispielsweise sendet ein Nutzer eine Direktnachricht an die Chat-App oder erwähnt die Chat-App in einem Gruppenbereich mit mehreren Personen mit @.
      • Aus Gruppenbereich entfernt: Ein Nutzer deinstalliert die Chat-App oder entfernt sie aus einem Gruppenbereich.
      • App-Befehl: Ein Nutzer ruft einen Schnellbefehl, einen Slash-Befehl oder eine Nachrichtenaktion aus der Chat-App auf.

   4. Optional: Fügen Sie weitere interaktive Funktionen hinzu, z. B. Einstiegsprompts, Befehle (Schnellbefehle, Slash-Befehle und nachrichtenbasierte Aktionen) oder Linkvorschauen.

   5. Geben Sie unter Sichtbarkeit Ihre E‑Mail-Adresse an, damit Sie die Chat-App installieren und testen können, bevor Sie sie im Google Workspace Marketplace veröffentlichen. Sie können bis zu fünf Personen oder eine oder mehrere Google-Gruppen aus Ihrer Google Workspace-Organisation angeben.

5. Optional: Klicken Sie unter Logs das Kästchen Fehler in Logging protokollieren an, um Google Cloud Logging zu verwenden. Weitere Informationen finden Sie unter Fehlerlogs für Chat-Apps abfragen.

6. Klicken Sie auf Speichern.

Nachdem Sie die Konfiguration gespeichert haben, können alle Personen, die Sie in der Einstellung Sichtbarkeit der Chat API angegeben haben, die Chat-App installieren, testen oder verwenden. Informationen zum Testen und Debuggen Ihrer Chat-App finden Sie unter Interaktive Funktionen für Google Chat-Apps testen.

Chat-App mit der Google Workspace Add-ons API konfigurieren

Anstatt Ihre Chat-App manuell in der Google Cloud Console zu konfigurieren, können Sie Ihr Google Cloud-Projekt, das im Google Workspace Developer Preview Program registriert ist, verwenden, um die Konfiguration einer Chat-App, die als Google Workspace-Add-on erstellt wurde, programmatisch zu lesen und zu aktualisieren. Verwenden Sie dazu die Ressource chatAppConfig in der Google Workspace add-ons API.

chatAppConfig ist eine Singleton-Ressource, die für jedes Cloud-Projekt immer vorhanden ist. Bevor Sie eine Konfiguration zum ersten Mal speichern, enthält die Ressource eine leere Konfiguration. Das ist auch das, was GetChatAppConfig zurückgibt, wenn Sie die Ressource vor dem ersten Speichern lesen. Da die Ressource bereits vorhanden ist, müssen Sie sie nicht separat erstellen. Verwenden Sie UpdateChatAppConfig, um die ursprüngliche Konfiguration zu speichern und eine vorhandene Konfiguration zu aktualisieren.

Voraussetzungen und Authentifizierung

Bevor Sie GetChatAppConfig oder UpdateChatAppConfig aufrufen, müssen Sie die folgenden Voraussetzungen erfüllen:

1. Registrieren Sie Ihr Google Cloud-Projekt im Google Workspace Developer Preview Program.
2. Aktivieren Sie die Google Workspace Add-ons API (gsuiteaddons.googleapis.com) in Ihrem Cloud-Projekt. Optional können Sie die Google Chat API (chat.googleapis.com) aktivieren, wenn Sie die Konfiguration der Chat-App in der Google Cloud Console aufrufen oder aktualisieren oder die Chat API aufrufen möchten.
3. Authentifizieren Sie sich als menschlicher Nutzer mit OAuth 2.0-Anmeldedaten, die den Bereich https://www.googleapis.com/auth/cloud-platform enthalten. Die Dienstkontoauthentifizierung wird für chatAppConfig-Methoden nicht unterstützt.
4. Prüfen Sie, ob der authentifizierte Nutzer die erforderlichen IAM-Berechtigungen (Identity and Access Management) für das Cloud-Zielprojekt hat:
   • gsuiteaddons.chatAppConfigs.get und chat.bots.get, um die Konfiguration zu lesen (GetChatAppConfig).
   • gsuiteaddons.chatAppConfigs.update und chat.bots.update, um die Konfiguration (UpdateChatAppConfig) zu aktualisieren.
5. Wenn Sie eine Clientbibliothek verwenden, laden Sie die Entwicklervorschau-Clientbibliothek mit Ihrem registrierten Entwicklervorschau-Konto herunter.

Konfiguration einer Chat-App aktualisieren

Wenn Sie eine Chat-App zum ersten Mal konfigurieren oder eine vorhandene Konfiguration aktualisieren möchten, senden Sie eine PATCH-Anfrage (UpdateChatAppConfig) an die Singleton-Ressource chatAppConfig für Ihr Cloud-Projekt:

• Beim ersten Speichern eines Cloud-Projekts mit einer leeren chatAppConfig sind displayName (3 bis 25 Zeichen) und description (1 bis 40 Zeichen) erforderlich. Wenn Sie interactiveFeatureConfig beim ersten Speichern weglassen, wird die Chat-App als nicht interaktiv konfiguriert.
• Verwenden Sie für nachfolgende Aktualisierungen den optionalen Suchparameter updateMask, um die kommagetrennten Felder anzugeben, die aktualisiert werden sollen (oder lassen Sie updateMask weg, um alle angegebenen Felder zu aktualisieren). Wenn Sie ein wiederkehrendes Feld (appCommands, urlPatterns oder allowlistedTestingPrincipals) aktualisieren, wird die gesamte Liste ersetzt.

PATCH https://gsuiteaddons.googleapis.com/v1/projects/PROJECT_NUMBER/chatAppConfig?updateMask=displayName,description,avatarUri,state,errorLoggingEnabled,markupSyntax,interactiveFeatureConfig
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

{
  "name": "projects/PROJECT_NUMBER/chatAppConfig",
  "displayName": "Cymbal Assistant",
  "description": "Helps manage tasks and schedules",
  "avatarUri": "https://www.gstatic.com/dynamite/images/quickstart-app-avatar.png",
  "state": "ACTIVE",
  "errorLoggingEnabled": true,
  "markupSyntax": "MARKUP_SYNTAX_MARKDOWN",
  "interactiveFeatureConfig": {
    "supportsMultiuserSpaces": false,
    "connectionConfig": {
      "httpEndpointConfig": {
        "commonUrl": "https://example.com/chat"
      }
    },
    "appCommands": [
      {
        "commandType": "SLASH_COMMAND",
        "commandId": 1,
        "command": "/help",
        "description": "Show available commands",
        "dialogEnabled": false
      }
    ],
    "urlPatterns": [
      {
        "hostPattern": "example.com",
        "pathPrefix": "tasks/"
      }
    ],
    "allowlistedTestingPrincipals": [
      "USER_EMAIL"
    ]
  }
}

Ersetzen Sie in der Anfrage-URL, im Header und im Text Folgendes:

• PROJECT_NUMBER: Die numerische Projektnummer des Cloud-Projekts, in dem Ihre Chat-App gehostet wird.
• ACCESS_TOKEN: Ein OAuth 2.0-Zugriffstoken für Nutzer, das mit dem Bereich https://www.googleapis.com/auth/cloud-platform autorisiert wurde.
• USER_EMAIL: Eine E-Mail-Adresse oder Google-Gruppe aus Ihrer Google Workspace-Organisation, die Sie zum Testen der Chat-App auf die Zulassungsliste setzen möchten (z. B. Ihre eigene E-Mail-Adresse).
• Die Beispielkonfigurationsfelder im Anfragetext (z. B. displayName, description, avatarUri und interactiveFeatureConfig, einschließlich Ihrer Endpunktkonfiguration, Befehle, URL-Muster für die Linkvorschau und Test-Hauptkonten) durch die Werte für Ihre Chat-App. Weitere Informationen zu allen unterstützten Feldern und Endpunktoptionen finden Sie in der REST-Referenz zu projects.chatAppConfig und unter projects.chatAppConfig.patch.

Konfiguration einer Chat-App abrufen

Wenn Sie die aktuelle Chat-App-Konfiguration für ein Cloud-Projekt lesen möchten, rufen Sie GetChatAppConfig auf. Sie können den optionalen Abfrageparameter view (ChatAppConfigView) übergeben:

• BASIC (Standard): Gibt grundlegende Metadaten ohne interactiveFeatureConfig zurück.
• FULL: Gibt alle Konfigurationsfelder zurück, einschließlich interactiveFeatureConfig.

Wenn die Konfiguration der Chat-App noch nicht für das Cloud-Projekt gespeichert wurde, gibt die Methode ein leeres ChatAppConfig-Objekt zurück.

GET https://gsuiteaddons.googleapis.com/v1/projects/PROJECT_NUMBER/chatAppConfig?view=FULL
Authorization: Bearer ACCESS_TOKEN

const {GSuiteAddOnsClient} = require('@google-cloud/gsuiteaddons').v1;

const client = new GSuiteAddOnsClient();

async function getChatAppConfig() {
  const [response] = await client.getChatAppConfig({
    name: 'projects/PROJECT_NUMBER/chatAppConfig',
    view: 'FULL',
  });
  console.log(JSON.stringify(response, null, 2));
}

getChatAppConfig();

from google.cloud import gsuiteaddons_v1

client = gsuiteaddons_v1.GSuiteAddOnsClient()

request = gsuiteaddons_v1.GetChatAppConfigRequest(
    name="projects/PROJECT_NUMBER/chatAppConfig",
    view=gsuiteaddons_v1.GetChatAppConfigRequest.ChatAppConfigView.FULL,
)
response = client.get_chat_app_config(request=request)
print(response)

Überlegungen zu vorhandenen Google Workspace-Add-ons

Chat-Apps erfordern eine andere Konfiguration als Google Workspace-Add-ons, die andere Google Workspace-Anwendungen erweitern. Wenn Ihr Add‑on andere Google Workspace-Anwendungen erweitert, beachten Sie die folgenden Anforderungen für die Konfiguration der Chat-App:

• Sowohl Einzelpersonen als auch Google Workspace-Administratoren müssen Ihr Add-on über den Marketplace installieren können. Diese Installationseinstellungen konfigurieren Sie im Marketplace SDK.
• Chat-Apps verwenden nicht den Namen und das Logo, die Sie für andere Google Workspace-Anwendungen im addons.common-Objekt des Manifests konfigurieren.
• Bei Add-ons, die im Google Workspace Marketplace veröffentlicht wurden, können Sie keinen Entwurf von Änderungen an den Konfigurationseinstellungen der Google Chat API speichern. Nachdem Sie die Konfigurationseinstellungen der Chat API aktualisiert und gespeichert haben, ist die aktualisierte Chat-App sofort für alle vorhandenen Nutzer verfügbar. Wenn Sie Ihren Marketplace-Eintrag aktualisieren möchten, können Sie einen Entwurf erstellen, bevor Sie Änderungen einreichen.
• Wenn Sie Ihr Add-on mit Apps Script erstellt haben:
  • Sie müssen dieselbe Apps Script-Bereitstellungs-ID verwenden, die Sie für den Rest Ihrer Add-on-Konfiguration verwenden.
  • Sie können den Apps Script-Editor nicht verwenden, um Testbereitstellungen in Google Chat zu installieren. Stattdessen müssen Sie sie direkt über die Chat-Benutzeroberfläche installieren.
• Wenn Sie Ihr Add‑on mit einem HTTP-Dienst erstellt haben, lassen Sie alle Konfigurationsdetails für die Chat-App im Manifest projects.deployments weg, das Sie mit der Google Workspace Add-ons API erstellen. Die HTTP-Bereitstellungen, die Sie im Google Workspace Marketplace SDK angeben, werden nur für andere Google Workspace-Anwendungen verwendet. Konfigurieren Sie Ihre Chat-App stattdessen in der Google Cloud Console oder mit der Ressource chatAppConfig in der Google Workspace Add-ons API.

Anderen Personen die Berechtigung zum Konfigurieren der Chat API erteilen

Sie können bestimmten Nutzern Zugriff auf die Konfigurationsseite der Chat-App gewähren, indem Sie ihnen die Google Cloud Identity Access Management (IAM)-Rolle Chat-Apps-Inhaber oder Chat-Apps-Betrachter zuweisen. Nutzer mit diesen Rollen können die Konfigurationsseite für Chat-Apps nicht über das Dashboard APIs & Dienste aufrufen. Sie können jedoch so auf die Konfigurationsseite zugreifen, indem sie die Google Cloud Console für das Host-Cloud-Projekt der Chat-App aufrufen:

https://console.developers.google.com/apis/api/chat.googleapis.com/hangouts-chat?project=PROJECT_ID

Dabei ist PROJECT_ID die Projekt-ID des Google Cloud-Projekts, in dem die Chat-App gehostet wird.

Weitere Informationen

• Architektur für eine Chat-App auswählen
• Nutzerinteraktionen empfangen und darauf reagieren
• Interaktive Funktionen für Google Chat-Apps testen