Überblick
Mit Gmail können Agenten und Workflows E-Mails durchsuchen, lesen, entwerfen, senden und mit Labels versehen. In Langdock Cloud verbinden Nutzer Gmail über den Langdock OAuth-Client, dafür ist keine Einrichtung nötig. Folge diesem Guide, wenn du deinen eigenen Google OAuth-Client nutzt, zum Beispiel in einem Dedicated Deployment oder um dein eigenes Branding im Zustimmungsbildschirm zu zeigen. Er hat zwei Teile:- Google OAuth-Client erstellen, damit Nutzer Gmail verbinden können.
- Webhook-Trigger einrichten (optional).
Authentifizierung: OAuth
Kategorie: Kommunikation
Verfügbarkeit: Alle Workspace-Pläne
Voraussetzungen
- Ein Google Cloud-Projekt, das du verwalten kannst
- Admin-Zugriff auf deinen Langdock Workspace
- Für Webhook-Trigger: die Berechtigung, in diesem Projekt Pub/Sub-Topics, Subscriptions und Dienstkonten anzulegen
Google OAuth-Client erstellen
1
Gmail API aktivieren
Wähle in der Google Cloud Console dein Projekt aus, öffne APIs & Services → Library und aktiviere die Gmail API.
2
Zustimmungsbildschirm konfigurieren
Öffne Google Auth Platform und fülle Branding aus. Wähle unter Audience die Option Internal, wenn sich nur Nutzer deiner Google Workspace-Organisation verbinden. Gmail-Scopes sind eingeschränkt, deshalb braucht eine External-App eine Prüfung durch Google, bevor sich Nutzer außerhalb deiner Testnutzer verbinden können.Füge unter Data access die Scopes aus Berechtigungen hinzu.
3
OAuth-Client erstellen
Öffne Google Auth Platform → Clients und klicke auf Create client. Wähle als Anwendungstyp Web application.Trage unter Authorized redirect URIs die Redirect-URL aus Langdock ein. Du findest sie unter Workspace Einstellungen → Integrationen: Wähle Gmail aus und öffne unter Bring your own OAuth Client den Dialog für den OAuth-Client.Klicke auf Create und kopiere die Client ID und das Client secret.
4
Client in Langdock hinzufügen
Trage im Gmail OAuth-Client-Dialog die Client-ID und das Client-Secret ein, wähle unter Zugriff, wer den Client nutzen kann, klicke auf Speichern und bestätige. Wähle den gespeicherten Client in der Client-Liste aus und bestätige den Wechsel, um ihn zu aktivieren.Details zu Zugriffsoptionen und Gruppen-Clients findest du unter Bring Your Own OAuth Client.
5
Verbindung testen
Lass einen Nutzer sein Gmail-Konto verbinden und eine Gmail-Aktion ausführen, zum Beispiel Search emails.
Webhook-Trigger einrichten
Gmail hat zwei Arten von Triggern:- Polling-Trigger (Neue E-Mail, Neue E-Mail entspricht Suchkriterien, Label an E-Mail geändert) prüfen nach Zeitplan auf Änderungen. Sie funktionieren mit jedem OAuth-Client.
- Webhook-Trigger (Monitor inbox, Monitor labels, Monitor sent emails) starten Workflows innerhalb von Sekunden. Gmail sendet Benachrichtigungen über Änderungen per Google Cloud Pub/Sub, deshalb braucht dein OAuth-Client ein Pub/Sub-Topic und eine Push-Subscription.
Das Topic muss im Google Cloud-Projekt deines OAuth-Clients liegen, und Google muss deine Langdock-Instanz erreichen können. Dedicated Deployments brauchen aktivierte Integrations-Webhook-Trigger.
1
Cloud Pub/Sub API aktivieren
Öffne in der Google Cloud Console das Projekt deines OAuth-Clients, gehe zu APIs & Services → Library und aktiviere die Cloud Pub/Sub API.
2
Pub/Sub-Topic erstellen
- Öffne Pub/Sub → Topics und klicke auf Create topic.
- Gib eine Topic-ID ein, zum Beispiel
gmail-webhooks, deaktiviere Add a default subscription und klicke auf Create. - Klicke auf der Topic-Seite oben rechts auf Show info panel. Klicke im Tab Permissions auf Add principal.
- Gib
gmail-api-push@system.gserviceaccount.comein, wähle die Rolle Pub/Sub Publisher und klicke auf Save.
3
Push-Dienstkonto erstellen
- Öffne IAM & Admin → Service accounts und klicke auf Create service account.
- Gib einen Namen ein, zum Beispiel
gmail-pubsub-push, und klicke auf Create and continue. - Überspringe Permissions und Principals with access und klicke auf Done. Das Konto braucht keine Rollen, weil Pub/Sub es nur nutzt, um die Anfragen an Langdock zu signieren.
- Kopiere die E-Mail-Adresse des Dienstkontos aus der Liste. Du brauchst sie in den nächsten Schritten.
4
Topic und Dienstkonto in Langdock speichern
- Klappe im Gmail OAuth-Client-Dialog Webhook-Trigger auf.
- Trage bei Pub/Sub-Topic den vollständigen Topic-Pfad ein, zum Beispiel
projects/PROJECT_ID/topics/gmail-webhooks. - Trage bei Dienstkonto der Push-Subscription die E-Mail-Adresse des Dienstkontos ein, zum Beispiel
gmail-pubsub-push@PROJECT_ID.iam.gserviceaccount.com. - Klicke auf Speichern und bestätige.
- Kopiere den Push-Endpunkt, der jetzt im Dialog erscheint.
5
Push-Subscription anlegen
Öffne dein Topic unter Pub/Sub → Topics und klicke auf Create subscription:
- Delivery type: Push
- Endpoint URL: der Push-Endpunkt aus Langdock
- Enable authentication: aktiviert, mit dem Dienstkonto aus Schritt 3
- Audience: leer lassen
- Retry policy: Retry after exponential backoff delay
- Expiration period: Never expire
Mit der Standard-Ablaufzeit löscht Google die Subscription nach 31 Tagen ohne Benachrichtigungen, und Webhook-Trigger stoppen ohne Fehlermeldung.
6
Webhook-Trigger testen
Erstelle einen Workflow mit einem Integrations-Trigger, wähle Gmail und Monitor inbox und sende dir selbst eine E-Mail. Der Workflow startet innerhalb von Sekunden.
So funktioniert es
Gmail erlaubt einen Benachrichtigungskanal pro Postfach und veröffentlicht jede Änderung in deinem Topic. Eine Benachrichtigung enthält nur die Postfachadresse und eine Änderungsmarke, niemals E-Mail-Inhalte. Pub/Sub sendet sie an Langdock, signiert mit deinem Dienstkonto. Langdock prüft Signatur und Endpunkt, danach ruft jeder abonnierte Trigger die Änderungen mit seiner eigenen Gmail-Verbindung ab. Ein Trigger sieht also nur E-Mails, die seine Verbindung lesen kann. Du brauchst nur ein Topic, ein Dienstkonto und eine Push-Subscription pro OAuth-Client. Wenn du mehrere Google OAuth-Clients hast, zeigt jeder seinen eigenen Push-Endpunkt und braucht eine eigene Push-Subscription. Liegen sie im selben Projekt, können sie sich ein Topic und ein Dienstkonto teilen.Berechtigungen
Füge diese Scopes zu deinem Zustimmungsbildschirm hinzu. Langdock fragt die Scopes an, die die in deinem Workspace aktivierten Aktionen brauchen. Mehr dazu unter Action-Level-Scopes verwalten.Fehlerbehebung
Ein Webhook-Trigger lässt sich nicht aktivieren
Ein Webhook-Trigger lässt sich nicht aktivieren
Prüfe, ob im Abschnitt Webhook-Trigger des OAuth-Clients sowohl das Topic als auch das Dienstkonto eingetragen sind und ob die Verbindung mit diesem OAuth-Client erstellt wurde. Verbindungen bleiben mit dem Client verknüpft, mit dem sie erstellt wurden.Prüfe außerdem, ob das Topic im selben Google Cloud-Projekt liegt wie der OAuth-Client und ob
gmail-api-push@system.gserviceaccount.com darauf die Rolle Pub/Sub Publisher hat.Der Trigger ist aktiv, aber Workflows starten nie
Der Trigger ist aktiv, aber Workflows starten nie
Öffne die Push-Subscription in der Google Cloud Console und prüfe die Antwortcodes unter Metrics → Push:
401: Die Subscription hat die Authentifizierung deaktiviert, nutzt ein anderes Dienstkonto als das in Langdock gespeicherte oder hat eine Audience gesetzt.403: Eine Firewall, eine WAF oder ein Proxy vor Langdock blockiert die Anfragen von Google. ErlaubePOST-Anfragen an/api/webhook-pubsub/. Langdock prüft die Signatur jeder Anfrage selbst.404: Die Endpunkt-URL stimmt nicht mit dem Push-Endpunkt in Langdock überein, oder der OAuth-Client hat keine Webhook-Trigger-Einstellungen.