Daten-Connectoren ermöglichen es Fin, über API-Endpunkte mit externen Systemen zu interagieren. Fin kann Daten-Connectoren verwenden, um:

Live-Daten aus einem externen System zu lesen und im Verfahren zu verwenden (z. B. prüfen, welchen Plan ein Kunde hat, den Bestellstatus abrufen oder Kontodetails einsehen).
Zurückschreiben in ein externes System, indem Aktionen während des Gesprächs ausgeführt werden (z. B. ein Abonnement kündigen, einen Datensatz aktualisieren oder eine Rückerstattung über POST-, PUT-, PATCH- oder DELETE-Anfragen verarbeiten).

Wenn ein Daten-Connector innerhalb eines Verfahrens ausgeführt wird, steht die Antwort Fin als temporärer Kontext für die Dauer dieses Gesprächs zur Verfügung – sie wird nicht automatisch in einem Kontakt- oder Gesprächsattribut gespeichert. Wenn Sie die Daten dauerhaft in Intercom speichern möchten (z. B. in einem benutzerdefinierten Kontaktattribut oder Custom Object), müssen Sie die Objektzuordnung in der Connector-Konfiguration einrichten.

Loslegen

Einen Daten-Connector zu einem Anweisungsschritt hinzufügen

Geben Sie in einem Anweisungsschritt @ ein, um das Werkzeugmenü zu öffnen.
Wählen Sie Daten-Connector aufrufen.
Wählen Sie den spezifischen Connector aus, den Sie ausführen möchten (z. B. Bestellungen abrufen, um die Kaufhistorie eines Kunden abzurufen).

Tipp: Erfahren Sie, wie Sie Daten-Connectoren einrichten, um Live-Informationen aus Ihren internen Systemen oder Drittanbieter-APIs direkt in Ihre Fin Procedures zu ziehen.

Zugriff auf die Antwort über automatisch generierte Attribute

Sobald ein Connector hinzugefügt wurde, können Sie die Antwort sofort in nachfolgenden Schritten nutzen. Diese steht Fin allgemein als Kontext zur Verfügung, aber wir parsen auch die Antwortfelder in Daten-Connectoren, damit Sie explizit auf Elemente im Antwortkörper für höchste Zuverlässigkeit verweisen können.

Hinweis: Eine Antwortzuordnung ist bei der Verwendung von Daten-Connectoren in Procedures nicht erforderlich. Fin verwendet die Testantwort, die Sie im Daten-Connector konfigurieren, um die Struktur der API-Antwort zu verstehen – die verfügbaren Feldnamen und deren Typen. Sie können dann in Ihren Verfahrensanweisungen in einfacher Sprache angeben, welche Daten aus der Antwort verwendet werden sollen. Zur Laufzeit macht Fin einen Live-API-Aufruf und liest die echten Werte aus diesen Feldern.

Geben Sie @ ein und wählen Sie Attribut lesen.
Sie sehen die Antwortfelder des Daten-Connectors automatisch oben im Dropdown-Menü aufgelistet (z. B. Bestellung abrufen > Status, Bestellung abrufen > order_id).
Wählen Sie das spezifische Attribut aus, das Sie in Ihre Anweisung oder Bedingung einfügen möchten.

Der Kontext wird im gesamten Verfahren geteilt

Wenn Sie Fin anweisen, einen Daten-Connector zu verwenden (@ use data connector), werden die zurückgegebenen Daten im gesamten Verfahren verfügbar.

Für mehr Zuverlässigkeit können Sie auf diese Daten mit (@ read attributes) zugreifen. Fin behält Connector-Daten für die gesamte Dauer eines Verfahrens, einschließlich aller Schritte und Unterverfahren. Sie müssen jeden Connector nur einmal pro Verfahren aufrufen, es sei denn, Sie benötigen explizit aktualisierte Daten.

Wenn Sie beispielsweise (@ use Get_Subscription_info) im ersten Schritt aufrufen, behält Fin den Abonnement-Kontext des Kunden für alle nachfolgenden Schritte und Unterverfahren.

Best Practices

Nutzen Sie Mock-Daten-Connectoren, um Ihre Verfahren zu testen und aufzubauen.

Sie benötigen keine vollständig funktionierende Live-API, um Verfahren zu erstellen. Sie können Beispielantworten verwenden, um Daten zu simulieren.

Beispielantwort: Wählen Sie in der Daten-Connector-Konfiguration (unter dem Tab „Test response“) Beispielantwort aus und fügen Sie eine Mock-JSON-Nutzlast ein. So können Sie den Verfahrensablauf sofort erstellen und testen.
Dynamisches Mocking: Für komplexere Szenarien können Sie Tools wie Beeceptor verwenden, um dynamische API-Antworten zu simulieren.

Optimieren Sie Ihre API-Antworten so, dass sie die kleinstmögliche Teilmenge relevanter Daten enthalten, die Fin für das Verfahren benötigt.

Zu viele irrelevante Daten können die Leistung beeinträchtigen. Generell gilt: Je kleiner und präziser, desto besser.

