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 lesen und im Verfahren verwenden (z. B. prüfen, welchen Plan ein Kunde hat, den Bestellstatus abrufen oder Kontodetails einsehen).
Zurückschreiben in ein externes System, indem Aktionen mitten im Gespräch 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 direkt aus Ihren internen Systemen oder Drittanbieter-APIs 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 den folgenden Schritten abrufen. Dies steht Fin allgemein als Kontext zur Verfügung, aber wir parsen die Antwortfelder auch 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 führt Fin einen Live-API-Aufruf aus 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. Lieferbestellung abrufen > Status, Lieferbestellung abrufen > order_id).
Wählen Sie das spezifische Attribut aus, das Sie in Ihre Anweisung oder Bedingung einfügen möchten.
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 höhere 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 bei.
Beste Praktiken
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 im Setup des Daten-Connectors (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, damit 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 bezieht sich „Kontext“ auf 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 werden während der Einrichtung des Daten-Connectors vorkonfiguriert, sodass Fin die benötigten Eingaben automatisch ermittelt, ohne dass Sie Fin explizit auffordern müssen, diese Daten zu sammeln.
Beispielsweise wenn 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 ermittelt und sammelt automatisch die erforderlichen Eingaben basierend auf der Connector-Konfiguration, 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. Indem Sie das Attribut direkt im Connector konfigurieren statt als von Fin gesammelte 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 Parameter eines Daten-Connectors auswählen. Wenn ein temporäres Attribut als Eingabe zugeordnet ist, überspringt Fin jegliche Attributabruf-Logik und verwendet den Wert des temporären Attributs direkt – keine Ableitung, keine Kundenabfrage, kein Fallback.
Dies ist nützlich, wenn ein Verfahrensschritt früher im Ablauf 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 dem Ausführen 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
Verfahren, die Daten-Connectoren verwenden, zeigen auf der Verfahrenslisten-Seite einen Gesundheitsindikator direkt an, sodass Sie Connector-Probleme auf einen Blick erkennen können, ohne jedes Verfahren zu öffnen. Der Stempel zeigt den am schlechtesten performenden Connector des Verfahrens an, berechnet über die letzten 14 Tage (maximal 1.000 Ausführungen pro Connector).
Verfahren ohne Daten-Connectoren zeigen keinen Indikator; Connectoren mit null Ausführungen gelten als gesund.
Gesundheitsstatus
Status | Kriterien | Auswirkung |
🟢 Gesund | Alle Connectoren haben eine Erfolgsrate von >95 % und eine durchschnittliche Antwortgröße unter 50 KB. | Funktioniert optimal. |
🟡 Verschlechtert | Mindestens ein Connector hat eine Erfolgsrate von 80–95 % oder >95 % Erfolgsrate, aber eine durchschnittliche Antwortgröße ≥50 KB (~15K Tokens). | Erlebt Probleme oder liefert große Antworten, die das Risiko von Halluzinationen erhöhen können. |
🔴 Ungesund | Mindestens ein Connector hat eine Erfolgsrate von <80 % oder eine durchschnittliche Antwortgröße ≥100 KB (~30K Tokens). | Kritische Probleme oder gefährlich große Antworten, die sofortige Aufmerksamkeit erfordern. |
Detaillierte Ansicht
Ein Klick auf den Gesundheitsstempel öffnet eine Seitenleiste mit einer Aufschlüsselung pro Connector: Status, Erfolgsrate, durchschnittliche Antwortgröße, P90-Latenz und häufigste Fehler. Connector-Namen verlinken direkt zur Einstellungsseite für schnelles Debugging.
Tipp: Wenn ein Connector aufgrund der Antwortgröße als verschlechtert oder ungesund angezeigt wird, siehe die oben genannte beste Praxis Optimieren Sie Ihre API-Antworten, damit sie die kleinstmögliche Teilmenge relevanter Daten enthalten, die Fin benötigt. Das Filtern von Feldern oder die Verwendung von Codeblöcken, um die Antwort vor der Ansicht durch Fin zu kürzen, ist die schnellste Lösung.
Umgang mit Arrays
Wenn ein Daten-Connector eine Liste zurückgibt, zeigt Fin nur das Wurzel-Array als Attribut an. Kindelemente innerhalb des Arrays werden im Attributauswahlmenü 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 > titleBestellungen abrufen > items > price
Fin kann trotzdem mit dem Inhalt einer Liste arbeiten. Zum Beispiel, wenn Sie folgende 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 den gesamten Inhalt der Items-Liste und antwortet mit: „Ihre Bestellung enthält eine kabellose Maus (24,99 $) und einen Laptop-Ständer (39,99 $).“
Zum Beispiel: Für die untenstehende Antwort-Nutzlast wird nur das Wurzel-Array-Element items als temporäres Attribut angezeigt, 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 wichtigsten Artikel in seiner Bestellung.
Verwendung von Arrays in Code-Bedingungen
Array-Attribute sind im 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 ob 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 während 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.