> For the complete documentation index, see [llms.txt](https://replyx-docs.sematell.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://replyx-docs.sematell.com/how-to/admins/integrations/custom-integrations.md). # Custom Integrations Über Custom Integrations können von Admins flexibel über eigene **Connections und Tools für individuelle Systeme und APIs** konfiguriert werden. Als Admin konfigurierst du eine **individuelle Integration**, wenn ReplyX auf Daten oder Funktionen eines Drittsystems zugreifen soll und dafür keine passende Standard-Integration vorhanden ist. Eine individuelle Integration besteht aus: * einer **Connection** * einem oder mehreren **Tools** Die Connection definiert, wie ReplyX das Drittsystem erreicht und sich authentifiziert. Ein Tool definiert, welchen konkreten API-Aufruf ReplyX gegenüber diesem System ausführen kann. ## Bevor du startest Du brauchst Admin-Rechte in der Organisation. Kläre außerdem: * welches Drittsystem angebunden werden soll * welche Zugangsdaten benötigt werden * welche Authentifizierung das System unterstützt * welche API-Endpunkte ReplyX aufrufen soll * welche Eingabewerte diese Endpunkte benötigen * welche Daten die API zurückliefert * ob die Integration in Workflows oder für die Geschäftspartneridentifikation verwendet werden soll Wenn das Drittsystem eine IP-Allowlist verwendet, prüfe zusätzlich die erforderlichen IP-Freigaben. PM-\_RX Documentation-021026-042… ## Individuelle Integration als Connection anlegen Öffne den Bereich **Integrationen** und füge eine neue individuelle Integration hinzu. Vergib einen eindeutigen Namen und konfiguriere die Connection. ### Authentifizierung auswählen ReplyX unterstützt für individuelle Connections: * **Basic Authentication** * **Token Authentication** #### Basic Authentication Bei Basic Authentication verwendet ReplyX Benutzername und Passwort zur Authentifizierung gegenüber dem Drittsystem. Der Authorization Header wird für die Requests der Connection verwendet. #### Token Authentication Bei Token Authentication verwendet ReplyX einen hinterlegten Token. Bei Bedarf kannst du zusätzlich einen Prefix für den Authorization Header konfigurieren. ### Einschränkungen Für individuelle Connections gilt aktuell: * jeder Request enthält die konfigurierte Authentifizierung * es gibt keinen automatischen Refresh-Mechanismus für Tokens * Cookie-basierte Authentifizierung wird nicht verwendet Speichere die Connection, wenn alle erforderlichen Angaben gültig sind. ### Mehrere individuelle Integrationen verwenden Du kannst innerhalb einer Organisation mehrere individuelle Integrationen anlegen. Jede Connection wird unabhängig konfiguriert. Dadurch kannst du beispielsweise: * mehrere unterschiedliche Drittsysteme anbinden * mehrere Connections zum gleichen System für unterschiedliche fachliche Zwecke verwenden * Tools aus unterschiedlichen Connections innerhalb verschiedener Workflows einsetzen Mehrere Connections können gleichzeitig aktiv sein. Eine fehlerhafte oder nicht erreichbare Connection verhindert nicht die Verwendung anderer Connections. ## Tools konfigurieren Tools beschreiben konkrete API-Aufrufe eines verbundenen Systems. Ein Tool repräsentiert einen HTTP-Aufruf mit einer der folgenden Methoden: * GET * POST * PUT * PATCH * DELETE ### Neues Tool anlegen Öffne die gewünschte Integration und füge ein neues Tool hinzu. Konfiguriere anschließend die erforderlichen Angaben. #### Name Vergib einen eindeutigen Namen. Der Name wird auch von der KI verwendet. Wähle deshalb eine fachlich eindeutige Bezeichnung. Beispiele: * Bestellung suchen * Kundendaten abrufen * Lieferstatus prüfen #### Beschreibung Beschreibe, was das Tool macht und wann es verwendet werden soll. Auch die Beschreibung wird von der KI verwendet. Formuliere deshalb möglichst konkret, welche fachliche Funktion das Tool bereitstellt. #### Methode Wähle die HTTP-Methode des API-Aufrufs: * GET * POST * PUT * PATCH * DELETE #### Eingabeparameter definieren Ein Tool kann Eingabeparameter (Input Parameters) besitzen. Für jeden Parameter definierst du: * Name * Beschreibung * Typ Unterstützte Typen sind: * string * number * boolean Name und Beschreibung der Parameter werden von der KI verwendet. Beschreibe deshalb eindeutig, welche Information der Parameter enthalten soll. Beispiele: * orderId – eindeutige Bestellnummer * referenceNumber – Referenznummer des Drittsystems * orderName – Bezeichnung oder Name einer Bestellung Standardmäßig sind Eingabeparameter **verpflichtend**. Du kannst Eingabeparameter jedoch als **optional** markieren. #### Optionale Eingabeparameter verwenden Optionale Eingabeparameter (Input Parameters) eignen sich, wenn ein Drittsystem denselben Datensatz über unterschiedliche Merkmale finden kann. Beispiel: Ein Drittsystem kann eine Bestellung über: * Bestellnummer * Referenznummer * Bestellname identifizieren. In einer eingehenden Nachricht ist möglicherweise nur einer dieser Werte vorhanden. In diesem Fall kannst du die entsprechenden Eingabeparameter als optional konfigurieren. ReplyX kann das Tool dann mit den Informationen ausführen, die aus der Nachricht tatsächlich ermittelt werden konnten. #### Mindestens einen optionalen Parameter verwenden Wenn ein Tool mehrere Eingabeparameter (Input Parameters) besitzt, kannst du die Option: **'Mindestens einen optionalen Parameter verwenden'** aktivieren. Ist diese Option aktiviert: * werden die Eingabeparameter automatisch als optional behandelt * ReplyX versucht, die Werte aus dem Inhalt der Nachricht zu ermitteln * das Tool wird ausgeführt, sobald mindestens ein geeigneter optionaler Parameter vorhanden ist * nicht alle optionalen Parameter müssen gefüllt sein Beispiel: Ein Tool besitzt folgende Eingabeparameter: * orderId * referenceNumber * orderName Enthält eine E-Mail nur eine Bestellnummer, kann ReplyX das Tool bereits mit orderId ausführen. Enthält sie stattdessen nur einen Bestellnamen, kann orderName für den Aufruf verwendet werden. Damit kann dasselbe Tool unterschiedliche Identifikationsmerkmale eines Drittsystems nutzen. **Verhalten bei manueller Konfiguration** Wenn du alle vorhandenen Eingabeparameter manuell als optional markierst, aktiviert ReplyX die Option **Mindestens einen optionalen Parameter verwenden**. #### Nur ein Eingabeparameter Wenn ein Tool nur einen Eingabeparameter besitzt, stehen die Optionen: * **Optional** * **Mindestens einen optionalen Parameter verwenden** nicht zur Verfügung. Bei nur einem Parameter ist diese Unterscheidung nicht erforderlich. #### Verhalten im Workflow Wenn ein Tool in einem Workflow verwendet wird, versucht ReplyX die benötigten Eingabewerte aus dem aktuellen Vorgang beziehungsweise der Nachricht zu bestimmen. Bei verpflichtenden Parametern müssen alle erforderlichen Werte vorhanden sein. Bei mehreren optionalen Parametern mit aktivierter Option **Mindestens einen optionalen Parameter verwenden** reicht es aus, wenn mindestens einer dieser Werte ermittelt werden kann. Nicht alle optionalen Eingabeparameter müssen gefüllt sein. ReplyX zeigt im Workflow dauerhaft einen entsprechenden Hinweis an, damit erkennbar ist, dass für den Tool-Aufruf nicht alle optionalen Werte benötigt werden. #### Wenn kein optionaler Parameter ermittelt werden kann Kann ReplyX keinen der erforderlichen optionalen Werte aus der Nachricht ermitteln, wird das Tool nicht mit unvollständigen Eingabedaten ausgeführt. Stattdessen greift der für diesen Fall vorgesehene **Fallback** im Workflow. Der Hinweis im Workflow macht deutlich, dass: * nicht alle optionalen Parameter benötigt werden * mindestens ein geeigneter Wert vorhanden sein muss * bei fehlenden Werten der Fallback verwendet wird Damit bleibt das Verhalten des Workflows auch bei unvollständigen Eingangsdaten nachvollziehbar. ### Request konfigurieren Die definierten Eingabeparameter (Input Parameters) kannst du innerhalb des Requests als variable Werte verwenden. #### Query-Parameter Konfiguriere Query-Parameter, wenn das Drittsystem Werte über die URL erwartet. Beispiel: /orders?id=\\&orderName=\ Bei optionalen Parametern kann abhängig vom Nachrichteninhalt beispielsweise nur orderId oder nur orderName befüllt sein. #### Header Füge zusätzliche HTTP-Header hinzu, wenn der API-Endpunkt sie benötigt. Eingabeparameter können auch als Werte innerhalb von Headern verwendet werden. Die Authentifizierung der Connection wird unabhängig davon bei den Requests berücksichtigt. #### Body Wenn der API-Aufruf einen Request Body benötigt, kannst du dessen Inhalt konfigurieren. Auch im Body können Eingabeparameter als variable Werte verwendet werden. ### Response Schema definieren Über das **Response Schema** beschreibst du die erwartete Antwort des API-Endpunkts. ReplyX verwendet dafür ein **JSON Schema**. Das Schema beschreibt die Struktur der Daten, die das Tool zurückliefert. Das Response Schema unterstützt auch: * verschachtelte Objekte * leere Objekte * Werte vom Typ null Achte darauf, dass das Schema die tatsächliche Antwort des Drittsystems korrekt beschreibt. ## Tools in einem Workflow verwenden Nach dem Speichern kann ein Tool innerhalb einer ReplyExperience verwendet werden. Öffne die gewünschte ReplyExperience und füge im Workflow eine Aufgabe vom Typ: **Integration aufrufen** hinzu. Wähle anschließend das gewünschte Tool. ReplyX kann dabei Tools aus mehreren Connections gleichzeitig anbieten. Beispielsweise können Tools aus: * Shopify * einer ersten individuellen Integration * einer weiteren individuellen Integration parallel für Workflows verfügbar sein. Nutze Integrationsaufrufe insbesondere dort, wo ein Prozess externen Kontext oder eine Aktion in einem Drittsystem benötigt. PM-\_RX Documentation-021026-042… ## Individuelle Integration für Geschäftspartneridentifikation verwenden Eine individuelle Integration kann auch für: * Geschäftspartneridentifikation * Kundendatenabruf verwendet werden. Dafür muss die Connection die dafür erforderlichen Tools bereitstellen. ReplyX berücksichtigt nur Connections, die: * einen Geschäftspartner anhand seiner E-Mail-Adresse identifizieren können * die erforderlichen Kundendaten abrufen können ### Connection für Geschäftspartneridentifikation auswählen Öffne die Integrationskonfiguration und wähle die Connection aus, die ReplyX für Geschäftspartneridentifikation und Kundendaten verwenden soll. Pro Organisation kannst du: * genau eine Connection oder * keine Connection für diesen Zweck auswählen. ReplyX verwendet die ausgewählte Connection anschließend, wenn: * ein Geschäftspartner identifiziert werden muss * Kundendaten für die Vorgangsbearbeitung benötigt werden Du kannst die ausgewählte Connection später ändern. Andere Connections bleiben weiterhin für Workflow-Aufrufe verfügbar. ## Tool bearbeiten Öffne die Integration und wähle das gewünschte Tool. Je nach Verwendung des Tools kannst du unterschiedliche Teile der Konfiguration bearbeiten. ### Tool wird noch nicht in einer ReplyExperience verwendet Solange das Tool noch in keiner ReplyExperience verwendet wird, kannst du die Tool-Konfiguration weiter bearbeiten. Dazu gehören unter anderem: * Name * Beschreibung * HTTP-Methode * Eingabeparameter * Kennzeichnung von Eingabeparametern als optional * Verwendung von mindestens einem optionalen Parameter * Query-Parameter * Header * Request Body * Response Example Damit kannst du ein neu angelegtes Tool zunächst vollständig konfigurieren und korrigieren, bevor es produktiv in einem Workflow verwendet wird. ### Tool wird bereits in einer ReplyExperience verwendet Sobald das Tool in mindestens einer ReplyExperience verwendet wird, sind bestimmte Teile der Konfiguration nicht mehr änderbar. **Read-only werden:** * Eingabeparameter * Response Example Diese Einschränkung verhindert Änderungen, die auf bestehende Workflows keine Wirkung hätten oder zu unterschiedlichen Konfigurationen zwischen Tool und Workflow führen könnten. ReplyX übernimmt Eingabeparameter und Response Example beim Einbinden des Tools in den Workflow. Nachträgliche Änderungen am ursprünglichen Tool würden deshalb nicht automatisch auf bestehende Workflow-Konfigurationen übertragen. ### Warum diese Einschränkung besteht Ein Workflow speichert relevante Teile der Tool-Konfiguration als Bestandteil seiner eigenen Konfiguration. Das bedeutet: **Tool-Konfiguration → Verwendung im Workflow → Kopie von Input Parameters und Response Example im Workflow** Dadurch können bestehende Vorgänge und Workflows weiterhin mit der Konfiguration arbeiten, die zum Zeitpunkt der Einbindung gültig war. Eine nachträgliche Änderung der Parameterstruktur am ursprünglichen Tool würde diese bereits übernommenen Informationen nicht automatisch aktualisieren. Um inkonsistente Konfigurationen zu vermeiden, verhindert ReplyX deshalb solche Änderungen. ### Eingabeparameter oder Response Example ändern Wenn du die Eingabeparameter oder das Response Example eines bereits verwendeten Tools ändern musst, kannst du das bestehende Tool dafür nicht direkt anpassen. Gehe stattdessen so vor: 1. Prüfe, in welchen ReplyExperiences das bestehende Tool verwendet wird. 2. Erstelle ein neues Tool mit der gewünschten Konfiguration. 3. Ersetze das bisherige Tool in den betroffenen ReplyExperiences durch das neue Tool. 4. Prüfe die Workflows und die erwartete Verarbeitung. 5. Entferne das alte Tool aus allen ReplyExperiences. 6. Lösche das alte Tool, wenn es nicht mehr benötigt wird. ### Bestehende Vorgänge Änderungen an einem Tool wirken nicht rückwirkend auf bereits bestehende Vorgänge, deren Workflow die Tool-Konfiguration bereits übernommen hat. Bestehende Vorgänge verwenden weiterhin die für ihren Workflow vorhandene Konfiguration. ### Ergebnis Du kannst ein neu angelegtes Tool vollständig bearbeiten, solange es noch nicht in einer ReplyExperience verwendet wird. Sobald das Tool in einem Workflow verwendet wird, bleiben **Eingabeparameter und Response Example unveränderlich**. Dadurch verhindert ReplyX Konfigurationsänderungen, die auf bestehende Workflows keine verlässliche Wirkung hätten. ## Tool löschen Du kannst ein Tool löschen, wenn es nicht mehr benötigt wird. Vor der Löschung prüft ReplyX, ob das Tool noch von einer ReplyExperience verwendet wird. ### Tool wird verwendet Wenn mindestens eine ReplyExperience das Tool verwendet: * kann das Tool nicht gelöscht werden * informiert ReplyX dich über die bestehende Abhängigkeit * werden die betroffenen ReplyExperiences angezeigt Entferne das Tool zunächst aus diesen Workflows. ### Tool wird nicht verwendet Wenn keine ReplyExperience das Tool verwendet, kannst du die Löschung bestätigen. Danach steht das Tool nicht mehr für ReplyExperiences zur Verfügung. ## Connection bearbeiten Du kannst eine bestehende individuelle Integration bearbeiten. Änderbar sind insbesondere: * Name * Credentials Bestehende Konfigurationen, die auf die Integration verweisen, behalten ihre Referenz auch nach einer Änderung von Name oder Credentials. Gespeicherte sensible Zugangsdaten werden nicht im Klartext angezeigt. ## Individuelle Integration löschen Beim Löschen einer Connection löscht ReplyX auch die zugehörigen Tools. Vor der Löschung prüft ReplyX deshalb, ob eines dieser Tools noch in einer ReplyExperience verwendet wird. Wenn mindestens ein Tool verwendet wird: * kann die Connection nicht gelöscht werden * informiert ReplyX dich über die bestehende Verwendung * kannst du erkennen, welche ReplyExperiences die Löschung verhindern Entferne zuerst die betreffenden Tools aus den Workflows. Anschließend kannst du die Connection löschen. Das Löschen einer Connection verändert oder entfernt keine ReplyExperience automatisch. ## Ergebnis Du hast ein Drittsystem über eine individuelle Integration mit ReplyX verbunden und die benötigten API-Aufrufe als Tools konfiguriert. Je nach Konfiguration kann ReplyX diese Integration verwenden, um: * externe Daten abzurufen * Aktionen in Drittsystemen auszuführen * Vorgänge mit zusätzlichem Kontext anzureichern * Tools innerhalb von ReplyExperience-Workflows aufzurufen * alternative Identifikationsmerkmale über optionale Eingabeparameter zu verwenden * ein Tool auszuführen, sobald mindestens ein geeigneter optionaler Wert aus einer Nachricht ermittelt werden kann * Geschäftspartner zu identifizieren * Kundendaten für die Vorgangsbearbeitung abzurufen Dadurch lassen sich weitere Drittsysteme flexibel in ReplyX-Prozesse integrieren, auch wenn die benötigten Identifikationsdaten je nach Kundenanfrage unterschiedlich vorliegen. ## Verwandte Themen * [Integrationen](/how-to/admins/integrations.md) * [IP-Adressen für Integrationen freigeben](/how-to/admins/integration-ip-whitelisting.md) * [ReplyExperiences anlegen und pflegen](/how-to/admins/reply-experiences.md) * [Workflows und Automatisierung gestalten](/how-to/admins/workflows-and-automation.md) * [Smart Conditions gestalten](/how-to/admins/smart-conditions.md) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://replyx-docs.sematell.com/how-to/admins/integrations/custom-integrations.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.