SDK-Migrationen

Migration zu SDK 4.0 und der v3-Session-API

Stelle Python- und PHP-Code von den v2-Flow-Session-Aufrufen auf v3 um, das die Session-ID in einem Header sendet.

Die v2-Session-API wird am 30. November 2026 eingestellt

SDK 4.0.0 markiert die v2-Flow-Session-Aufrufe wie create_flow_session, invoke_flow_response und poll_flow_response als veraltet. Die v2-Session-Routen werden am 30. November 2026 eingestellt. Stelle deinen Code bis dahin auf die v3-Aufrufe auf dieser Seite um.

Version 4.0.0 der FlowHunt Python- und PHP-SDKs bringt die v3-Flow-Session-API. Der Umstieg hält deine Chat-Session-IDs aus URLs heraus, und der größte Teil der Arbeit besteht darin, Methoden umzubenennen. Diese Seite zeigt, was sich geändert hat, welche Aufrufe umbenannt werden müssen und den Code vorher und nachher.

Was sich geändert hat#

v3-Session-Aufrufe übergeben die Session-ID im Header X-FH-Session-Id, nie in der URL. Die Request- und Response-Bodies sind dieselben wie in v2. Die v2-Session-Routen sind veraltet und werden am 30. November 2026 eingestellt.

In v2 setzt jeder Chat-Aufruf die Session-ID in den Pfad, zum Beispiel /v2/flows/sessions/{session_id}/invoke. Die Session-ID ist die einzige Berechtigung, die eine anonyme Chat-Session hat, und URLs landen in Access-Logs, Proxy-Logs, im Browserverlauf und in Referer-Headern. Ein Header nicht.

4.0.0 installieren#

Python

Das Paket auf PyPI ist flowhunt.

bash
pip install --upgrade "flowhunt>=4,<5"

PHP

Das Paket auf Packagist ist flowhunt/flowhunt-php-sdk. Es benötigt PHP 8.1 oder neuer.

bash
composer require flowhunt/flowhunt-php-sdk:^4.0

Migration in vier Schritten#

  1. Paket aktualisieren

    Installiere 4.0.0 wie oben beschrieben. Deine bestehenden v2-Aufrufe funktionieren nach dem Upgrade weiter, du kannst also jeweils einen Aufruf umstellen. Schließe die Migration vor dem 30. November 2026 ab.

  2. Jeden Session-Aufruf umbenennen

    Hänge _v3 an den Python-Methodennamen oder V3 an den PHP-Namen an. Die Methodenzuordnung listet jedes Paar auf.

  3. Session-ID als Header-Argument übergeben

    Das Session-ID-Argument heißt jetzt x_fh_session_id. In Python übergibst du es per Keyword. In PHP nehmen drei Methoden es an zweiter statt an erster Stelle. Siehe geänderte Argumentreihenfolge bei drei Methoden.

  4. Entfernte Methoden prüfen

    Wenn du eine der in 4.0.0 entfernten Methoden aufrufst, wechsle auf den Ersatz oder entferne den Aufruf.

Methodenzuordnung#

Python-Methoden liegen auf flowhunt.FlowsApi, und dieselben v3-Methoden gibt es auch auf flowhunt.V3Api. PHP-Methoden liegen auf FlowHunt\Api\FlowsApi.

