Data connectors bieten eine leistungsstarke Möglichkeit, personalisierte Antworten zu liefern, indem sie eine Verbindung zu Daten in Ihren Drittanbietersystemen herstellen. Anstatt dass Kunden darauf warten, dass Teammitglieder die Informationen manuell nachschlagen oder selbst nach Informationen suchen, kann Fin sofort auf die relevanten Daten zugreifen und eine personalisierte Antwort erstellen.
Um sicherzustellen, dass diese Data connectors korrekt funktionieren und in den richtigen Szenarien verwendet werden, sollten Sie folgende Best Practices beachten…
Effektive Data connector Prompts schreiben
Einer der wichtigsten Schritte ist es, einen effektiven Prompt im Fin-Bereich Ihres Data connectors zu schreiben.
Sie sollten 3-5 Sätze schreiben, um zu beschreiben, wann der Fin AI Agent diesen Data connector auslösen soll. Seien Sie so spezifisch wie möglich und stellen Sie sicher, dass Sie einen oder mehrere der folgenden Punkte einschließen:
Beispiele für Arten von Kundenanfragen, die durch diesen Data connector beantwortet werden würden.
Schlüsselphrasen, die Kunden möglicherweise verwenden.
Häufige Szenarien, in denen das Auslösen dieses Data connectors angemessen wäre.
Sie können sich auch die KI-empfohlenen Vorlagen als Beispiel ansehen.
Seien Sie beschreibend
Erklären Sie klar, wann dieser Data connector verwendet werden sollte und welche Arten von Details er liefern soll.
Gute Praxis | Verwenden Sie diesen Data connector, um Details zu den Bestellungen des Kunden zu erhalten und bei der Fehlerbehebung von Bestellproblemen zu helfen. Dieser Data connector liefert alle Bestelldetails für den Kunden wie Bestellstatus, gekaufte Artikel, Versandadresse, Sendungsverfolgung oder andere relevante Bestelldetails. |
Schlechte Praxis | Verwenden Sie diesen Data connector, um Informationen über ihre Bestellung zu erhalten. |
Vermeiden Sie die Verwendung von Pronomen
Ersetzen Sie Pronomen wie „wir“, „uns“ und „ihre“ durch das passende Substantiv, auf das Sie sich beziehen, z. B. den Namen Ihres Unternehmens.
Gute Praxis | Verwenden Sie diesen Data connector, um den Stromverbrauch eines Kunden mit Examply nachzuschlagen. |
Schlechte Praxis | Verwenden Sie diesen Data connector, um ihren Stromverbrauch bei uns nachzuschlagen. |
Seien Sie spezifisch
Verwenden Sie gängige Szenarien, in denen das Auslösen dieses Data connectors angemessen wäre.
Gute Praxis | Verwenden Sie diesen Data connector, um ungelöste Vorfälle nachzuschlagen, z. B. wenn Kunden wissen möchten, wann ein Vorfall begann, den aktuellen Status des Problems, welche Produkte oder Dienstleistungen von einem Vorfall betroffen sind oder ob die Systemleistung wieder normal ist. |
Schlechte Praxis | Verwenden Sie diesen Data connector, um ungelöste Vorfälle nachzuschlagen. |
Kundenphrasen einbeziehen
Sehen Sie sich an, wie Kunden ihre Anfragen in früheren Gesprächen formuliert haben, und fügen Sie die Schlüsselwörter und Phrasen ein, die sie verwenden.
Gute Praxis | Suchen Sie nach diesen Schlüsselphrasen wie „fehlgeschlagene Bestellung“, „Problem mit Bestellungen“, „Bestellungen erscheinen nicht im System“, „Schwierigkeiten mit der Bestellung“. |
Schlechte Praxis | Schlüsselphrasen der Kunden nicht einbeziehen. |
Wählen Sie den richtigen API-Endpunkt
Um den Kunden die korrekten Daten zu liefern, ist es wichtig, den richtigen API-Endpunkt auszuwählen, egal ob er von einer Drittanbieter-App oder einem externen System stammt, das Ihrem Unternehmen gehört.
Wenn Sie nicht sicher sind, wo Sie anfangen sollen, sollten Sie einen Ingenieur hinzuziehen, der Ihnen hilft herauszufinden, welche API die erforderlichen Daten zurückgibt.
Wenn Sie beispielsweise ein internes Buchungssystem haben, das die Buchungsdetails eines Kunden speichert, möchten Sie eine API für dieses System verwenden, die direkt auf Buchungsdetails zugreifen kann.
Sie sollten auch eine API verwenden, die Kundendetails anhand eines eindeutigen Identifikators als Parameter finden kann, wie eine ID oder eine E-Mail-Adresse.
Wenn Sie sich entschieden haben, den Namen oder die E-Mail-Adresse eines Kunden als Anforderungsparameter zu verwenden und dieser mehrere Buchungen hatte, müssten Sie die Anfrage wahrscheinlich weiter spezifizieren, indem Sie das Datum der Reservierung verwenden. Anstatt mehrere Daten anzufordern, wäre es optimal, nur eine zu erfragen – die Buchungs-ID.
So können Sie die Buchungs-ID als Dateneingabe erfassen, die Fin im Gespräch vom Kunden abfragen wird. Dann kann die ID in den Endpunkt eingefügt werden, indem Sie im Menü am Ende des URL-Eingabeformulars darüber fahren.
Tipp: Data connectors unterstützen jetzt sowohl JSON- als auch XML-API-Antworten. Wenn Ihr externes System nur XML bereitstellt, können Sie es trotzdem direkt verbinden – Intercom konvertiert das XML automatisch in JSON, sodass Sie die Daten in Fin, Workflows und Inbox ohne zusätzliche Schritte verwenden können.
Sie sollten auch sicherstellen, dass Sie die richtigen HTTP-Header für die Anfrage verwenden. Wenn diese über viele Data connectors hinweg verwendet werden, können Sie sie als gespeicherten Authentifizierungstoken hinzufügen, der sicher in Ihrem Workspace gespeichert wird.
Anhand unseres Buchungsbeispiels: Angenommen, ein Kunde möchte seine Reise auf einen anderen Tag umbuchen. Wenn ein Data connector zur Überprüfung von Buchungspreisen und Verfügbarkeit verfügbar ist, wählt Fin ihn automatisch im selben Gespräch aus.
Wenn Sie API-Endpunkte für Data connectors auswählen, sollten Sie Fälle bedenken, in denen die Daten, die Ihre Kunden benötigen, über mehrere Endpunkte verteilt sind.
Um sicherzustellen, dass der Kunde die Preise und Verfügbarkeit sehen kann, können Sie einen weiteren Data connector zu einem Endpunkt erstellen, der diese Informationen enthält.
Sichere und geschützte Verbindungen erstellen
Identitätsprüfung
Für den sichersten Aufruf empfehlen wir die Verwendung von ‘Email’ oder ‘User ID’ im People Object, um den Nutzer in Ihrem System abzugleichen.
Intercom erlaubt derzeit nur die Verifizierung der E-Mail- oder Benutzer-ID-Werte, die von Messenger kommen. Wir empfehlen dringend, users im Messenger mit JSON Web Tokens (JWTs) zu authentifizieren.
E-Mail-Verifizierung mit Einmal-Passcode (OTP)
Verwenden Sie die E-Mail-Verifizierung für Datenconnectoren mit OTP, um einen zusätzlichen Verifizierungsschritt bereitzustellen, bevor ein Datenconnector verwendet wird, indem Kunden aufgefordert werden, ihre Identität durch einen einzigartigen, zeitlich begrenzten Code zu bestätigen, der per E-Mail gesendet wird.
Schutz vor Datenlecks
Es gibt im Allgemeinen zwei Möglichkeiten, wie Daten kompromittiert werden können:
Ein user aktualisiert böswillig eines seiner eigenen Attribute - Zum Beispiel das Setzen von „user_shopify_id=123“, wobei 123 die Shopify-ID eines Opfers ist. Dann werden diese Daten für die ID 123 von Shopify gepusht oder gezogen und mit dem böswilligen user in Intercom verknüpft.
Ein user manipuliert Daten bei einem Drittanbieter, und ein Datenconnector zieht kompromittierte Daten in Intercom - Zum Beispiel meldet sich ein user bei einem Drittanbieter mit der Telefonnummer eines Opfers an. Dann fragt ein Datenconnector den Drittanbieter ab und synchronisiert diese Telefonnummer mit einem Personenattribut in Intercom. Nun hat der user seine Telefonnummer mit der des Opfers überschrieben.
Um dies zu verhindern, testen Sie Ihren Datenconnector immer zuerst, bevor Sie ihn live schalten, um sicherzustellen, dass er korrekt konfiguriert ist.
Wichtige Punkte, auf die Sie achten sollten:
Stellen Sie sicher, dass Ihr Datenconnector Daten zurückgibt, die für den zugeordneten user relevant sind.
Stellen Sie sicher, dass Ihre Daten korrekt in Ihren zugeordneten Intercom-Attributen gespeichert werden.
Verwenden Sie Datenumwandlung, um Daten einzuschränken
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. Mit Codeblöcken in Datenconnectoren 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.
Tipps:
Verwenden Sie immer
returnfür Ihr Hauptergebnis.Nur zum Debuggen drucken (z. B.
print('Verarbeite Bestellung', order['id'])).Halten Sie es einfach: Vermeiden Sie es, alles auf einmal zu transformieren – eine klare Transformation pro Codeblock ist am besten.
Validieren Sie die Ausgabeform: Stellen Sie sicher, dass die Ausgabe dem entspricht, was Fin (oder Ihr Mapping-Schritt) erwartet.
Keine Importe über genehmigte Module hinaus: Standard-Python-Module (
math,decimal,re,datetime,datetime.timezone,json,random,time). Wir werden im Laufe der Zeit weitere Module hinzufügen, wenn sie benötigt werden.
Praktische Beispiele
Hier sind 4 gängige Muster, jeweils mit einem realistischen Beispiel unter Verwendung der neuesten Anforderungen (einschließlich return).
1. Reduzierung großer Payloads für Fin
APIs liefern oft zu viele Daten zurück. Angenommen, Ihre Antwort enthält 1.000 Produkte, aber Sie möchten nur die ersten 5 für Fin, um Halluzinationen zu vermeiden.
api_response = inputs['data']
# Reduce payload to just the first 5 products
result = api_response[:5]
return result
2. Umgang mit Daten in API-Antworten
Manchmal interpretieren LLMs (wie Fin) Datumsstrings falsch, besonders bei Zeitzonen. Verwenden Sie Python, um alle Datumsstrings in ein einheitliches ISO-Format mit explizitem UTC umzuwandeln.
import datetime
def to_iso_utc(date_str):
try: # Adjust this format as needed!
dt = datetime.datetime.strptime(date_str, "%Y-%m-%d %H:%M:%S")
dt = dt.replace(tzinfo=datetime.timezone.utc)
return dt.isoformat()
except Exception as e:
print(f"Error parsing {date_str}: {e}")
return date_str
api_response = inputs['data']
for item in api_response:
if 'created_at' in item:
item['created_at'] = to_iso_utc(item['created_at'])
return api_response
3. Filtern von API-Ergebnissen nach einem bestimmten Feldwert
Angenommen, Sie möchten nur Autos zurückgeben, bei denen make 'toyota' ist (siehe Ihre Screenshots!).
api_response = inputs['data']
filtered = [car for car in api_response if car.get('make', '').lower() == 'toyota']
return filtered
4. Verschachtelte Positionen für aktuelle Bestellungen abflachen
Wenn Ihre API-Antwort tief verschachtelt ist (Bestellungen mit Positionen darin), flachen Sie sie für Fin ab:
orders = inputs['data']['orders']
result = []
for order in orders:
for item in order['line_items']:
result.append({
"order_id": order['id'],
"item_name": item['name']
})
return result
Klickbare Deep Links von Ihrem Datenconnector zurückgeben
Wenn Ihr Datenconnector eine URL zurückgibt, die Fin als klickbaren Link präsentieren soll, haben Sie zwei Optionen.
Option 1: Formatieren Sie den Link in Ihrer API-Antwort
Fügen Sie die Markdown-Link-Syntax direkt in den Text ein, den Ihre API zurückgibt. Fin rendert ihn als klickbaren Link im Gespräch.
Verwenden Sie dieses Format, um benutzerdefinierten Linktext anzuzeigen:
[View Dashboard](beyond://account/dashboard)
Oder dieses Format, wenn Sie möchten, dass die URL selbst sichtbar und klickbar ist:
[beyond://account/dashboard](beyond://account/dashboard)
Option 2: Verwenden Sie Fin-Anweisungen, um den Link zu formatieren
Wenn Ihre API eine einfache URL in einem Datenattribut zurückgibt, können Sie Fin anweisen, sie als klickbaren Link mit Anweisungen zu formatieren. Verweisen Sie auf den Namen des Datenconnectors und das Attribut mit dem Deep Link und sagen Sie Fin, es mit Markdown-Link-Syntax zu präsentieren.
Zielgruppenregeln nutzen
Wenn Sie gerade erst mit Datenconnectoren beginnen, möchten Sie vielleicht experimentieren, welche Datenconnector-Konfigurationen zu mehr Lösungen führen. Eine Möglichkeit besteht darin, den Datenconnector zunächst für eine Teilmenge von users zu aktivieren, um zu sehen, wie er funktioniert. Sie können dies mit audience rules tun.
Audience rules können aus einer Liste von Firmen- oder Kontaktattributen ausgewählt werden, die bereits in Ihrem Workspace verfügbar sind. Wenn Sie Shopify, Statuspage oder Stripe installiert haben, können Sie auch auf app-spezifische Attribute zugreifen.
Wenn ein Attribut, das Sie verwenden möchten, nicht existiert, können Sie custom data attributes einrichten, um users zu identifizieren, die die Kriterien erfüllen, die Sie für den Datenconnector anvisieren möchten.
Sobald Sie die Regel erstellt haben, können Sie eine Vorschau der users sehen, die möglicherweise eine Antwort erhalten, die vom Datenconnector unterstützt wird.
Verwenden Sie Sicherheitsprüfungen, um Ihre Connectoren zu schützen
Führen Sie vor dem Live-Schalten eines Connectors die integrierten Sicherheitsprüfungen auf der Registerkarte Sicherheit aus. Diese zeigen potenzielle Risiken mit umsetzbaren Empfehlungen an, damit Sie fundierte Entscheidungen treffen können, bevor Sie live gehen.
Prüfungen können Folgendes umfassen:
Kundendatenattribute werden nicht verifiziert — Wenn Kundendatenattribute ohne user-Verifizierung aktualisiert werden können, fügen Sie eine user-Verifizierung hinzu.
Daten, die von Fin für diesen Connector gesammelt werden, müssen überprüft werden — Wenn Fin Informationen von Kunden sammelt, bevor Ihre API aufgerufen wird, validieren Sie die Eingaben zuerst in Ihrem Backend.
Workflows, die diesen Datenconnector verwenden, müssen überprüft werden — Wenn bestimmte workflows ein Risiko darstellen, sensible Kundendaten offenzulegen, überprüfen Sie diese, um sie in Ihrem Backend zu validieren.
Ein Anforderungsheader für diesen Datenconnector muss überprüft werden — Wenn Kundendetails mit jeder Anfrage gesendet werden, stellen Sie sicher, dass Ihre API den Wert überprüft.
Jede Prüfung enthält klare Schritte zur Behebung des Problems. Beheben Sie alle markierten Risiken, bevor Sie den Connector live schalten.
Analysieren Sie Gespräche, um Optimierungen voranzutreiben.
Jeder Datenconnector verfügt über ein eigenes Health-Dashboard, in dem Sie Auswirkungen bewerten und Verbesserungsmöglichkeiten erkennen können. Navigieren Sie zu Einstellungen > Integrations > data connectors und klicken Sie auf einen Connector, um dessen Dashboard zu öffnen. Dort können Sie Erfolgsraten, Ausführungsverzögerungen, HTTP-Statusaufteilungen und Fehlerkategorisierungen überprüfen – alles filterbar nach Zeitfenster (1h, 6h, 24h, 7d oder 14d). Für einzelne Ausführungsdetails wählen Sie den Logs-Tab. Über das Dashboard hinaus werfen Sie einen Blick auf Gespräche, bei denen ein data connector verwendet wurde, um zu sehen, was gut funktionierte oder was nicht ganz passte.
Wenn Sie benutzerdefinierte Datenattribute verwenden, um die Zielgruppe einzugrenzen, können Sie das Attribut nutzen, um das inbox zu filtern und zu sehen, wie es sich entwickelt hat und ob Anpassungen erforderlich sind.
Einige Fragen, die Sie berücksichtigen sollten, sind:
Hat der data connector im richtigen Fall ausgelöst?
Musste ein Teammitglied eingreifen, und wenn ja, in welcher Phase?
Hat der data connector dem Kunden basierend auf der gestellten Frage die richtigen Informationen geliefert, obwohl die Frage des Kunden eigentlich etwas anderes betraf?
Konnte die Antwort mit zusätzlichen Informationen aus Ihrem Knowledge Hub unterstützt werden?
Fin kann keine benutzerdefinierten Attribute oder Ereignisdaten für Antworten abfragen. Um Fin die Antwort mit Echtzeit-Asset-Daten zu ermöglichen, richten Sie Data Connectors ein, damit Fin über die API auf externe Datenquellen zugreifen kann.