Jeder Daten-Connector besteht aus einem API-Aufruf, den Sie im Hintergrund konfigurieren können. Fin wählt automatisch aus, wann er ihn verwendet, und liefert eine personalisierte Antwort an den Kunden.
Sie können jedes System verbinden, das eine API hat; das kann Ihr einzigartiges internes Backend-Tool sein, das Sie für Ihr Unternehmen entwickelt haben, oder eine Drittanbieter-App wie Shopify, Salesforce, Stripe, Jira und mehr.
Hinweis:
Die Benutzerauthentifizierung muss konfiguriert werden, um einen Daten-Connector für users live zu schalten. Dies verhindert, dass sich jemand als Ihre angemeldeten users ausgibt oder deren Gespräche einsehen kann. Erfahren Sie, wie Sie JWTs für die Benutzerauthentifizierung einrichten.
Erstellen Sie einen Daten-Connector
Um einen benutzerdefinierten Daten-Connector für Fin einzurichten, navigieren Sie zu Einstellungen > Integrationen > Daten-Connectoren und klicken Sie auf + Neu.
Phase 1: API
Der Konfigurationseditor ist in vier Registerkarten unterteilt: API, Daten, Fin und Sicherheit. Arbeiten Sie jede Registerkarte durch, um Ihren Connector zu erstellen, bevor Sie ihn live schalten.
Identität
Geben Sie zunächst einen kurzen Namen an, der beschreibt, was dieser Daten-Connector macht, z. B. „Unbezahlten Kontostand abrufen“. Geben Sie anschließend eine detaillierte Beschreibung an, die erklärt, wann Fin ihn verwenden soll.
Fügen Sie Beispiele für die Daten hinzu, die dieser Daten-Connector bereitstellt, und Kundenanfragen, die er beantwortet.
Zum Beispiel:
Verwenden Sie diesen Daten-Connector, um die letzten Transaktionen eines Kunden abzurufen. Dieser Daten-Connector liefert wichtige Informationen wie… Beispielhafte Kundenanfragen sind… „Können Sie prüfen, ob ich einen offenen Saldo auf meinem Konto habe?“ „Gibt es derzeit eine Zahlung, die auf meinem Konto fällig ist?“ „Schulde ich etwas auf meinem Konto?“ „Können Sie mir sagen, ob ich unbezahlte Rechnungen oder Gebühren habe?“ „Gibt es einen Saldo, den ich auf meinem Konto begleichen muss?“ „Können Sie bestätigen, ob mein Konto vollständig bezahlt ist?“
API-Verbindung
Falls gewünscht, können Sie angeben, ob Fin vor der Verwendung dieses Daten-Connectors Daten sammeln soll. Dies kann hilfreich sein, wenn Sie sicherstellen müssen, dass Daten vorhanden sind, bevor der Daten-Connector ausgeführt wird. Zum Beispiel möchten Sie den Kunden nach seiner Kontonummer fragen, wenn diese nicht in seinem user-Profil in Intercom gespeichert ist.
Um Dateneingaben zu sammeln, klicken Sie auf + Dateneingabe hinzufügen und wählen Sie das Format der zu sammelnden Daten (Text, Zahl, Dezimalzahl oder Wahr/Falsch) aus und geben Sie ihm einen Namen und eine Beschreibung, damit Fin weiß, wie die Daten gesammelt werden sollen.
Hinweis:
Wenn verfügbar, wird Fin die Informationen aus dem Gesprächskontext sammeln.
Sie können Daten-Connectoren mit APIs verbinden, die XML zurückgeben. Intercom konvertiert XML-Antworten automatisch in JSON, sodass Sie keine manuelle Konvertierung oder ein Drittanbieter-Tool verwenden müssen. Das bedeutet, dass Sie eine größere Bandbreite externer Systeme anschließen können, selbst wenn diese JSON nicht nativ unterstützen.
Als Nächstes müssen Sie die HTTPS-URL Ihrer API angeben und die Anfragemethode auswählen: GET, POST, PUT, DELETE oder PATCH.
Sie möchten möglicherweise Attribute verwenden, die in Ihrem Workspace verfügbar sind, wie die user-ID oder E-Mail eines Kunden, um eine Suche durchzuführen. Sie müssen auch sicherstellen, dass Sie das richtige Authentifizierungstoken angeben und die korrekten Header festlegen (z. B. Accept: application/json oder Content-Type: application/json).
Testen Sie nach Abschluss Ihre Verbindung, um die Einrichtung zu validieren, bevor Sie zur Registerkarte Daten wechseln.
Antwort testen
Sie müssen diese Aktion testen, um sicherzustellen, dass die richtigen Daten von der API abgerufen werden, mit der Sie sich verbinden. Sie können Ihren Daten-Connector mit zwei Methoden testen:
Live-Antwort: Testen Sie mit Live-Antwortdaten von Ihrer API-Anfrage, um die korrekte Konfiguration sicherzustellen. Die Live-Antwort führt einen tatsächlichen API-Aufruf an Ihren Endpunkt aus, seien Sie also vorsichtig, falls diese Anfrage reale Daten beeinflusst.
Beispielantwort: Geben Sie Beispiel-JSON-Daten an, die nützlich sind, wenn Ihre API noch nicht vollständig entwickelt ist oder Sie eine bestimmte Antwort simulieren/mimen müssen.
Wenn alles gut aussieht, fahren Sie mit der Registerkarte Daten fort, um zu konfigurieren, wie die Antwort gestaltet wird.
Phase 2: Daten
Diese Registerkarte steuert, wie die API-Antwort gestaltet wird, bevor Fin sie verwendet.
Einschränken und gestalten
Standardmäßig kann Fin auf die vollständigen Antwortdaten zugreifen, um Antworten zu generieren. Wählen Sie Zugriff manuell einschränken, wenn Sie die Daten, auf die Fin zugreifen kann, begrenzen möchten. Wählen Sie dann die Datenfelder aus, auf die Fin Zugriff erhalten soll.
Sie können auch einzelne Datenelemente bearbeiten, indem Sie auf das Bearbeiten-Symbol klicken, um Ihren Antwortdaten einen kundenorientierten Namen zu geben und beliebige Transformationen der Daten anzugeben.
Wenn die API-Antwort beispielsweise einen Saldo von 0 zurückgibt, kann Fin anstatt zu sagen, dass der unbezahlte Saldo 0 ist, antworten, dass derzeit kein unbezahlter Saldo mehr vorhanden ist.
Verwenden Sie Code, um die Antwort zu filtern oder zu transformieren
Mit Codeblöcken für Daten-Connectoren ermöglichen wir Ihnen, API-Antworten direkt mit Python zu transformieren und zu manipulieren – direkt in Ihrer Connector-Einrichtung.
Unstrukturierte oder zu große Payloads von APIs können dazu führen, dass KI-basierte Antworten (wie Fin oder andere KI-Agenten) Halluzinationen erzeugen, falsch interpretieren oder einfach keine klaren Antworten liefern. Jetzt können Sie API-Antworten programmatisch vorverarbeiten, filtern oder anpassen, bevor sie an Fin gesendet oder auf Intercom-Objekte abgebildet werden, ohne Backend-Änderungen oder Drittanbieter-Integrationen zu benötigen.
Wie es funktioniert
return-Anweisung: Das Hauptergebnis, das Ihr Codeblock erzeugt, muss mit einerreturn-Anweisung zurückgegeben werden. Nur das, was zurückgegeben wird, wird an Fin oder den Rest Ihres Connectors weitergeleitet.print()-Anweisungen: Verwenden Sie diese nur für Debug- oder Fortschrittsprotokolle. Diese Ausgaben werden separat erfasst und NICHT als API-Ergebnis gesendet.Nur Standardmodule: Sie sind auf eine Reihe von Standard-Python-Modulen (
math,decimal,re,datetime,datetime.timezone,json,random,time) beschränkt. Wir werden im Laufe der Zeit weitere Module hinzufügen, wenn sie benötigt werden.
Hinweis:
Nicht-JSON-Testantworten: Codeblöcke erfordern, dass Ihre API-Testantwort ein gültiges JSON-Objekt oder -Array ist. Nicht-JSON-Payloads werden nicht unterstützt (und führen zu Fehlern).
Nicht erfolgreiche API-Anfragen: Codeblöcke können nur erfolgreiche API-Antworten (Statuscode 200) transformieren. Fehlerantworten mit Statuscodes wie 400, 404 oder 500 werden für die Codeblock-Transformation nicht unterstützt.
So konfigurieren Sie Codeblöcke für Daten-Connectoren
Gehen Sie zu Einstellungen > Integrationen > Daten-Connectoren und wählen Sie den Daten-Connector aus, mit dem Sie Codeblöcke verwenden möchten. Klicken Sie dann auf Daten-Transformation und wählen Sie die Option „Code verwenden, um die Antwort zu filtern oder zu transformieren“ aus.
Zugriff auf Eingabedaten (API-Antwort) in Ihrem Codeblock
Um auf die von Ihrer API zurückgegebenen Daten (die Testantwort) zuzugreifen, verwenden Sie die inputs['data']-Variable in Ihrem Codeblock. Normalerweise erhalten Sie so die gesamte Antwort Ihrer API, die Sie nach Belieben transformieren können.
Zum Beispiel schreiben Sie am Anfang Ihres Codeblocks typischerweise:
api_response = inputs['data']
Dies weist die API-Antwort (ein Python-Wörterbuch, eine Liste oder ein String, je nach Ihrer API) der Variablen api_response zur weiteren Verarbeitung zu.
Erhalten Sie automatische Vorschläge für Codeblöcke
Wenn Sie zum Tab Datenumwandlung navigieren, wird Ihre Datenconnector-Antwort automatisch analysiert, um Vorschläge zu identifizieren, die die Leistung von Fin verbessern.
Dies erkennt häufige Probleme wie Unix-Zeitstempel und übergroße Nutzlasten – unstrukturierte oder zu große Daten, die dazu führen können, dass KI-basierte Antworten halluzinieren, falsch interpretieren oder keine klaren Antworten liefern.
Wenn ein Vorschlag gefunden wird, sehen Sie ein Banner mit einer Schaltfläche Vorschlag anzeigen, die empfohlenen Python-Code zeigt, der Ihre Daten für Fin sauberer und zuverlässiger macht. Wählen Sie Code testen, um das Ergebnis zu sehen.
Wenn Sie mit der Rückgabeanweisung zufrieden sind, wählen Sie Vorschlag akzeptieren, um die Qualität und Genauigkeit der Fin-Antworten aus Ihren Connector-Daten erheblich zu verbessern.
Objektzuordnung
Beim Erstellen von Datenconnectors für Fin ist es nicht notwendig, Antwortdaten auf Intercom-Attribute oder -Objekte abzubilden. Stattdessen interpretiert Fin die JSON-Antwort direkt und kann sie dann zur Beantwortung von Fragen verwenden. Die Antwort wird basierend auf dem Abschnitt „Testantwort“ generiert. Jeder Posten entspricht einem Datenpunkt in der JSON-Antwort.
Nachdem Sie den Daten-Tab konfiguriert haben, fahren Sie mit Phase 3: Fin fort, um zu definieren, wie Fin diesen Connector verwendet, und Phase 4: Sicherheit, um die Authentifizierung einzurichten und Sicherheitsprüfungen vor dem Livegang durchzuführen.
Phase 3: Fin
Dieser Tab bestimmt, wie Fin mit dem Connector interagiert.
Wie soll Fin diesen Connector verwenden?
Wählen Sie zwischen zwei Modi:
Aktiviert (direkter Auslöser) — Fin löst den Connector automatisch basierend auf der Kundenfrage aus. Am besten für schreibgeschützte Connectoren wie „Bestellstatus prüfen“ und volumenstarke, wiederholbare Anfragen.
Deaktiviert (manueller Auslöser) — Der Connector wird nicht automatisch ausgeführt. Sie müssen ihn manuell zu einem Workflow, einer Aufgabe, einem Verfahren oder einem Macro hinzufügen. Am besten für sensible oder schreibaktive Connectoren, bei denen Sie menschliche oder Workflow-Überwachung vor der Ausführung wünschen.
Zielgruppe
Steuern Sie, für wen dieser Connector mit wiederverwendbaren Fin-Zielgruppen verfügbar ist, oder erstellen Sie eine benutzerdefinierte Zielgruppe für einmalige Regeln. Zum Beispiel machen Sie ihn für Kunden in Ihrer „Enterprise plan“-Zielgruppe verfügbar oder beschränken ihn auf angemeldete users mit verifizierter E-Mail.
Tipp: Sie können Alle, eine wiederverwendbare Fin-Zielgruppe oder eine Benutzerdefinierte Zielgruppe für einmalige Regeln wählen. Sie können mehrere Fin-Zielgruppen auswählen, aber keine Benutzerdefinierten Regeln mit einer Fin-Zielgruppe kombinieren. Alle bestehenden Zielgruppenregeln, die Sie konfiguriert haben, werden zu einer Benutzerdefinierten Zielgruppe, um die Funktionalität zu erhalten.
Fin-Vorschau
Verwenden Sie die Fin-Vorschau, um genau zu sehen, wie Fin mit diesem Connector antwortet, bevor Sie ihn live schalten.
Phase 4: Sicherheit
Der letzte Schritt vor dem Livegang. Dieser Tab verwaltet die Zugriffskontrolle für Kundendaten.
Kunden-Authentifizierung
Schalten Sie dies ein, um die Authentifizierungsregeln Ihres Arbeitsbereichs durchzusetzen, bevor der Connector auf sensible Informationen zugreifen oder diese anzeigen kann. Die Authentifizierungsregeln werden unter Einstellungen > Arbeitsbereich > Sicherheit > Kunden-Authentifizierung konfiguriert.
Sicherheitsprüfung
Führen Sie eine Diagnose durch, um die Sicherheit Ihrer API-Konfiguration zu bewerten. Alle Risiken werden mit umsetzbaren Empfehlungen angezeigt – beheben Sie diese, bevor Sie den Connector live schalten.
Wichtig: Es gibt einige potenzielle Wege, wie Fin versehentlich Informationen von einem anderen user beim Parameterübergabe teilen könnte. Siehe unsere empfohlenen Einstellungen zur besten Risikominderung.
Sobald alle Prüfungen bestanden sind, speichern Sie Ihren Connector und schalten ihn live.
Rollout von Datenconnectors
Wir empfehlen, Zielgruppenregeln zu verwenden, um Datenconnectors phasenweise an Ihre Kundenbasis auszurollen. So können Sie die Leistung der Datenconnectors validieren und bei Bedarf Anpassungen vornehmen.
Wenn Sie Probleme haben, bei denen Ihr Datenconnector für einen user nicht ausgelöst wird, stellen Sie sicher, dass Sie alle unternehmensspezifischen Zielgruppenregeln entfernt haben, die Sie in der Testphase hinzugefügt haben.
Fehlerbehebung
Zu Fehlerbehebungszwecken werden alle Antwortdaten, die von Datenconnectors generiert werden, die von Fin ausgelöst werden, bis zu 14 Tage lang gespeichert. Sie können diese Protokolle unter dem Tab Datenconnector > Protokolle einsehen. Sie können Antwortdaten basierend darauf anzeigen, auf welche Art von Daten Fin Zugriff hat.
Gesamte Antwort – Vollständige, unveränderte Antwort
Redigierte & formatierte Antwort – Nach der Umwandlung
Keine Antwortdaten
FAQs
Kann ich Datenconnectors verwenden, um Attribute zu senden, wenn ich eine Fin-Konversation an eine Drittanbieterplattform (nicht Zendesk/Salesforce) übergebe?
Kann ich Datenconnectors verwenden, um Attribute zu senden, wenn ich eine Fin-Konversation an eine Drittanbieterplattform (nicht Zendesk/Salesforce) übergebe?
Wenn Sie versuchen, eine POST-Anfrage zu senden (z. B. mit einer Struktur wie unten), verwenden Sie stattdessen Ihre Fin-Workflow-Übergabeoptionen:
{
"body": "the conversation with Fin",
"from": "users_email_address",
"to": "our_ticketing_email_address"
}
Workflow-Übergabeoptionen umfassen Übergabe mit JavaScript und Übergabe an URL, mit der Möglichkeit, Gesprächskontext durch KI-generierte Zusammenfassungen einzubeziehen.
1. Übergabe mit JavaScript
Dies ermöglicht Ihnen, eine handoff_with_javascript-Funktion in Ihrer Messenger-App zu definieren, die Folgendes kann:
Die Gesprächszusammenfassung sammeln (über „AI Add Summary Note“)
Auf die E-Mail des users zugreifen (mithilfe von Attributen)
Eine fetch()- oder XMLHttpRequest an Ihren externen Endpunkt mit der gewünschten Struktur senden
Erfahren Sie mehr hier 👉 Übergabe mit JavaScript
2. Übergabe an URL
Diese Option leitet den user nur auf eine bestimmte Seite weiter, sie sendet keine POST-Anfrage und überträgt keine Gesprächsdaten. Daher ist sie nicht geeignet, wenn Sie JSON per POST senden möchten.
Empfohlene Einrichtung
Verwenden Sie die JavaScript hand-off und fügen Sie Logik wie folgt ein:
handoff_with_javascript = function (params) {
const userEmail = params.user.email;
const summary = params.conversation_summary;
fetch('https://your-endpoint.com/api', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
body: summary,
from: userEmail,
to: 'your_support@company.com'
})
});
}