Wenn eine Datenumwandlung erforderlich ist, wird dringend empfohlen, die Daten entweder durch Auswahl einer begrenzten Anzahl von Feldern oder durch Verwendung von Daten-Connector-Codeblöcken zu transformieren. Dies transformiert die API-Antwort, bevor Fin sie im Verfahren sieht.

Optimieren Sie, nicht mehr als einen Daten-Connector pro Schritt zu verwenden.

Ein Schritt soll eine einzelne Arbeitseinheit sein. Fin ist am zuverlässigsten, wenn Sie in einem Schritt nur einen Daten-Connector aufrufen.

Daten-Connectoren einmal pro Kontext aufrufen

In Procedures bezeichnet „Kontext“ den gesamten Ablauf des Verfahrens. Fin verwendet Connector-Daten automatisch in allen Schritten und Unterverfahren wieder. Sie müssen dieselbe API nicht zweimal aufrufen.

❌ Es ist nicht notwendig, denselben Connector in mehreren Schritten aufzurufen:

Step 1: 

… (@use Get_Subscription_info) … and include @read plan status in your response so the users knows 

Step 2 

… (@use Get_Subscription_info) …  and include @read refund eligibility in your response so the users knows

✅ Es ist einfacher, sauberer und schneller, den Connector nur einmal aufzurufen:

Step 1: 

… (@use Get_Subscription_info) … include @read plan status in your response so the users knows 

Step 2 

… include @read refund eligibility in your response so the users knows

Wenn Sie Daten aus mehreren Systemen benötigen, verteilen Sie die Logik auf mehrere Schritte, anstatt mehrere Connectoren in einem Schritt aufzurufen.

Es ist nicht nötig, Fin zu bitten, Daten zu sammeln, die bereits als erforderliche Eingaben für einen Daten-Connector konfiguriert sind.

Eingaben sind während der Daten-Connector-Einrichtung vorkonfiguriert, sodass Fin die benötigten Eingaben automatisch ableitet, ohne dass Sie Fin explizit auffordern müssen, diese Daten zu sammeln.

Wenn beispielsweise der Daten-Connector Get Order Details bereits das Eingabefeld E-Mail konfiguriert hat:

❌ Unnötig komplexe Anweisung:

First ask the customer for their email, then call @get_order_details with that email

✅ Klare Anweisungen:

Call @get_order_details

Fin leitet die erforderlichen Eingaben basierend auf der Connector-Konfiguration automatisch ab und sammelt sie, sofern die Eingabe nicht bereits direkt von Intercom bereitgestellt wird.

Hinweis: Wenn Sie Leistungs- oder Zuverlässigkeitsprobleme bei der Eingabesammlung bemerken, können Sie Fin explizit anweisen, wann diese Daten gesammelt werden sollen.

Profi-Tipp: Wenn ein Verfahren genaue, unveränderte oder sichere Daten benötigt (z. B. E-Mail, Benutzer-ID oder Kontoinformationen), injizieren Sie diese Werte direkt von Intercom in den Connector. Durch die direkte Konfiguration des Attributs im Connector anstelle einer von Fin gesammelten Eingabe umgeht die Daten die Sammlung oder Verarbeitung durch Fin vollständig und bleiben unverändert.

Verwenden Sie temporäre Attribute als deterministische Eingaben für Daten-Connectoren.

Sie können jetzt ein temporäres Attribut als Eingabequelle für einen Daten-Connector-Parameter auswählen. Wenn ein temporäres Attribut als Eingabe zugeordnet ist, überspringt Fin jegliche Attributabruf-Logik und verwendet direkt den Wert des temporären Attributs – keine Ableitung, keine Kundenabfrage, kein Fallback.

Dies ist nützlich, wenn ein früherer Verfahrensschritt einen Wert sammelt oder setzt (z. B. über eine Aktualisierung: Temporäres Attribut-Aktion) und Sie sicherstellen möchten, dass genau dieser Wert an den Connector übergeben wird.

Um dies zu konfigurieren, öffnen Sie den Daten-Connector-Schritt in Ihrem Verfahren, suchen Sie den Eingabeparameter, den Sie zuordnen möchten, klicken Sie auf das Dropdown-Menü Quelle und wählen Sie das temporäre Attribut aus der Liste aus.

Wichtig: Wenn das temporäre Attribut vor Ausführung des Daten-Connector-Schritts nicht gesetzt wurde, zeigt Fin einen Fehler in den Gesprächsereignissen an. Stellen Sie sicher, dass ein vorheriger Schritt im Verfahren das Attribut setzt, bevor der Connector aufgerufen wird.

Überwachung der Connector-Gesundheit

Procedures, die Daten-Connectoren verwenden, zeigen auf der Verfahrenslisten-Seite eine Connector-Probleme-Anzeige, sodass Sie Connector-Probleme auf einen Blick erkennen können, ohne jedes Verfahren zu öffnen. Die Anzeige spiegelt den am schlechtesten performenden Connector wider, der in diesem Verfahren verwendet wird, berechnet über die letzten 14 Tage (maximal 1.000 Ausführungen pro Connector).

