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.
pip install --upgrade "flowhunt>=4,<5"PHP
Das Paket auf Packagist ist flowhunt/flowhunt-php-sdk. Es benötigt PHP 8.1 oder neuer.
composer require flowhunt/flowhunt-php-sdk:^4.0Migration in vier Schritten#
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.
Jeden Session-Aufruf umbenennen
Hänge
_v3an den Python-Methodennamen oderV3an den PHP-Namen an. Die Methodenzuordnung listet jedes Paar auf.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.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.
| Was | v2 HTTP | v3 HTTP (Session-ID in X-FH-Session-Id) | Python 3.x → 4.0 | PHP 3.x → 4.0 |
|---|---|---|---|---|
| Flow-Session starten (API-Key) | POST /v2/flows/sessions/from_flow/create | POST /v3/flows/sessions/from_flow/create | create_flow_session → create_flow_session_v3 | createFlowSession → createFlowSessionV3 |
| Chatbot-Session starten (anonym) | POST /v2/flows/sessions/create | POST /v3/flows/sessions/create | create_chatbot_session → create_chatbot_session_v3 | createChatbotSession → createChatbotSessionV3 |
| Nachricht senden | POST /v2/flows/sessions/{id}/invoke | POST /v3/flows/sessions/invoke | invoke_flow_response → invoke_flow_response_v3 | invokeFlowResponse → invokeFlowResponseV3 |
| Auf Events pollen | POST /v2/flows/sessions/{id}/invocation_response/{from_timestamp} | POST /v3/flows/sessions/invocation_response/{from_timestamp} | poll_flow_response → poll_flow_response_v3 | pollFlowResponse → pollFlowResponseV3 |
| Lauf abbrechen | POST /v2/flows/sessions/{id}/cancel | POST /v3/flows/sessions/cancel | cancel_flow_session → cancel_flow_session_v3 | cancelFlowSession → cancelFlowSessionV3 |
| Zum vorherigen Anker zurück | POST /v2/flows/sessions/{id}/back | POST /v3/flows/sessions/back | go_back → go_back_v3 | goBack → goBackV3 |
| Chat-Hook auslösen | POST /v2/flows/sessions/{id}/hook | POST /v3/flows/sessions/hook | fire_chat_hook → fire_chat_hook_v3 | fireChatHook → fireChatHookV3 |
| Wartenden Hook fortsetzen | POST /v2/flows/sessions/{id}/resume-hook | POST /v3/flows/sessions/resume-hook | resume_hook → resume_hook_v3 | resumeHook → resumeHookV3 |
| Flow-Variablen setzen | PATCH /v2/flows/sessions/{id}/variables | PATCH /v3/flows/sessions/variables | update_session_variables → update_session_variables_v3 | updateSessionVariables → updateSessionVariablesV3 |
| Anhänge auflisten | GET /v2/flows/sessions/{id}/attachments | GET /v3/flows/sessions/attachments | get_attachments → get_attachments_v3 | getAttachments → getAttachmentsV3 |
| Anhang hochladen | POST /v2/flows/sessions/{id}/attachments | POST /v3/flows/sessions/attachments | upload_attachments → upload_attachments_v3 | uploadAttachments → uploadAttachmentsV3 |
| Anhang löschen | DELETE /v2/flows/sessions/{id}/attachments/{file_id} | DELETE /v3/flows/sessions/attachments/{file_id} | delete_attachment → delete_attachment_v3 | deleteAttachment → deleteAttachmentV3 |
| Nachrichten-Feedback | POST /v2/flows/sessions/{id}/feedback | POST /v3/flows/sessions/feedback | create_message_feedback → create_message_feedback_v3 | createMessageFeedback → createMessageFeedbackV3 |
| Artefakt lesen | GET /v2/flows/sessions/{id}/artefacts/{artefact_id} | GET /v3/flows/sessions/artefacts/{artefact_id} | get_artefact_content → get_artefact_content_v3 | getArtefactContent → getArtefactContentV3 |
| Suche bei Eingabe (neu, kein v2) | keine | POST /v3/flows/sessions/search | invoke_search_v3 | invokeSearchV3 |
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
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)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:
breakPHP
$session = $flows->createFlowSession($workspaceId, $request);
$invocation = $flows->invokeFlowResponse($session->getSessionId(), $invokeRequest);
$events = $flows->pollFlowResponse($session->getSessionId(), $fromTimestamp);<?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.
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\"}"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"}'curl -X POST "https://api.flowhunt.io/v3/flows/sessions/invocation_response/$FROM_TIMESTAMP" \
-H "X-FH-Session-Id: $SESSION_ID"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_timestampist in Millisekunden seit der Epoche. Das Polling gibt die Events zurück, derencreated_at_timestampstrikt größer ist.- Beginne mit dem
created_atder Invoke-Response, einem Millisekundenwert, der als String gesendet wird, also wandle ihn in eine Ganzzahl um. Verwende0, um die gesamte Session zu erhalten. Verwende nicht dascreated_atder Create-Response, das ein Datum und eine Uhrzeit ist, keine Millisekunden. - Verschiebe nach jedem Polling den
from_timestampauf dencreated_at_timestampdes neuesten Events minus 1 und überspringe Events, derenevent_iddu 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,humanodersystem), einenaction_type(message,loading,tool_call,failed,hook_waiting_for_inputund andere) sowiemetadata. Der Antworttext steht inmetadata.messagederai-Events vom Typmessage.
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.
| v2 | v3 |
|---|---|
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 Methode | Endpunkt | Was zu tun ist |
|---|---|---|
AgentGridsApi.get_agent_grid_preview | GET /v2/agent_grids/{agent_grid_id}/preview | Aufruf entfernen. |
CustomModelsApi.get_available_models | GET /v2/custom-models/available | Aufruf entfernen. |
FineTuningsApi.create_image_ft, delete_image_ft, search_image_fts, update_image_ft | /v2/photo_ai/images/... | Aufrufe entfernen. |
WorkspacesApi.update_workspace_auto_recharge | PUT /v2/workspaces/{workspace_id}/auto-recharge | Aufruf entfernen. |
FlowBatchApi.export_csv | GET /v2/flows/{flow_id}/batch/{batch_run_id}/export-csv | start_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.