SDK-migreringer
Migrer til SDK 4.0 og v3-session-API'et
Flyt Python- og PHP-kode fra v2-flow-session-kaldene til v3, som sender session-id’et i en header.
v2-session-API'et udgår den 30. november 2026
SDK 4.0.0 markerer v2-flow-session-kaldene som forældede, for eksempel create_flow_session, invoke_flow_response og poll_flow_response. v2-sessionruterne udgår den 30. november 2026. Flyt din kode til v3-kaldene på denne side inden da.
Version 4.0.0 af FlowHunts Python- og PHP-SDK’er tilføjer v3-flow-session-API’et. Når du skifter til det, holdes dine chat-session-id’er ude af URL’er, og det meste af arbejdet består i at omdøbe metoder. Denne side viser, hvad der er ændret, hvilke kald du skal omdøbe, og koden før og efter.
Hvad er ændret#
v3-sessionskald tager session-id’et i headeren X-FH-Session-Id, aldrig i URL’en. Request- og response-bodies er de samme som i v2. v2-sessionruterne er forældede og udgår den 30. november 2026.
I v2 lægger hvert chatkald session-id’et i stien, for eksempel /v2/flows/sessions/{session_id}/invoke. Session-id’et er den eneste legitimationsoplysning, en anonym chatsession har, og URL’er ender i accesslogs, proxylogs, browserhistorik og Referer-headere. Det gør en header ikke.
Installér 4.0.0#
Python
Pakken på PyPI hedder flowhunt.
pip install --upgrade "flowhunt>=4,<5"PHP
Pakken på Packagist hedder flowhunt/flowhunt-php-sdk. Den kræver PHP 8.1 eller nyere.
composer require flowhunt/flowhunt-php-sdk:^4.0Migrér i fire trin#
Opgrader pakken
Installér 4.0.0 som vist ovenfor. Dine eksisterende v2-kald virker stadig efter opgraderingen, så du kan flytte ét kald ad gangen. Afslut inden den 30. november 2026.
Omdøb hvert sessionskald
Tilføj
_v3til Python-metodens navn ellerV3til PHP-metodens. Metodetilknytningen viser hvert par.Send session-id’et som header-argument
Argumentet for session-id er nu
x_fh_session_id. I Python sendes det som keyword-argument. I PHP tager tre metoder det som det andet argument i stedet for det første. Se argumentrækkefølgen er ændret for tre metoder.Tjek de fjernede metoder
Hvis du kalder nogen af de metoder, der er fjernet i 4.0.0, skal du skifte til erstatningen eller fjerne kaldet.
Metodetilknytning#
Python-metoderne ligger på flowhunt.FlowsApi, og de samme v3-metoder findes også på flowhunt.V3Api. PHP-metoderne ligger på FlowHunt\Api\FlowsApi.
| Hvad | v2 HTTP | v3 HTTP (session-id i X-FH-Session-Id) | Python 3.x → 4.0 | PHP 3.x → 4.0 |
|---|---|---|---|---|
| Start flowsession (API-nøgle) | POST /v2/flows/sessions/from_flow/create | POST /v3/flows/sessions/from_flow/create | create_flow_session → create_flow_session_v3 | createFlowSession → createFlowSessionV3 |
| Start chatbotsession (anonym) | POST /v2/flows/sessions/create | POST /v3/flows/sessions/create | create_chatbot_session → create_chatbot_session_v3 | createChatbotSession → createChatbotSessionV3 |
| Send en besked | POST /v2/flows/sessions/{id}/invoke | POST /v3/flows/sessions/invoke | invoke_flow_response → invoke_flow_response_v3 | invokeFlowResponse → invokeFlowResponseV3 |
| Poll efter events | 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 |
| Annullér en kørsel | POST /v2/flows/sessions/{id}/cancel | POST /v3/flows/sessions/cancel | cancel_flow_session → cancel_flow_session_v3 | cancelFlowSession → cancelFlowSessionV3 |
| Gå tilbage til forrige anker | POST /v2/flows/sessions/{id}/back | POST /v3/flows/sessions/back | go_back → go_back_v3 | goBack → goBackV3 |
| Udløs en chat-hook | POST /v2/flows/sessions/{id}/hook | POST /v3/flows/sessions/hook | fire_chat_hook → fire_chat_hook_v3 | fireChatHook → fireChatHookV3 |
| Genoptag en ventende hook | POST /v2/flows/sessions/{id}/resume-hook | POST /v3/flows/sessions/resume-hook | resume_hook → resume_hook_v3 | resumeHook → resumeHookV3 |
| Angiv flowvariabler | PATCH /v2/flows/sessions/{id}/variables | PATCH /v3/flows/sessions/variables | update_session_variables → update_session_variables_v3 | updateSessionVariables → updateSessionVariablesV3 |
| Vis vedhæftede filer | GET /v2/flows/sessions/{id}/attachments | GET /v3/flows/sessions/attachments | get_attachments → get_attachments_v3 | getAttachments → getAttachmentsV3 |
| Upload vedhæftet fil | POST /v2/flows/sessions/{id}/attachments | POST /v3/flows/sessions/attachments | upload_attachments → upload_attachments_v3 | uploadAttachments → uploadAttachmentsV3 |
| Slet vedhæftet fil | DELETE /v2/flows/sessions/{id}/attachments/{file_id} | DELETE /v3/flows/sessions/attachments/{file_id} | delete_attachment → delete_attachment_v3 | deleteAttachment → deleteAttachmentV3 |
| Feedback på besked | POST /v2/flows/sessions/{id}/feedback | POST /v3/flows/sessions/feedback | create_message_feedback → create_message_feedback_v3 | createMessageFeedback → createMessageFeedbackV3 |
| Læs en artefakt | GET /v2/flows/sessions/{id}/artefacts/{artefact_id} | GET /v3/flows/sessions/artefacts/{artefact_id} | get_artefact_content → get_artefact_content_v3 | getArtefactContent → getArtefactContentV3 |
| Søg efter type (ny, ingen v2) | ingen | POST /v3/flows/sessions/search | invoke_search_v3 | invokeSearchV3 |
Download af en vedhæftet fil (GET /v2/flows/sessions/{id}/attachments/{file_id}) har ingen v3-version. Det er et dashboard-kald for indloggede brugere og er ikke en del af denne migrering.
Kun de to create-kald kræver din API-nøgle. from_flow/create starter en session for et flow i dit workspace og kræver nøglen. create er den anonyme chatbotsession, som den indlejrede chat-widget bruger, så den tager ingen nøgle. Begge returnerer session_id og created_at med HTTP 201. Alle andre v3-sessionskald kræver kun headeren X-FH-Session-Id.
Upload vedhæftede filer over HTTP indtil videre
I 4.0.0 kan upload_attachments_v3 og uploadAttachmentsV3 ikke sende en fil. API’et returnerer 422 “Expected UploadFile”, og Python-metoden afviser bytes, før requesten sendes. 3.x-uploadmetoderne har samme problem. Indtil det er rettet, skal du sende filen som multipart/form-data til POST /v3/flows/sessions/attachments med headeren X-FH-Session-Id. HTTP-fanen nedenfor viser kaldet.
Før og efter#
Dette eksempel starter en session for et publiceret flow, sender “Hello” og udskriver flowets svar. Hver fane viser først 3.x-koden og derefter 4.0-koden, som vi kørte mod https://api.flowhunt.io. 4.0-koden læser API-nøglen, workspace-id’et og flow-id’et fra miljøvariablene FLOWHUNT_API_KEY, FLOWHUNT_WORKSPACE_ID og 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 # hold den hemmelig, log den aldrig
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("Flow-kørslen mislykkedes")
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(); // hold den hemmelig, log den aldrig
$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);
// Bemærk rækkefølgen: tidsstempel først, session-id derefter.
$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('Flow-kørslen mislykkedes');
}
if ($event->getEventType() === 'ai' && $event->getActionType() === 'message') {
echo $event->getMetadata()->getMessage(), PHP_EOL;
$answered = true;
}
}
if ($answered && !$newEvents) {
break;
}
}HTTP
Kun create-kaldet sender API-nøglen. Alle kald efter det sender session-id’et i headeren 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"Tidligere var session-id’et en del af hver sti, for eksempel /v2/flows/sessions/$SESSION_ID/invoke. Et v3-kald uden headeren returnerer 401.
Sådan fungerer polling#
from_timestamper millisekunder siden epoch. Pollingen returnerer de events, hviscreated_at_timestamper strengt større.- Start fra
created_ati invoke-response, som er en millisekundværdi sendt som en streng, så konvertér den til et heltal. Brug0for at få hele sessionen. Brug ikkecreated_atfra create-response, som er en dato og et klokkeslæt, ikke millisekunder. - Efter hver polling flyttes
from_timestamptil det nyeste eventscreated_at_timestampminus 1, og du springer events over, hvisevent_iddu allerede har set. Events, der oprettes i samme millisekund, kan ankomme i forskellige pollinger. FlowHunts chat-widget poller på samme måde. - Hvert event har en
event_type(ai,humanellersystem), enaction_type(message,loading,tool_call,failed,hook_waiting_for_inputog andre) ogmetadata. Svarets tekst findes imetadata.messagepåai-events af typenmessage.
FlowHunt sender ikke et separat “run finished”-event. Da vi kørte eksemplerne mod et flow med ét trin, returnerede pollingen et system loading-event, derefter ét ai message med svaret og intet derefter. Derfor stopper eksemplerne ved den første polling, der ikke bringer nye events, efter at et svar er ankommet, og kaster en fejl ved failed. Hvis dit flow sender flere beskeder eller venter på input med hook_waiting_for_input, må du selv beslutte stopbetingelsen.
Argumentrækkefølgen er ændret for tre metoder#
Omarrangér disse tre kald
v3-metoderne placerer path-parametre før session-id-headeren. I PHP, og i Python når du sender argumenter positionelt, fejler disse tre kald med en typefejl eller sender lydløst de forkerte værdier, medmindre du omarrangerer dem.
| 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) |
I Python bør du bruge keyword-argumenter overalt, for eksempel x_fh_session_id=session_id, og så betyder rækkefølgen ikke længere noget. Python 4.0 kontrollerer også argumenttyper, så from_timestamp skal være en int. Sendes strengen "0", udløses en pydantic-ValidationError.
Andre brydende ændringer i 4.0.0#
Disse metoder fandtes i 3.19.1 og er væk i 4.0.0, fordi de bagvedliggende API-endpoints er fjernet eller ændret. PHP-metodernes navne er camelCase-formen af Python-navnene, for eksempel bliver get_available_models til getAvailableModels.
| Fjernet metode | Endpoint | Hvad du skal gøre |
|---|---|---|
AgentGridsApi.get_agent_grid_preview | GET /v2/agent_grids/{agent_grid_id}/preview | Fjern kaldet. |
CustomModelsApi.get_available_models | GET /v2/custom-models/available | Fjern kaldet. |
FineTuningsApi.create_image_ft, delete_image_ft, search_image_fts, update_image_ft | /v2/photo_ai/images/... | Fjern kaldene. |
WorkspacesApi.update_workspace_auto_recharge | PUT /v2/workspaces/{workspace_id}/auto-recharge | Fjern kaldet. |
FlowBatchApi.export_csv | GET /v2/flows/{flow_id}/batch/{batch_run_id}/export-csv | Kald start_export_csv (POST, samme sti), derefter get_export_csv_status (GET .../export-csv/{task_id}). |
Metoderne til Zendesk-kanalen, Shopify-fakturering, Replicate og SERP-pingback-webhooks er også fjernet. Det er indgående webhooks til FlowHunts egne servere, ikke kald din kode laver.
Hold session-id’et hemmeligt#
Session-id'et er en legitimationsoplysning
Alle, der har et session-id, kan læse og fortsætte den pågældende samtale. Log det ikke, læg det ikke i URL’er eller query strings, og send det ikke til analyseværktøjer. Behandl det som en kortlivet adgangskode.
Hvad med v2?#
v2-sessionruterne er forældede fra og med SDK 4.0.0 og udgår den 30. november 2026. Indtil da virker de stadig, og de er markeret som forældede i API-referencen. SDK 4.0.0 indeholder stadig v2-metoderne. I Python udløser et kald en DeprecationWarning. I PHP er de markeret med @deprecated i koden, hvilket din IDE eller statisk analyse vil markere.