TurboFlow

TurboFlow-Endpunkte

Mit TurboFlow erstellen Sie visuelle Workflows, veröffentlichen unveränderliche Versionen und lösen veröffentlichte Flows aus Ihrer App oder Ihrem Sprachassistenten aus. Die meisten Endpunkte verwenden Sitzungs-Cookie-Authentifizierung aus der Talkturo-App, während der Trigger-Endpunkt HMAC-Authentifizierung nutzt, damit externe Systeme einen veröffentlichten Flow sicher aufrufen können.

Endpunktübersicht

Authentifizierung

Die meisten TurboFlow-Endpunkte sind für die Flow-Verwaltung innerhalb des Produkts ausgelegt. Rufen Sie sie aus einer bei Talkturo authentifizierten Browser-Sitzung auf oder aus einem Backend, das ein gültiges Sitzungs-Cookie weiterleiten kann.

Sitzungsauthentifizierte Endpunkte

Verwenden Sie Sitzungsauth für:

• Flow-CRUD
• Veröffentlichen
• Testläufe
• Laufhistorie
• Integrationen
• Secrets
• Manifest und Tools
• AI-Builder-Endpunkte

Wenn Ihre Anfrage keiner gültigen Talkturo-Sitzung zugeordnet ist, scheitern diese Endpunkte, bevor die Geschäftslogik ausgeführt wird.

HMAC-authentifizierter Trigger-Endpunkt

Verwenden Sie HMAC-Auth für POST /api/flow/{flowId}/trigger. Dieser Endpunkt ist für externe Aufrufer und die Ausführung veröffentlichter Runtimes gedacht.

So erstellen Sie die Signatur:

import crypto from "crypto";

const flowId = "flow_72c9f2ab";
const triggerSecret = "tfsec_example_1k9n3d7s4h2m8q";
const body = JSON.stringify({
  params: {
    caller_name: "Jane Chen",
    booking_id: "bk_9d31a8f4",
    priority: "high"
  },
  context: {
    assistant_id: "asst_4f0c8b21"
  }
});

const signature = crypto
  .createHmac("sha256", triggerSecret)
  .update(body)
  .digest("hex");

const response = await fetch(
  `https://app.talkturo.com/api/flow/${flowId}/trigger?sync=true`,
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-Talkturo-Secret": signature
    },
    body
  }
);

const data = await response.json();
console.log(response.status, data);

import hashlib
import hmac
import json
import requests

flow_id = "flow_72c9f2ab"
trigger_secret = "tfsec_example_1k9n3d7s4h2m8q"

payload = {
    "params": {
        "caller_name": "Jane Chen",
        "booking_id": "bk_9d31a8f4",
        "priority": "high"
    },
    "context": {
        "assistant_id": "asst_4f0c8b21"
    }
}

body = json.dumps(payload, separators=(",", ":"))
signature = hmac.new(
    trigger_secret.encode("utf-8"),
    body.encode("utf-8"),
    hashlib.sha256
).hexdigest()

response = requests.post(
    f"https://app.talkturo.com/api/flow/{flow_id}/trigger?sync=true",
    headers={
        "Content-Type": "application/json",
        "X-Talkturo-Secret": signature,
    },
    data=body,
)

print(response.status_code, response.json())

BODY='{"params":{"caller_name":"Jane Chen","booking_id":"bk_9d31a8f4","priority":"high"},"context":{"assistant_id":"asst_4f0c8b21"}}'
SECRET='tfsec_example_1k9n3d7s4h2m8q'
SIGNATURE=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$SECRET" -hex | sed 's/^.* //')

curl -X POST "https://app.talkturo.com/api/flow/flow_72c9f2ab/trigger?sync=true" \
  -H "Content-Type: application/json" \
  -H "X-Talkturo-Secret: $SIGNATURE" \
  -d "$BODY"

Flows erstellen und verwalten

Mit diesen Endpunkten erstellen Sie Entwurfs-Flows, rufen bestehende Definitionen ab, aktualisieren sie und archivieren sie, wenn sie nicht mehr benötigt werden.