Wasv2 HTTPv3 HTTP (Session-ID in X-FH-Session-Id)Python 3.x → 4.0PHP 3.x → 4.0
Flow-Session starten (API-Key)POST /v2/flows/sessions/from_flow/createPOST /v3/flows/sessions/from_flow/createcreate_flow_session → create_flow_session_v3createFlowSession → createFlowSessionV3
Chatbot-Session starten (anonym)POST /v2/flows/sessions/createPOST /v3/flows/sessions/createcreate_chatbot_session → create_chatbot_session_v3createChatbotSession → createChatbotSessionV3
Nachricht sendenPOST /v2/flows/sessions/{id}/invokePOST /v3/flows/sessions/invokeinvoke_flow_response → invoke_flow_response_v3invokeFlowResponse → invokeFlowResponseV3
Auf Events pollenPOST /v2/flows/sessions/{id}/invocation_response/{from_timestamp}POST /v3/flows/sessions/invocation_response/{from_timestamp}poll_flow_response → poll_flow_response_v3pollFlowResponse → pollFlowResponseV3
Lauf abbrechenPOST /v2/flows/sessions/{id}/cancelPOST /v3/flows/sessions/cancelcancel_flow_session → cancel_flow_session_v3cancelFlowSession → cancelFlowSessionV3
Zum vorherigen Anker zurückPOST /v2/flows/sessions/{id}/backPOST /v3/flows/sessions/backgo_back → go_back_v3goBack → goBackV3
Chat-Hook auslösenPOST /v2/flows/sessions/{id}/hookPOST /v3/flows/sessions/hookfire_chat_hook → fire_chat_hook_v3fireChatHook → fireChatHookV3
Wartenden Hook fortsetzenPOST /v2/flows/sessions/{id}/resume-hookPOST /v3/flows/sessions/resume-hookresume_hook → resume_hook_v3resumeHook → resumeHookV3
Flow-Variablen setzenPATCH /v2/flows/sessions/{id}/variablesPATCH /v3/flows/sessions/variablesupdate_session_variables → update_session_variables_v3updateSessionVariables → updateSessionVariablesV3
Anhänge auflistenGET /v2/flows/sessions/{id}/attachmentsGET /v3/flows/sessions/attachmentsget_attachments → get_attachments_v3getAttachments → getAttachmentsV3
Anhang hochladenPOST /v2/flows/sessions/{id}/attachmentsPOST /v3/flows/sessions/attachmentsupload_attachments → upload_attachments_v3uploadAttachments → uploadAttachmentsV3
Anhang löschenDELETE /v2/flows/sessions/{id}/attachments/{file_id}DELETE /v3/flows/sessions/attachments/{file_id}delete_attachment → delete_attachment_v3deleteAttachment → deleteAttachmentV3
Nachrichten-FeedbackPOST /v2/flows/sessions/{id}/feedbackPOST /v3/flows/sessions/feedbackcreate_message_feedback → create_message_feedback_v3createMessageFeedback → createMessageFeedbackV3
Artefakt lesenGET /v2/flows/sessions/{id}/artefacts/{artefact_id}GET /v3/flows/sessions/artefacts/{artefact_id}get_artefact_content → get_artefact_content_v3getArtefactContent → getArtefactContentV3
Suche bei Eingabe (neu, kein v2)keinePOST /v3/flows/sessions/searchinvoke_search_v3invokeSearchV3

Das Herunterladen eines Anhangs (GET /v2/flows/sessions/{id}/attachments/{file_id}) hat keine v3-Version. Es ist ein Aufruf aus dem angemeldeten Dashboard und nicht Teil dieser Migration.

Nur die beiden Create-Aufrufe benötigen deinen API-Key. from_flow/create startet eine Session für einen Flow in deinem Workspace und erfordert den Key. create ist die anonyme Chatbot-Session, die das eingebettete Chat-Widget verwendet, und benötigt keinen Key. Beide geben session_id und created_at mit HTTP 201 zurück. Jeder andere v3-Session-Aufruf benötigt nur den Header X-FH-Session-Id.

Anhänge vorerst über HTTP hochladen

In 4.0.0 können upload_attachments_v3 und uploadAttachmentsV3 keine Datei senden. Die API gibt 422 “Expected UploadFile” zurück, und die Python-Methode weist Bytes bereits vor dem Senden der Anfrage ab. Die Upload-Methoden aus 3.x haben dasselbe Problem. Sende die Datei bis zur Behebung als multipart/form-data an POST /v3/flows/sessions/attachments mit dem Header X-FH-Session-Id. Der HTTP-Tab unten zeigt den Aufruf.

Vorher und nachher#

Dieses Beispiel startet eine Session für einen veröffentlichten Flow, sendet “Hello” und gibt die Antwort des Flows aus. Jeder Tab zeigt zuerst den 3.x-Code, dann den 4.0-Code, den wir gegen https://api.flowhunt.io ausgeführt haben. Der 4.0-Code liest den API-Key, die Workspace-ID und die Flow-ID aus den Umgebungsvariablen FLOWHUNT_API_KEY, FLOWHUNT_WORKSPACE_ID und FLOWHUNT_FLOW_ID.

Python

Python, SDK 3.x
session = flows.create_flow_session(workspace_id, flowhunt.FlowSessionCreateFromFlowRequest(flow_id=FLOW_ID))
invocation = flows.invoke_flow_response(session.session_id, flowhunt.FlowSessionInvokeRequest(message="Hello"))
events = flows.poll_flow_response(session.session_id, from_timestamp)
Python, SDK 4.0
import os
import time

import flowhunt

config = flowhunt.Configuration(host="https://api.flowhunt.io")
config.api_key["APIKeyHeader"] = os.environ["FLOWHUNT_API_KEY"]

