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 Agenten 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 hinzufügen, 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 Agenten 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
Was ist ein API-Schlüssel? Ein API-Schlüssel ist ein eindeutiger Identifikationscode, der zur Authentifizierung von Anfragen an eine API verwendet wird. Ähnlich wie ein Passwort autorisiert er den Zugriff auf externe Dienste.
data.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
Was ist OAuth 2.0? OAuth 2.0 ist ein Autorisierungsprotokoll, das es Anwendungen ermöglicht, sicheren Zugriff auf Nutzerdaten von anderen Services zu erhalten, ohne dass Passwörter weitergegeben werden müssen.
Client-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 Agenten, 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
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”
- 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
Der Trigger-Builder unterstützt aktuell nur Polling-Trigger. Webhook-Trigger (REST_HOOK) sind über die API verfügbar, aber noch nicht im Trigger-Builder-UI sichtbar.
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 Agenten-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 Agenten, 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 Agenten, 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.{fieldSlug} für Eingabefeldwerte und data.auth.{fieldSlug} für Authentifizierungsfeldwerte aus der aktuellen Verbindung des Nutzers. Der Slug ist der Bezeichner, den du beim Erstellen jedes Feldes im Integrations-Builder festlegst.
Integrierte Funktionen für benutzerdefinierte Code-Abschnitte
Benutzerdefinierte Code-Abschnitte haben Zugriff auf eine Reihe von integrierten Utility-Funktionen für gängige Operationen. Hier sind die am häufigsten verwendeten:Wesentliche Funktionen
ld.request()- HTTP-Anfragen an externe APIs ausführenld.log()- Debugging-Informationen ausgebenatob()/btoa()- Base64-Encoding/-DecodingJSON.stringify()/JSON.parse()- JSON-Manipulation
Vollständige Sandbox-Utilities-Referenz
Sieh dir alle verfügbaren Sandbox-Utilities an, einschließlich Datenkonvertierungen (CSV, Parquet, Arrow), SQL-Validierung, Kryptographie, AWS-Request-Signing, Microsoft XMLA-Integration und mehr.
Schnelle Beispiele
HTTP-AnfrageSandbox-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 Agenten 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 Agenten 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 Agenten, 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
FAQ
Wann sollte ich eine benutzerdefinierte Integration erstellen?
Wann sollte ich eine benutzerdefinierte Integration erstellen?
Erstelle eine benutzerdefinierte Integration, wenn Langdock mit einem Tool oder einer API verbunden werden soll, die keine bestehende Integration abdeckt. Sie eignet sich am besten für wiederholbare Aktionen, den Abruf strukturierter Daten und Workflows, bei denen Nutzer Daten nicht manuell zwischen Systemen kopieren sollen.
Was sollte ich prüfen, wenn eine benutzerdefinierte Integration nicht wie erwartet funktioniert?
Was sollte ich prüfen, wenn eine benutzerdefinierte Integration nicht wie erwartet funktioniert?
Prüfe die Authentifizierung, die Endpunkt-URLs, die Request-Methoden, erforderliche Header, das Eingabeschema, das Ausgabeschema und ob die externe API die erwartete Antwort liefert. Teste zuerst eine einzelne Aktion mit einfachen Eingaben, bevor du komplexe Logik hinzufügst.