Flows auflisten

GET /api/flow

Gibt die Flows zurück, die im Kontext der aktuellen authentifizierten Sitzung verfügbar sind.

Flow erstellen

POST /api/flow

Erstellt einen neuen Entwurfs-Flow.

Flow abrufen, aktualisieren oder archivieren

GET /api/flow/{flowId} ruft die aktuelle Flow-Definition ab. PATCH /api/flow/{flowId} aktualisiert den Entwurf. DELETE /api/flow/{flowId} archiviert den Flow.

Pfadparameter

Aktualisierungsverhalten

Verwenden Sie PATCH /api/flow/{flowId}, um Metadaten oder Struktur des Entwurfs zu ändern. Das Veröffentlichen erzeugt eine ausführbare Version; das Aktualisieren des Entwurfs wirkt sich nicht auf bereits veröffentlichte Versionen aus, bis Sie erneut veröffentlichen.

Archivierungsverhalten

Verwenden Sie DELETE /api/flow/{flowId}, um einen Flow zu archivieren. Behandeln Sie dies als Verwaltungsoperation, nicht als Runtime-Stoppmechanismus für bereits abgeschlossene Läufe.

Flow veröffentlichen

POST /api/flow/{flowId}/publish

Das Veröffentlichen erzeugt eine neue ausführbare Version des Flows. Trigger-Anfragen werden gegen eine veröffentlichte Version ausgeführt, nicht gegen einen unveröffentlichten Entwurf.

Pfadparameter

Was das Veröffentlichen ändert

• Erzeugt einen versionierten Runtime-Snapshot
• Macht den Flow über den Trigger-Endpunkt auslösbar
• Ordnet die Runtime-Ausführung der veröffentlichten Version zu
• Ermöglicht HMAC-basierte externe Aufrufe über das trigger_secret der Version

Veröffentlichten Flow auslösen

POST /api/flow/{flowId}/trigger

Dies ist der Runtime-Einstiegspunkt für TurboFlow. Er führt einen veröffentlichten Flow mit vom Aufrufer gelieferten Parametern und optionalem Ausführungskontext aus.

Query-Parameter

Header

Request-Body

Async-Trigger-Beispiel

Der Async-Modus gibt sofort eine Laufkennung zurück. Verwenden Sie ihn, wenn der Aufrufer Ergebnisse später abfragen oder beobachten kann.

Async-Antwortfelder

Sync-Trigger-Beispiel

Der Sync-Modus wartet bis zu etwa 30 Sekunden auf den Abschluss des Flows und gibt die finale Ausgabe inline zurück.

Sync-Antwortfelder

Sync oder Async wählen

Flow vor dem Veröffentlichen testen

TurboFlow bietet Test-Endpunkte, um Entwurfsverhalten zu validieren, ohne den veröffentlichten Trigger-Pfad zu verwenden.

Gesamten Flow im Testmodus ausführen

POST /api/flow/{flowId}/test-run

Führt den Flow im Testmodus aus. Verwenden Sie dies beim Erstellen eines Entwurfs oder beim Validieren von Änderungen vor dem Veröffentlichen.

Pfadparameter

Einzelnen Node im Testmodus ausführen

POST /api/flow/{flowId}/test-run/node

Führt einen Node isoliert aus. Nutzen Sie ihn, um Tool-Konfiguration, Eingabe-Mapping oder Branch-Logik zu debuggen, ohne den gesamten Graphen auszuführen.

Pfadparameter

Laufhistorie prüfen

GET /api/flow/{flowId}/runs

Gibt historische Ausführungen für einen Flow zurück. Nutzen Sie die Laufhistorie, um Produktionstrigger zu prüfen, Fehler zu untersuchen und externe Ereignisse mit TurboFlow-Ausführungen zu korrelieren.

Pfadparameter

Wofür die Laufhistorie dient