with flowhunt.ApiClient(config) as client:
    flows = flowhunt.FlowsApi(client)

    session = flows.create_flow_session_v3(
        workspace_id=os.environ["FLOWHUNT_WORKSPACE_ID"],
        flow_session_create_from_flow_request=flowhunt.FlowSessionCreateFromFlowRequest(
            flow_id=os.environ["FLOWHUNT_FLOW_ID"]
        ),
    )
    session_id = session.session_id  # geheim halten, niemals loggen

    invocation = flows.invoke_flow_response_v3(
        x_fh_session_id=session_id,
        flow_session_invoke_request=flowhunt.FlowSessionInvokeRequest(message="Hello"),
    )

    since, seen, answered = int(invocation.created_at), set(), False
    for _ in range(60):
        time.sleep(2)
        events = flows.poll_flow_response_v3(
            x_fh_session_id=session_id, from_timestamp=since
        )
        new_events = [e for e in events if e.event_id not in seen]
        for event in new_events:
            seen.add(event.event_id)
            since = max(since, int(float(event.created_at_timestamp)) - 1)
            if event.action_type == "failed":
                raise RuntimeError("The flow run failed")
            if event.event_type == "ai" and event.action_type == "message":
                print(event.metadata.to_dict()["message"])
                answered = True
        if answered and not new_events:
            break

PHP

PHP, SDK 3.x
$session = $flows->createFlowSession($workspaceId, $request);
$invocation = $flows->invokeFlowResponse($session->getSessionId(), $invokeRequest);
$events = $flows->pollFlowResponse($session->getSessionId(), $fromTimestamp);
PHP, SDK 4.0
<?php
require 'vendor/autoload.php';

$config = FlowHunt\Configuration::getDefaultConfiguration()
    ->setHost('https://api.flowhunt.io')
    ->setApiKey('Api-Key', getenv('FLOWHUNT_API_KEY'));
$flows = new FlowHunt\Api\FlowsApi(new GuzzleHttp\Client(), $config);

$session = $flows->createFlowSessionV3(
    getenv('FLOWHUNT_WORKSPACE_ID'),
    new FlowHunt\Model\FlowSessionCreateFromFlowRequest(['flow_id' => getenv('FLOWHUNT_FLOW_ID')])
);
$sessionId = $session->getSessionId(); // keep secret, never log it

$invocation = $flows->invokeFlowResponseV3(
    $sessionId,
    new FlowHunt\Model\FlowSessionInvokeRequest(['message' => 'Hello'])
);

$since = (int) $invocation->getCreatedAt();
$seen = [];
$answered = false;
for ($i = 0; $i < 60; $i++) {
    sleep(2);
    // Beachte die Reihenfolge: zuerst der Zeitstempel, dann die Session-ID.
    $events = $flows->pollFlowResponseV3($since, $sessionId);
    $newEvents = array_filter($events, fn ($e) => !isset($seen[$e->getEventId()]));
    foreach ($newEvents as $event) {
        $seen[$event->getEventId()] = true;
        $since = max($since, (int) $event->getCreatedAtTimestamp() - 1);
        if ($event->getActionType() === 'failed') {
            throw new RuntimeException('The flow run failed');
        }
        if ($event->getEventType() === 'ai' && $event->getActionType() === 'message') {
            echo $event->getMetadata()->getMessage(), PHP_EOL;
            $answered = true;
        }
    }
    if ($answered && !$newEvents) {
        break;
    }
}

HTTP

Nur der Create-Aufruf sendet den API-Key. Jeder Aufruf danach sendet die Session-ID im Header X-FH-Session-Id.

Start a session (API key)
curl -X POST "https://api.flowhunt.io/v3/flows/sessions/from_flow/create?workspace_id=$WORKSPACE_ID" \
  -H "Api-Key: $FLOWHUNT_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"flow_id\": \"$FLOW_ID\"}"
Send a message
curl -X POST "https://api.flowhunt.io/v3/flows/sessions/invoke" \
  -H "X-FH-Session-Id: $SESSION_ID" \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello"}'
Poll for events
curl -X POST "https://api.flowhunt.io/v3/flows/sessions/invocation_response/$FROM_TIMESTAMP" \
  -H "X-FH-Session-Id: $SESSION_ID"
Upload an attachment
curl -X POST "https://api.flowhunt.io/v3/flows/sessions/attachments" \
  -H "X-FH-Session-Id: $SESSION_ID" \
  -F "file=@invoice.jpg;type=image/jpeg"

Früher war die Session-ID Teil jedes Pfads, zum Beispiel /v2/flows/sessions/$SESSION_ID/invoke. Ein v3-Aufruf ohne den Header gibt 401 zurück.

