Zum Hauptinhalt springen

Erstellen Sie Daten-Connectoren für Fin

So richten Sie Fin mit personalisierten Antworten ein, die Daten aus externen Systemen benötigen.

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 dem Kunden eine personalisierte Antwort.

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:

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, Data, Fin und Security. 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 einen Namen und eine Beschreibung an, damit Fin weiß, wie die Daten gesammelt werden sollen.

Hinweis:

  • Wenn verfügbar, sammelt Fin die Informationen aus dem Gesprächskontext.

  • 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, auch 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 richtigen Header spezifizieren (zum Beispiel: Accept: application/json oder Content-Type: application/json).

Nach Abschluss testen Sie Ihre Verbindung, um die Einrichtung zu validieren, bevor Sie zur Registerkarte Data 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:

  1. 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.

  2. 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 Data fort, um zu konfigurieren, wie die Antwort gestaltet wird.

Phase 2: Data

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.

Hinweis: Bei Verwendung von Zugriff manuell einschränken können Felder, deren Namen Sonderzeichen enthalten – wie Klammern (), Pluszeichen + oder Schrägstriche / – aufgrund eines Pfadabgleich-Bugs stillschweigend von den Daten ausgeschlossen werden, die Fin erhält. Um dies zu umgehen, benennen Sie die betroffenen Felder um, um Sonderzeichen zu entfernen, bevor Sie den Zugriff einschränken. Alternativ verwenden Sie den vollständigen Datenzugriff, wenn die Antwort keine sensiblen Daten enthält.

Sie können auch einzelne Datenpunkte 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) halluzinieren, 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 einer return-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-Dictionary, 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 einem Vorschlag anzeigen-Button, der 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.

Tipp: Sehen Sie sich diese Tipps und praktischen Beispiele zur Datenumwandlung an.

Objektzuordnung

Beim Erstellen von Datenconnectoren 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 Macro hinzufügen. Am besten für sensible oder schreibaktive Connectoren, bei denen menschliche oder Workflow-Überwachung vor der Ausführung gewünscht ist.

Zielgruppe

Steuern Sie, für wen dieser Connector verfügbar ist, indem Sie wiederverwendbare Fin-Zielgruppen verwenden oder eine benutzerdefinierte Zielgruppe für einmalige Regeln erstellen. 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.

Hinweis: Änderungen an der Fin-Auslöser-Einstellung werden im Entwurfsmodus gespeichert und treten erst in Kraft, wenn Sie sie veröffentlichen. Die Live-Version des Connectors verwendet weiterhin die bestehenden Einstellungen, bis Sie auf Live schalten klicken. Nach Änderungen bestätigen Sie immer, dass die Einstellung in der Live-Version reflektiert wird – nicht nur im Entwurf.

Phase 4: Sicherheit

Der letzte Schritt vor dem Livegang. Dieser Tab verwaltet den Zugriff auf Kundendaten.

Kunden-Authentifizierung

Schalten Sie dies ein, um die Authentifizierungsregeln Ihres Arbeitsbereichs durchzusetzen, bevor der Connector auf sensible Informationen zugreifen oder diese anzeigen kann. 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. 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.

Hinweis: Datenconnectoren verwenden ein Entwurf-/Live-Versionierungssystem. Alle Änderungen, die Sie vornehmen – einschließlich der Fin-Auslöser-Einstellung unter dem Fin-Tab – werden als Entwurf gespeichert und wirken sich erst aus, wenn Sie auf Live schalten klicken. Wenn der Connector nach einer Änderung unerwartet reagiert, prüfen Sie, ob der aktualisierte Entwurf veröffentlicht wurde. Die Connector-Liste in den Einstellungen zeigt den aktuellen Status jedes Connectors (live oder Entwurf).

Rollout von Datenconnectoren

Wir empfehlen, Zielgruppenregeln zu verwenden, um Datenconnectoren phasenweise für Ihre Kundenbasis auszurollen. So können Sie die Leistung der Datenconnectoren validieren und bei Bedarf Anpassungen vornehmen.

Wenn Sie Probleme haben, dass 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.

Tipp: Sie können einen bestehenden Datenconnector duplizieren, um ihn als Ausgangspunkt für einen neuen zu verwenden. Öffnen Sie den Connector und klicken Sie auf das ...-Menü oben rechts, dann wählen Sie Duplizieren. Die Kopie öffnet sich im Entwurfsmodus mit allen vorausgefüllten Einstellungen.

Fehlerbehebung

Zu Zwecken der Fehlerbehebung werden alle Antwortdaten, die von Datenconnectoren generiert werden, die von Fin ausgelöst werden, bis zu 14 Tage lang aufgezeichnet. 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 Datenconnectoren verwenden, um Attribute zu senden, wenn ich ein Fin-Gespräch 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:

  • 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 hier mehr 👉 Hand-off mit JavaScript

2. Übergabe an URL

Diese Option leitet den user nur auf eine bestimmte Seite weiter, sie sendet kein POST und überträgt keine Konversationsdaten. Daher ist sie nicht geeignet, wenn Sie versuchen, JSON zu POSTEN.

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'
})
});
}

Hat dies deine Frage beantwortet?

Verwandte Artikel