Integrationen vs. Aktionen vs. Trigger
Integrationen sind standardisierte Verbindungen zwischen Langdock und Drittanbieter-Tools, die Authentifizierung und API-Kommunikation verwalten. Innerhalb jeder Integration kannst du Folgendes erstellen:- Aktionen: Funktionen, die Assistenten und Workflows aufrufen können, um mit APIs zu interagieren (z.B. “Ticket erstellen”, “E-Mail senden”, “Daten abrufen”)
- Trigger: Event-Monitore, die Workflows starten, wenn bestimmte Ereignisse auftreten (z.B. “neue E-Mail erhalten”, “Datei hochgeladen”)
Eine Integration einrichten
Klicke im Integrationsmenü aufIntegration erstellen
, um zu beginnen.
Gib als Nächstes einen Integrationsnamen an und lade ein Icon hoch (wird im Chat bei der Verwendung von Aktionen und in der Integrationsübersicht angezeigt). Füge eine Beschreibung hinzu, damit Assistenten wissen, wann sie diese Integration verwenden sollen. Klicke auf Speichern
, um sie zu erstellen.
Authentifizierung
Beginne mit der Authentifizierung im TabErstellen
. Wähle deinen Authentifizierungstyp und konfiguriere ihn gemäß den folgenden Schritten:
API-Schlüssel
Nach der Auswahl der API-Schlüssel-Authentifizierung füge in Schritt 2 benutzerdefinierte Eingabefelder hinzu (wie API-Schlüssel oder Client-ID). Diese Eingaben werden erfasst, wenn Nutzer Verbindungen einrichten und können als “erforderlich” markiert werden. In Schritt 3 kannst du einen Test-API-Endpunkt einrichten, um die Authentifizierung zu validieren. Ersetze den URL-Parameter und füge Verweise auf deine Eingabefelder mitdata.auth.fieldId
hinzu.
Verwende die integrierten Funktionen ld.request
und ld.log
für Anfragen und Protokollierung.
Teste deine Aktion und erstelle deine erste Verbindung.
OAuth 2.0
Nutzerdefinierte Integrationen unterstützen OAuth 2.0-Authentifizierung. Schritt 2 ermöglicht benutzerdefinierte Eingabefelder (die beim Einrichten der Verbindung erfasst werden). Client-ID und Client-Secret werden in Schritt 4 eingegeben, daher deckt dies nur zusätzliche Parameter ab. OAuth-Client erstellen Richte einen OAuth-Client/App/Projekt in deiner Zielanwendung ein und aktiviere die erforderlichen APIs. Dies ist anwendungsspezifisch, weshalb unsere Oberfläche benutzerdefinierten Code in Schritt 5 unterstützt. Für Google Calendar: Erstelle ein Google Service-Konto, generiere einen neuen Schlüssel, um dieClient-ID
und das Secret zu erhalten, füge sie in Schritt 4 zu Langdock hinzu, speichere die OAuth Redirect URL
und aktiviere die Google Calendar API.
Autorisierungs-URL ändern
Überprüfe die OAuth-Dokumentation für deinen Service und extrahiere die Autorisierungs-URL
. Normalerweise reicht es aus, die BASE_URL
in unserer Vorlage zu ändern.
Für Google Calendar:
Access Token URL
und Refresh Token URL
. Normalerweise funktioniert es, die tokenUrl
in unserer Vorlage zu aktualisieren.
Für Google Calendar:
const tokenUrl ='https://oauth2.googleapis.com/token';
Authentifizierungs-Setup testen
Stelle einen Test-API-Endpunkt (wie /me
) bereit, um die Authentifizierung zu verifizieren. Der Rückgabewert dieser Testanfrage kann innerhalb des OAuth Client Labels verwendet werden, um die Benennung der hergestellten Verbindungen zu beeinflussen. Du kannst auf den Rückgabewert über {{data.input}}
zugreifen.
Für Google Calendar: Google Sheets - {{data.input.useremail.value}}
Teste, indem du eine Verbindung hinzufügst und verifizierst, dass der Autorisierungsablauf funktioniert.
Für Google Calendar testen wir mit:
Öffentliche APIs
WähleKeine
für öffentlich verfügbare APIs ohne Authentifizierung.
Aktionen erstellen
Aktionen ermöglichen es Assistenten, mit deinen API-Endpunkten zu interagieren. Es gibt zwei Arten von Aktionen:- Reguläre Aktionen: Standard-API-Interaktionen (Erstellen, Lesen, Aktualisieren, Löschen)
- Native Aktionen: Spezielle Dateisuche- und Download-Aktionen, die in das Langdock-Dateisystem integriert sind
Reguläre Aktionen
Reguläre Aktionen sind der häufigste Typ und verarbeiten Standard-API-Operationen.Wann du reguläre Aktionen erstellen solltest
- CRUD-Operationen: Daten über API-Aufrufe erstellen, lesen, aktualisieren oder löschen
- Datenverarbeitung: Daten zur Analyse, Transformation oder Validierung an APIs senden
- Dateioperationen: Dateien zu Services hochladen, Dokumente verarbeiten, Anhänge senden
- Benachrichtigungen: E-Mails, Nachrichten senden oder Tickets erstellen
- Integrationen: Mehrere Services verbinden oder Daten zwischen Plattformen synchronisieren
Reguläre Aktionen einrichten
- Aktion hinzufügen: Klicke in deiner Integration auf “Aktion hinzufügen”
- Grundlegende Informationen konfigurieren: Name, Beschreibung und Slug festlegen
- Eingabefelder hinzufügen: Definiere, welche Daten die Aktion von Nutzern benötigt
- Aktionscode schreiben: Implementiere die API-Interaktionslogik
- Testen: Validiere, dass deine Aktion korrekt funktioniert
Eingabefeldtypen
Typ | Zweck | Hinweise |
---|---|---|
TEXT | Kurze Texteingabe | Einzeiliger Text |
MULTI_LINE_TEXT | Lange Texteingabe | Mehrere Zeilen, gut für Beschreibungen |
NUMBER | Numerische Eingabe | Ganze Zahlen oder Dezimalzahlen |
BOOLEAN | Wahr/Falsch-Toggle | Checkbox-Eingabe |
SELECT | Dropdown-Optionen | Vordefinierte Auswahlmöglichkeiten |
FILE | Datei-Upload | Einzelne oder mehrere Dateien (siehe Dateiunterstützungs-Guide) |
OBJECT | Komplexe Daten | JSON-Objekte mit benutzerdefiniertem Schema |
PASSWORD | Sensibler Text | Versteckte Eingabe für Geheimnisse |
Beispiel: Ticket-Erstellungsaktion
Datei-Upload-Beispiel
Dateien von Aktionen zurückgeben
Aktionen können auch Dateien generieren und zurückgeben:Trigger erstellen
Trigger überwachen externe Systeme auf Ereignisse und können Workflows automatisch starten.Wann du Trigger erstellen solltest
- Event-Überwachung: Neue E-Mails, Dateien, Datensätze oder Änderungen erkennen
- Workflow-Automatisierung: Prozesse starten, wenn bestimmte Ereignisse auftreten
- Datensynchronisierung: Systeme durch Erkennung von Änderungen synchron halten
- Benachrichtigungen: Auf externe Ereignisse reagieren und Nutzer benachrichtigen
Trigger-Typen
- Polling-Trigger: APIs regelmäßig auf neue Ereignisse überprüfen
- Webhook-Trigger: Echtzeit-Benachrichtigungen von externen Systemen empfangen
Polling-Trigger einrichten
- Trigger hinzufügen: Klicke in deiner Integration auf “Trigger hinzufügen”
- Typ auswählen: Wähle “Polling”
- Einstellungen konfigurieren: Name, Beschreibung und Polling-Intervall festlegen
- Eingabefelder hinzufügen: Konfigurationsparameter definieren (optional)
- Trigger-Code schreiben: Die Polling-Logik implementieren
- Testen: Validiere, dass dein Trigger Ereignisse korrekt erkennt
Erforderliches Rückgabeformat
Trigger müssen ein Array von Ereignissen mit dieser Struktur zurückgeben:Beispiel: Neue E-Mail-Trigger
Trigger mit Dateianhängen
Wenn Trigger Ereignisse mit Dateien erkennen, füge sie in das Datenobjekt ein:Webhook-Trigger einrichten
- Trigger hinzufügen: Wähle den Typ “Webhook”
- Endpunkt konfigurieren: Notiere dir die bereitgestellte Webhook-URL
- Externes System einrichten: Konfiguriere deinen Service, um Ereignisse an die Webhook-URL zu senden
- Verarbeitungscode schreiben: Eingehende Webhook-Daten transformieren (optional)
- Testen: Sende Testereignisse, um die Funktionalität zu verifizieren
Webhook-Verarbeitungsbeispiel
Native Aktionen
Native Aktionen ermöglichen es dir, Dateien nativ zu suchen und herunterzuladen, die nicht lokal auf dem Gerät eines Nutzers gespeichert sind. Wir haben bereits native Aktionen für SharePoint, OneDrive, Google Drive und Confluence erstellt. Du kannst über den Button Dateien auswählen darauf zugreifen, um Dateien direkt im Chat oder im Assistenten-Wissen zu suchen und anzuhängen.