So funktioniert das Polling#

  • from_timestamp ist in Millisekunden seit der Epoche. Das Polling gibt die Events zurück, deren created_at_timestamp strikt größer ist.
  • Beginne mit dem created_at der Invoke-Response, einem Millisekundenwert, der als String gesendet wird, also wandle ihn in eine Ganzzahl um. Verwende 0, um die gesamte Session zu erhalten. Verwende nicht das created_at der Create-Response, das ein Datum und eine Uhrzeit ist, keine Millisekunden.
  • Verschiebe nach jedem Polling den from_timestamp auf den created_at_timestamp des neuesten Events minus 1 und überspringe Events, deren event_id du bereits gesehen hast. Events, die in derselben Millisekunde entstehen, können in unterschiedlichen Polls eintreffen. Das FlowHunt-Chat-Widget pollt auf dieselbe Weise.
  • Jedes Event hat einen event_type (ai, human oder system), einen action_type (message, loading, tool_call, failed, hook_waiting_for_input und andere) sowie metadata. Der Antworttext steht in metadata.message der ai-Events vom Typ message.

FlowHunt sendet kein separates “Lauf beendet”-Event. Als wir die Beispiele gegen einen einstufigen Flow ausgeführt haben, lieferte das Polling ein system-Event vom Typ loading, dann ein ai-Event vom Typ message mit der Antwort und danach nichts mehr. Deshalb hören die Beispiele beim ersten Polling auf, das nach einer eingetroffenen Antwort keine neuen Events bringt, und lösen bei failed einen Fehler aus. Wenn dein Flow mehrere Nachrichten sendet oder mit hook_waiting_for_input auf Eingaben wartet, musst du deine eigene Abbruchbedingung festlegen.

Geänderte Argumentreihenfolge bei drei Methoden#

Reihenfolge dieser drei Aufrufe ändern

Die v3-Methoden setzen Pfadparameter vor den Session-ID-Header. In PHP und in Python, wenn du Argumente positionsbasiert übergibst, schlagen diese drei Aufrufe mit einem Typfehler fehl oder senden stillschweigend die falschen Werte, wenn du sie nicht umsortierst.

v2v3
pollFlowResponse($session_id, $from_timestamp)pollFlowResponseV3($from_timestamp, $x_fh_session_id)
deleteAttachment($session_id, $file_id)deleteAttachmentV3($file_id, $x_fh_session_id)
getArtefactContent($session_id, $artefact_id)getArtefactContentV3($artefact_id, $x_fh_session_id)

Übergib in Python überall Keyword-Argumente, zum Beispiel x_fh_session_id=session_id, dann spielt die Reihenfolge keine Rolle mehr. Python 4.0 prüft außerdem die Argumenttypen, from_timestamp muss also ein int sein. Wird der String "0" übergeben, löst das einen pydantic ValidationError aus.

Weitere Breaking Changes in 4.0.0#

Diese Methoden gab es in 3.19.1, in 4.0.0 sind sie verschwunden, weil die dahinterliegenden API-Endpunkte entfernt oder geändert wurden. PHP-Methodennamen sind die camelCase-Form der Python-Namen, zum Beispiel wird get_available_models zu getAvailableModels.

Entfernte MethodeEndpunktWas zu tun ist
AgentGridsApi.get_agent_grid_previewGET /v2/agent_grids/{agent_grid_id}/previewAufruf entfernen.
CustomModelsApi.get_available_modelsGET /v2/custom-models/availableAufruf entfernen.
FineTuningsApi.create_image_ft, delete_image_ft, search_image_fts, update_image_ft/v2/photo_ai/images/...Aufrufe entfernen.
WorkspacesApi.update_workspace_auto_rechargePUT /v2/workspaces/{workspace_id}/auto-rechargeAufruf entfernen.
FlowBatchApi.export_csvGET /v2/flows/{flow_id}/batch/{batch_run_id}/export-csvstart_export_csv aufrufen (POST, gleicher Pfad), dann get_export_csv_status (GET .../export-csv/{task_id}).

Die Methoden für den Zendesk-Kanal, die Shopify-Abrechnung sowie Replicate- und SERP-Pingback-Webhooks wurden ebenfalls entfernt. Das sind eingehende Webhooks für die eigenen Server von FlowHunt, keine Aufrufe aus deinem Code.

Session-ID geheim halten#

Die Session-ID ist eine Berechtigung

Jeder, der eine Session-ID besitzt, kann diese Konversation lesen und fortsetzen. Logge sie nicht, packe sie nicht in URLs oder Query-Strings und sende sie nicht an Analysedienste. Behandle sie wie ein kurzlebiges Passwort.

Was ist mit v2?#

Die v2-Session-Routen sind seit SDK 4.0.0 veraltet und werden am 30. November 2026 eingestellt. Bis dahin funktionieren sie weiter und sind in der API-Referenz als veraltet markiert. SDK 4.0.0 enthält die v2-Methoden noch. In Python löst ein Aufruf eine DeprecationWarning aus. In PHP sind sie im Code als @deprecated markiert, was deine IDE oder statische Analyse anzeigt.