Integrationen

Integrationen ermöglichen die Anbindung externer Systeme an die Mercury.ai Plattform, ohne dass eine Programmierung erforderlich ist. Sie können in Workflows sowohl als Trigger (Auslöser) als auch als Schritt (Aktion) eingesetzt werden.

Grundlagen

Bei Integrationen wird grundlegend zwischen der Richtung des Aufrufs unterschieden:

Inbound-Integration: Ein externes System ruft einen von Mercury.ai bereitgestellten Webhook auf.
Outbound-Integration: Die Mercury.ai Plattform ruft einen externen Dienst oder eine API auf.

Inbound-Integrationen

Inbound-Integrationen erlauben es externen Systemen, Informationen an Mercury.ai zu senden oder Aktionen (wie das Versenden einer WhatsApp-Vorlage) auszulösen. Eine Inbound-Integration ist von außen erreichbar, wenn sie als Trigger in einem Workflow konfiguriert ist.

Die Integration extrahiert Daten aus dem eingehenden Request und reicht diese an den Workflow weiter. Der Workflow verarbeitet die Daten und kann eine Antwort (Response) an den Aufrufer zurückgeben.

1. Your Webhook

Beim Anlegen einer Integration wird automatisch ein eindeutiger Webhook erzeugt.

Sicherheit: Über ein zuvor definiertes Secret kann der Webhook mittels Standard-Authentifizierung abgesichert werden.

2. Captured Payload

Hier wird der zuletzt empfangene Payload (meist JSON) des Webhooks angezeigt.

Nutzen: Dies erleichtert die Konfiguration der Datenextraktion.
Datenschutz: Da Payloads personenbezogene Daten enthalten können, werden sie nur kurzzeitig angezeigt und nach einiger Zeit automatisch gelöscht.

3. Workflow Input

Hier definieren Sie, welche Daten aus dem HTTP-Request extrahiert werden sollen. Ein Request besteht aus Headern und einem Body:

{
  "headers": [
    { "content-type" : "application/json" }
  ],
  "body": {
    "parameter" : "Hello World",
    "userId" : "123456"
  }
}

Um beispielsweise die userId zu extrahieren:

Legen Sie einen neuen Input an.
Wählen Sie einen freien Key (dient der Referenzierung im Workflow).
Nutzen Sie JSON Path, um den Wert zu adressieren (z. B. $.body.userId).

Erfahren Sie mehr über JSON Path.

4. Workflow Output

Definition von Key-Value-Paaren, die nach der Workflow-Ausführung an die Integration zurückgegeben werden.

Diese Werte können im Response Body verwendet werden.
Default-Werte: Falls der Workflow einen Wert nicht setzt, kann hier ein Standardwert definiert werden.

5. Response Body

Hier legen Sie fest, was der aufrufende Dienst als Antwort erhält. Es kann auf die Variablen aus dem Workflow Output zugegriffen werden.

Outbound-Integrationen

Outbound-Integrationen dienen dazu, externe APIs innerhalb eines Workflows anzusprechen. Sie werden als Schritt (Step) in einen Workflow eingebaut.

1. Input Definition

Variablen, die für den API-Aufruf benötigt werden (z. B. Parameter für die URL oder den Body).

Diese Variablen werden im Workflow mit dynamischen Werten gefüllt.
Example Value: Dieser Wert wird ausschließlich für die Test-Funktion verwendet.
Default Value: Wird genutzt, falls der Workflow keinen Wert übergibt.

2. Authentication

Wählen Sie ein Secret aus, um den API-Call abzusichern. Bei Token-basierten Secrets wird das Token automatisch dem Header hinzugefügt.

3. Your API Call

Hier konfigurieren Sie den Endpunkt und die Header.

Content-Type: Mindestens dieser Header muss gesetzt sein. Unterstützte Typen:
- application/json: Versendet den Body als JSON.
- none: Versendet den Body uninterpretiert.
- application/x-www-form-urlencoded: Für Key-Value-Paare.
- multipart/form-data: Für Binärdateien (z. B. Media-Assets).

4. Test

Über den Send-Button können Sie den API-Call mit den hinterlegten Example-Values prüfen. Das detaillierte Execution Log hilft bei der Fehlersuche.

5. Output Definition

Extrahieren von Daten aus der API-Antwort mittels JSON Path. Diese Werte stehen anschließend im Workflow zur Verfügung.