Procedures ohne Daten-Connectoren zeigen keine Anzeige; Connectoren mit null Ausführungen gelten als gesund.

Hinweis: Die Erfolgsraten der Daten-Connectoren basieren auf Ihrem ausgewählten Zeitfilter. Nach der Behebung eines Problems müssen Sie möglicherweise auf neue Daten warten oder den Zeitfilter anpassen, um zu bestätigen, dass der Connector erfolgreich ist.

Gesundheitsstatus

Status	Kriterien	Auswirkung
🟡 Verschlechtert	Jeder Connector hat eine Erfolgsrate von 80–95 % oder >95 % Erfolgsrate, aber eine durchschnittliche Antwortgröße ≥50 KB (~15.000 Tokens).	Erlebt Probleme oder liefert große Antworten, die das Risiko von Halluzinationen erhöhen können.
🔴 Ungesund	Jeder Connector hat eine Erfolgsrate von <80 % oder eine durchschnittliche Antwortgröße ≥100 KB (~30.000 Tokens).	Kritische Probleme oder gefährlich große Antworten, die sofortige Aufmerksamkeit erfordern.

Detaillierte Ansicht

Ein Klick auf die Anzeige für Connector-Probleme öffnet ein Panel mit einer Karte pro betroffenem Connector, die dessen Status (Verschlechtert oder Ungesund), Erfolgsrate, Ausführungsanzahl und Antwortgröße zeigt. Connector-Namen verlinken direkt zur Einstellungsseite für schnelles Debugging.

Umgang mit Arrays

Wenn ein Daten-Connector eine Liste zurückgibt, stellt Fin nur das Wurzel-Array als Attribut bereit. Kind-Elemente innerhalb des Arrays werden im Attribut-Auswahlmenü nicht als separate Attribute angezeigt.

Beispielsweise sehen Sie, wenn ein Connector ein items-Array zurückgibt:

Bestellungen abrufen > items

Aber Sie sehen nicht:

Bestellungen abrufen > items > title
Bestellungen abrufen > items > price

Fin kann dennoch mit dem Inhalt einer Liste arbeiten. Wenn Sie beispielsweise die Anweisung geben: „Wenn der Kunde fragt, was in seiner Bestellung ist, verwenden Sie Bestellung abrufen > items, um die Produkte und deren Preise aufzulisten.“

Fin liest dann den gesamten Inhalt der Items-Liste und antwortet mit: „Ihre Bestellung enthält eine Wireless Mouse (24,99 $) und einen Laptopständer (39,99 $).“

Zum Beispiel: Für die untenstehende Antwort-Nutzlast wird nur das Wurzel-Array-Element items als temporäres Attribut bereitgestellt, nicht jedoch dessen Kinder.

{
  "order_id": "ORD-1001",
  "status": "processing",
  "created_at": "2025-01-12T14:23:00Z",
  "items": [
    {
      "product_id": "PROD-200",
      "name": "Wireless Mouse",
      "quantity": 1,
      "unit_price": 24.99
    },
    {
      "product_id": "PROD-122",
      "name": "Laptop Stand",
      "quantity": 1,
      "unit_price": 39.99
    }
  ]
}

Hinweis: @Read Bestellungen abrufen > items und nennen Sie dem Kunden die drei obersten Artikel in seiner Bestellung.

Verwendung von Arrays in Code-Bedingungen

Array-Attribute sind unter dem Objekt inputs["data_connector"] verfügbar, gruppiert nach dem Namen des Daten-Connectors. Arrays sind nullbasiert, das heißt, das erste Element hat den Index 0. Prüfen Sie immer die Array-Länge bevor Sie auf einen bestimmten Index zugreifen.

Sie können Werte innerhalb eines Arrays weiterhin mit einer Code-Bedingung abfragen.
In Code-Bedingungen wird auf Array-Daten mit Python-Ausdrücken zugegriffen, bei denen Sie Elemente explizit nach Index referenzieren oder über die Liste iterieren.

Diese Bedingung prüft, ob die Bestellung mindestens vier Artikel enthält und die Menge des vierten Artikels größer als drei ist.

Validieren Sie immer die Array-Länge, bevor Sie auf einen Index zugreifen, um Laufzeitfehler bei der Bedingungsbewertung zu vermeiden.

Hinweis: Die verfügbaren Aktionen hängen davon ab, wie Ihr Daten-Connector konfiguriert ist.

Daten-Connectoren unterstützen:

Erstellen: Verwenden Sie POST-Anfragen, um neue Datensätze in einem externen System zu erstellen.
Lesen: Verwenden Sie GET-Anfragen, um vorhandene Daten abzurufen.
Aktualisieren: Verwenden Sie PUT- oder PATCH-Anfragen, um vorhandene Datensätze zu ändern.
Löschen: Verwenden Sie DELETE-Anfragen, um Datensätze zu entfernen.

Wie man Daten-Connectoren in Fin Procedures verwendet