• Prüfen, ob Async-Trigger-Anfragen angenommen und ausgeführt wurden
• Fehlgeschlagene Läufe nach Sync- oder Async-Ausführung untersuchen
• Runtime-Verhalten einer veröffentlichten Flow-Version prüfen
• Eine run_id aus der Trigger-Antwort mit gespeicherten Ausführungsdatensätzen korrelieren

Manifest und Tools

Diese Endpunkte helfen Ihnen zu erkennen, womit TurboFlow verbunden werden kann und wie ein bestimmter Flow Tool-Verhalten exponiert.

Connector-Manifest abrufen

GET /api/flow/manifest

Gibt das Connector-Manifest zurück, das der Workflow-Builder verwendet. Nutzen Sie es, um verfügbare Integrationsfähigkeiten und von der Plattform exponierte Tool-Definitionen zu prüfen.

Verfügbare Tools auflisten

GET /api/flow/tools

Gibt die Connectoren und Tools zurück, die dem aktuellen Konto und der Umgebung zur Verfügung stehen.

Flow-Tool-Schema abrufen

GET /api/flow/{flowId}/tool-schema

Gibt Tool-Schema-Informationen für einen bestimmten Flow zurück.

Integrationen verwalten

TurboFlow-Integrationen ermöglichen Flows die Verbindung zu externen Providern und das Abrufen providerspezifischer Konfigurationsoptionen.

Integrations-Endpunkte

• GET /api/flow/integrations
• POST /api/flow/integrations
• DELETE /api/flow/integrations
• GET /api/flow/integrations/{integrationId}
• DELETE /api/flow/integrations/{integrationId}
• GET /api/flow/integrations/{integrationId}/options

OAuth-Flow

Verwenden Sie die OAuth-Endpunkte, wenn eine Integration delegierten Zugriff erfordert.

Provider-Webhooks

TurboFlow stellt außerdem eingehende Webhook-Handler für unterstützte Provider bereit.

• POST /api/flow/integrations/webhooks/{provider} empfängt Provider-Webhook-Zustellungen für unterstützte Integrationen wie Cal.com, Calendly und Slack.
• GET /api/flow/integrations/webhooks/meta verarbeitet die Verifizierung für die Meta-Webhook-Einrichtung.
• POST /api/flow/integrations/webhooks/meta empfängt Meta-Lead-Ads-Webhook-Events.

Secrets verwalten

Secrets speichern verschlüsselte Anmeldedaten und Provider-Konfigurationen, die von Flows und Integrationen verwendet werden.

Secret-Endpunkte

• GET /api/flow/secrets
• POST /api/flow/secrets
• DELETE /api/flow/secrets
• GET /api/flow/secrets/{secretId}
• DELETE /api/flow/secrets/{secretId}
• GET /api/flow/secrets/providers

Pfadparameter

Secret-Provider

GET /api/flow/secrets/providers listet die verfügbaren Secret-Provider auf, die TurboFlow für verschlüsselte Secret-Speicherung und Verbindungsverwaltung nutzen kann.

AI-Builder-Endpunkte verwenden

Die AI-Builder-Endpunkte helfen dabei, Flow-Definitionen aus Anweisungen in natürlicher Sprache zu erzeugen oder zu verfeinern.

Streaming-Builder-Endpunkt

GET /api/flow/ai/robert und POST /api/flow/ai/robert

Verwenden Sie diese Endpunkte für KI-gestütztes Flow-Building mit Streaming-Verhalten. Die Route unterstützt sowohl GET als auch POST.

Verwandte AI-Endpunkte

• POST /api/flow/ai/robert-batch für Batch-AI-Flow-Building
• POST /api/flow/ai/describe-parameter zum Erzeugen einer Flow-Parameterbeschreibung
• POST /api/flow/ai/describe-tool zum Erzeugen einer Tool-Beschreibung

Typischer Workflow

Diese Sequenz zeigt, wie der Hauptlebenszyklus von der Entwurfserstellung bis zur externen Ausführung zusammenhängt.

Verwandte Endpunkte