Eine native Aktion einrichten
Um eine native Aktion einzurichten, beginne wie gewohnt mit dem Erstellen deiner Integration. Füge eine weitere Aktion hinzu und wähle in Schritt 1 unter Erweitert entweder “Dateien suchen” oder “Datei herunterladen” als Aktionstyp. Danach erstellst du die Aktion wie jede andere Aktion, aber deine Funktion muss eine spezifische Objektstruktur zurückgeben. Dies gewährleistet Kompatibilität und ermöglicht es Assistenten, Dateien und Suchergebnisse korrekt zu verarbeiten.Erforderliches Ausgabeformat
Abhängig von der ausgewählten Aktion muss deine Funktion eine spezifische Objektstruktur zurückgeben. Dies gewährleistet Kompatibilität und ermöglicht es Assistenten, Dateien und Suchergebnisse korrekt zu verarbeiten. Dateien suchen: Beim Erstellen einer nativen Suchintegration muss deine Funktion ein Array von Objekten zurückgeben, die dem folgenden Schema entsprechen:For native download actions, return an object in the following format:
Auf Eingabefelder zugreifen
Verwendedata.input.{inputFieldId}
für Eingabefeldwerte und data.auth.{authenticationFieldId}
für Authentifizierungsfeldwerte aus der aktuellen Verbindung des Nutzers.
Integrierte Funktionen für benutzerdefinierte Code-Abschnitte
Verwende unseren Integrations-Assistenten, um dir beim Einrichten
deiner Integrationsfunktionen zu helfen.
Grundlegende Funktionen
Die benutzerdefinierte Client-Bibliothek ld enthält die Kernfunktionalität, die für die Implementierung von Authentifizierungsabläufen benötigt wird.ld.request()
erstellt eine Webanfrage im Format des übergebenen Objekts und gibt die Antwort zurück. Die Parameter müssen gültige JSON-Objekte sein, da intern JSON.stringify()
aufgerufen wird. Für komplexe JSON-Objekte musst du zuerst JSON.parse()
anwenden.
ld.log()
gibt die übergebenen Werte im Logs-Feld aus, das nach dem Ausführen einer Aktion unter dem Button Aktion testen
erscheint.
Beispielverwendung aus der Google Calendar-Integration:
JSON
SowohlJSON.stringify()
(Konvertierung eines JavaScript-JSON-Objekts in einen String) als auch JSON.parse()
(Konvertierung eines Strings in ein JavaScript-JSON-Objekt) sind in benutzerdefinierten Code-Blöcken verfügbar.
Die an die Funktion ld.request()
übergebenen Parameter müssen gültige JSON-Objekte sein, da intern JSON.stringify()
aufgerufen wird. Für komplexe JSON-Strukturen musst du vorher JSON.parse()
anwenden, um eine korrekte Formatierung sicherzustellen.
Beispielverwendung aus der HubSpot-Integration:
Base 64
Da einige OAuth-Clients Base64-codierte Client-Anmeldedaten für die Basic-Authentifizierung benötigen, haben wir eine Hilfsfunktion dafür erstellt.btoa()
codiert einen String in Base64, während atob()
einen Base64-String zurück in Klartext decodiert.
Beispielverwendung:
Sandbox-Bibliotheksbeschränkungen
Nutzerdefinierter Integrationscode läuft in einer sicheren Sandbox-Umgebung.
Du kannst keine externen Bibliotheken installieren oder importieren (npm, pip usw.) – nur eine begrenzte Anzahl integrierter JavaScript/Node.js-APIs ist verfügbar.
Für erweiterte Verarbeitung (z.B. PDF-Parsing, Bildbearbeitung) verwende externe APIs oder Services und rufe sie aus deinem Integrationscode auf.
Best Practices
Aktionsdesign
- Einzelne Verantwortlichkeit: Jede Aktion sollte eine Sache gut machen
- Klare Benennung: Verwende beschreibende Aktionsnamen, die den Zweck erklären
- Eingabevalidierung: Validiere immer erforderliche Eingaben und gib hilfreiche Fehlermeldungen aus
- Fehlerbehandlung: Fange API-Fehler ab und behandle sie angemessen
- Protokollierung: Verwende
ld.log()
zur Unterstützung beim Debugging
ID-Verwaltung
Die meisten API-Aufrufe erfordern spezifische interne IDs. Die Herausforderung besteht darin, dass Assistenten diese IDs nicht erraten können, was zu einer schlechten Nutzererfahrung führt, wenn Aktionen wie “spezifischen Kontakt in HubSpot abrufen” oder “Ereignis zu spezifischem Kalender in Google Calendar hinzufügen” aufgerufen werden. Die Lösung: Erstelle Hilfsaktionen, die diese IDs zuerst abrufen und an den Assistenten zurückgeben. Beispielsweise verwendet unsere FunktionDeal-Kontext abrufen
für HubSpot GET-Endpunkte, um interne IDs für verfügbare Pipelines und Phasen zu sammeln. Dies ermöglicht es Assistenten, Aktionen wie Deal erstellen
oder Deal aktualisieren
viel effektiver zu nutzen, da sie nun den erforderlichen Kontext haben.
Performance
- API-Aufrufe minimieren: Batch-Operationen verwenden, wenn möglich
- Paginierung verwenden: Große Datensätze angemessen verarbeiten
- Timeout-Behandlung: Angemessene Timeouts für externe API-Aufrufe setzen
Sicherheit
- Eingaben validieren: Vertraue niemals Nutzereingaben ohne Validierung
- Daten bereinigen: Bereinige Daten, bevor du sie an externe APIs sendest
- Geheimnisse verwalten: Verwende Authentifizierungsfelder für sensible Daten, niemals hartcodieren
- Rate Limiting: Respektiere API-Rate-Limits und implementiere Backoff-Strategien