Nutzerdefinierte Integrationen ermöglichen es dir, jedes API-fähige Tool mit einem Assistenten zu verbinden. Dies eröffnet dir unendliche Möglichkeiten. Unten findest du eine umfassende Anleitung zum Erstellen von Integrationen, Aktionen und Triggern.
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”)
Klicke im Integrationsmenü auf Integration 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.
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.
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 mit 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.
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.
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 erstellenRichte 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 die 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:
Scopes definierenDefiniere die OAuth-Scopes, die deine Aktionen benötigen. Liste sie komma- oder leerzeichengetrennt gemäß deiner API-Dokumentation auf.Für Google Calendar (leerzeichengetrennt):
Access Token & Refresh Token URL bereitstellenÜberprüfe die OAuth-Dokumentation deiner API für die 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 testenStelle 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:
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.Dateien mit nativen Integrationen an den Chat anhängen.Dateien mit einer nativen Integration an das Assistenten-Wissen anhängen.Das Erstellen nativer Aktionen für andere Tools ermöglicht es dir, Dateien von diesen Plattformen auf die gleiche Weise zu suchen und herunterzuladen.
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.
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:
Der title und mimeType werden in der Nutzeroberfläche für alle Suchergebnisse angezeigt.Bitte sieh dir auch eine detaillierte Beschreibung für jeden Parameter an:
Die Web-URL, unter der Nutzer die Datei anzeigen oder bearbeiten können. Dies sollte ein direkter Link sein, der die Datei in der Quellanwendung öffnet (z.B. Google Docs Editor, SharePoint Viewer). Muss eine gültige HTTPS-URL sein, auf die der Nutzer mit seinen Anmeldedaten zugreifen kann.
documentId
string
Der eindeutige Identifikator der Datei im Quellsystem. Diese ID wird intern zur Referenzierung der Datei verwendet und sollte bei Suchen stabil bleiben. Kann jedes String-Format sein (UUID, numerische ID, etc.), solange es die Datei eindeutig identifiziert.
title
string
Der Anzeigename der Datei. Das ist, was Nutzer in den Suchergebnissen sehen werden. Sollte die Dateierweiterung enthalten, falls relevant (z.B. “Bericht.pdf”, “Budget.xlsx”).
mimeType
string
Der MIME-Typ der Datei. Wird verwendet, um das Dateityp-Icon und die Kategorie zu bestimmen. Häufige Werte sind: application/pdf, application/vnd.google-apps.document, application/vnd.openxmlformats-officedocument.wordprocessingml.document, text/plain, etc.
Informationen über denjenigen, der die Datei erstellt hat. Hilft Nutzern, Dateieigentümerschaft und Herkunft zu identifizieren.
author.id
string
Eindeutiger Identifikator des Autors. Normalerweise eine E-Mail-Adresse oder Nutzer-ID im Quellsystem.
author.name
string
Anzeigename des Autors. Der für Menschen lesbare Name, der Nutzern angezeigt wird (z.B. “Max Mustermann”).
lastSeenByUser
string
Wann der aktuelle Nutzer diese Datei zuletzt angesehen hat. ISO 8601 Datumsstring (z.B. “2024-01-15T10:30:00Z”). Wird für die Sortierung “Kürzlich angesehen” verwendet. Gib null zurück oder lass es weg, wenn der Nutzer die Datei nie angesehen hat.
createdDate
string
Wann die Datei ursprünglich erstellt wurde. ISO 8601 Datumsstring. Hilft Nutzern, das Alter der Datei zu verstehen und nach Erstellungsdatum zu sortieren.
lastModifiedByAnyone
string
Wann die Datei zuletzt von irgendeinem Nutzer geändert wurde. ISO 8601 Datumsstring. Wichtig zur Identifikation kürzlich aktualisierter Inhalte und kollaborativer Arbeit.
lastModifiedByUserId
object
Informationen darüber, wer die Datei zuletzt geändert hat. Hilft beim Verfolgen kürzlicher Änderungen in kollaborativen Umgebungen. Das gesamte Objekt sollte weggelassen werden, wenn ein erforderliches Unterfeld fehlt.
lastModifiedByUserId.id
string
Eindeutiger Identifikator des letzten Bearbeiters. Normalerweise eine E-Mail oder Nutzer-ID.
lastModifiedByUserId.name
string
Anzeigename des letzten Bearbeiters. Für Menschen lesbarer Name desjenigen, der die letzten Änderungen vorgenommen hat.
lastModifiedByUserId.lastModifiedByUserIdDate
string
Zeitstempel der letzten Änderung. ISO 8601 Datumsstring. Stimmt normalerweise mit lastModifiedByAnyone überein.
parent
object
Informationen über den Speicherort/Container der Datei. Hilft Nutzern, die Dateiorganisation zu verstehen und zu übergeordneten Ordnern zu navigieren.
parent.id
string
Eindeutiger Identifikator des übergeordneten Ordners/Containers. Wird für ordnerbasierte Operationen und Navigation verwendet.
parent.title
string
Anzeigename des übergeordneten Ordners. Wird angezeigt, um Nutzern zu helfen, den Dateistandort zu verstehen (z.B. “Marketing-Materialien”, “Q1 Berichte”).
parent.url
string
Web-URL zum Anzeigen des übergeordneten Ordners. Direkter Link zum Öffnen des Ordners in der Quellanwendung.
parent.type
string
Typ des übergeordneten Containers. Optionale Klassifizierung (z.B. “folder”, “workspace”, “site”).
parent.driveId
string
Identifikator des Laufwerks/der Bibliothek, die die Datei enthält. Für Services mit mehreren Speicherorten (z.B. SharePoint-Sites, Google Shared Drives).
parent.siteId
string
Identifikator der Site, die die Datei enthält. Spezifisch für SharePoint und ähnliche Plattformen mit sitebasierter Organisation.
parent.listId
string
Identifikator der Liste, die die Datei enthält. Für listenbasierte Speichersysteme.
parent.listItemId
string
Identifikator des Listenelements, das mit der Datei verbunden ist. Für Dateien, die an Listenelemente angehängt sind.
contentPreview
string
Ein Textausschnitt aus dem Dateiinhalt. Bietet Kontext über Dateiinhalte in Suchergebnissen. Sollte Klartext sein, normalerweise 100-200 Zeichen. Nützlich zum Anzeigen relevanter Ausschnitte, die zu Suchanfragen passen. Setze auf null, wenn keine Inhaltsvorschau verfügbar ist.
Datum:
Alle Datumsfelder müssen gültige ISO 8601 Strings sein oder vollständig weggelassen werden. Ungültige Daten verursachen Parsing-Fehler.Null vs. Weggelassen:
Verwende null für Felder, die explizit leer sind (z.B. keine Inhaltsvorschau verfügbar)
Lass Felder vollständig weg, wenn die Daten nicht anwendbar oder nicht verfügbar sind
Übergeordnete Informationen: Füge so viele übergeordnete Informationen wie verfügbar hinzu, um Nutzern bei der Navigation in Dateihierarchien zu helfen
Autor-Informationen: Füge immer sowohl ID als auch Name in Autor-Objekten hinzu, oder lass das gesamte Objekt weg
Suchrelevanz: Felder wie contentPreview können die Such-UX erheblich verbessern, indem sie zeigen, warum eine Datei zur Anfrage passt
Below you can find an example implementation for the native SharePoint Search files action.
Der vollständige Dateiname inklusive Erweiterung. Das ist der Name, der beim Speichern der Datei verwendet wird. Sollte dem ursprünglichen Dateinamen aus dem Quellsystem entsprechen (z.B. “Budget_2024.xlsx”, “Design_Final.pdf”). Wenn die Datei im Quellsystem keine Erweiterung hat, füge die passende basierend auf mimeType hinzu.
mimeType
string
Ja
Der MIME-Typ, der das Dateiformat identifiziert. Bestimmt, wie die Datei verarbeitet wird und welches Icon angezeigt wird. Muss ein gültiger MIME-Typ sein (z.B. “application/pdf”, “image/png”, “text/plain”). Für Google Workspace-Dateien verwende den ursprünglichen MIME-Typ, nicht den des exportierten Formats.
buffer
Buffer
Bedingt
Der binäre Inhalt der Datei als Buffer. Erforderlich für Binärdateien (PDFs, Bilder, Office-Dokumente). Die eigentlichen Dateidaten, die gespeichert werden. Kann bereitgestellt werden als: natives Buffer-Objekt, base64-kodierter String oder Objekt mit Format type:“Buffer”, data: [Byte-Array].
url
string
Ja
Die Web-URL zum Anzeigen/Bearbeiten der Datei in ihrer Quellanwendung. Sollte ein direkter Link sein, der die Datei beim Klicken öffnet (z.B. Google Drive Viewer URL, SharePoint Dokument-URL). Wird verwendet, damit Nutzer auf die ursprüngliche Datei zugreifen können und zur Referenzverfolgung.
lastModified
string/Date
Ja
ISO 8601 Zeitstempel der letzten Änderung der Datei. Zeigt an, wann der Dateiinhalt zuletzt geändert wurde. Kann ein Date-Objekt oder ISO-String wie “2024-01-15T10:30:00Z” sein. Wird für Versionsverfolgung und Bestimmung der Dateiaktualität verwendet.
data
any
Nein
Rohe Antwortdaten aus dem API-Aufruf. Optionales Feld, das zusätzliche Metadaten aus dem Quellsystem enthalten kann. Das ist normalerweise die rohe JSON-Antwort und wird zum Debugging oder Zugriff auf zusätzliche Eigenschaften verwendet, die nicht anderen Feldern zugeordnet sind. Wird vom System nicht verarbeitet.
text
string
Bedingt
Der Textinhalt der Datei als UTF-8-String. Erforderlich für textbasierte Dateien anstelle von buffer. Verwende für Klartext, HTML, JSON, CSV oder jedes für Menschen lesbare Format. Sollte den vollständigen Dateiinhalt enthalten. Kann nicht zusammen mit buffer verwendet werden.
Inhaltsfelder: Du musst entweder buffer ODER text bereitstellen, niemals beides:
Verwende buffer für: Bilder, PDFs, Office-Dokumente, Videos, jedes Binärformat
Verwende text für: Klartext, HTML, Quellcode, JSON, XML, jedes TextformatData-Feld: Das data-Feld ist optional und enthält normalerweise die rohe API-Antwort. Es wird vom Kernsystem nicht verwendet, kann aber hilfreich sein für:
Verwende data.input.{inputFieldId} für Eingabefeldwerte und data.auth.{authenticationFieldId} für Authentifizierungsfeldwerte aus der aktuellen Verbindung des Nutzers.
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:
Sowohl JSON.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:
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:
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.
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 Funktion Deal-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.