Migrácie SDK
Migrácia na SDK 4.0 a session API v3
Presuňte kód v Pythone a PHP z volaní flow-session vo v2 na v3, ktoré posiela ID session v hlavičke.
Session API v2 končí 30. novembra 2026
SDK 4.0.0 označuje volania flow-session vo v2 ako zastarané, napríklad create_flow_session, invoke_flow_response a poll_flow_response. Trasy session vo v2 končia 30. novembra 2026. Do tej doby presuňte svoj kód na volania v3 uvedené na tejto stránke.
Verzia 4.0.0 SDK FlowHunt pre Python a PHP prináša session API v3. Prechod naň udrží ID vašich chatových session mimo URL a väčšina práce spočíva v premenovaní metód. Táto stránka ukazuje, čo sa zmenilo, ktoré volania treba premenovať a kód pred zmenou a po nej.
Čo sa zmenilo#
Volania session vo v3 prijímajú ID session v hlavičke X-FH-Session-Id, nikdy v URL. Tela požiadaviek a odpovedí sú rovnaké ako vo v2. Trasy session vo v2 sú zastarané a končia 30. novembra 2026.
Vo v2 každé chatové volanie vkladá ID session do cesty, napríklad /v2/flows/sessions/{session_id}/invoke. ID session je jediný prihlasovací údaj, ktorý anonymná chatová session má, a URL sa nakoniec ocitnú v prístupových logoch, proxy logoch, histórii prehliadača a hlavičkách Referer. Hlavička nie.
Inštalácia 4.0.0#
Python
Balíček na PyPI je flowhunt.
pip install --upgrade "flowhunt>=4,<5"PHP
Balíček na Packagiste je flowhunt/flowhunt-php-sdk. Vyžaduje PHP 8.1 alebo novšie.
composer require flowhunt/flowhunt-php-sdk:^4.0Migrácia v štyroch krokoch#
Aktualizujte balíček
Nainštalujte 4.0.0 podľa vyššie uvedeného postupu. Vaše existujúce volania vo v2 fungujú aj po aktualizácii, takže môžete presúvať volania jedno po druhom. Dokončite to do 30. novembra 2026.
Premenujte každé volanie session
Pridajte
_v3k názvu metódy v Pythone aleboV3k názvu v PHP. Mapovanie metód uvádza všetky páry.Odovzdajte ID session ako argument hlavičky
Argument pre ID session je teraz
x_fh_session_id. V Pythone ho odovzdajte ako kľúčový argument. V PHP ho tri metódy prijímajú ako druhý namiesto prvého. Pozrite Zmenené poradie argumentov pri troch metódach.Skontrolujte odstránené metódy
Ak voláte niektorú z metód odstránených v 4.0.0, prejdite na náhradu alebo volanie odstráňte.
Mapovanie metód#
Metódy v Pythone sú na flowhunt.FlowsApi a tie isté metódy v3 existujú aj na flowhunt.V3Api. Metódy v PHP sú na FlowHunt\Api\FlowsApi.
| Čo | v2 HTTP | v3 HTTP (ID session v X-FH-Session-Id) | Python 3.x → 4.0 | PHP 3.x → 4.0 |
|---|---|---|---|---|
| Spustenie session flow (API kľúč) | POST /v2/flows/sessions/from_flow/create | POST /v3/flows/sessions/from_flow/create | create_flow_session → create_flow_session_v3 | createFlowSession → createFlowSessionV3 |
| Spustenie session chatbota (anonymné) | POST /v2/flows/sessions/create | POST /v3/flows/sessions/create | create_chatbot_session → create_chatbot_session_v3 | createChatbotSession → createChatbotSessionV3 |
| Odoslanie správy | POST /v2/flows/sessions/{id}/invoke | POST /v3/flows/sessions/invoke | invoke_flow_response → invoke_flow_response_v3 | invokeFlowResponse → invokeFlowResponseV3 |
| Zisťovanie udalostí | 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 |
| Zrušenie behu | POST /v2/flows/sessions/{id}/cancel | POST /v3/flows/sessions/cancel | cancel_flow_session → cancel_flow_session_v3 | cancelFlowSession → cancelFlowSessionV3 |
| Návrat na predchádzajúci anchor | POST /v2/flows/sessions/{id}/back | POST /v3/flows/sessions/back | go_back → go_back_v3 | goBack → goBackV3 |
| Spustenie chat hooku | POST /v2/flows/sessions/{id}/hook | POST /v3/flows/sessions/hook | fire_chat_hook → fire_chat_hook_v3 | fireChatHook → fireChatHookV3 |
| Obnovenie čakajúceho hooku | POST /v2/flows/sessions/{id}/resume-hook | POST /v3/flows/sessions/resume-hook | resume_hook → resume_hook_v3 | resumeHook → resumeHookV3 |
| Nastavenie premenných flow | PATCH /v2/flows/sessions/{id}/variables | PATCH /v3/flows/sessions/variables | update_session_variables → update_session_variables_v3 | updateSessionVariables → updateSessionVariablesV3 |
| Zoznam príloh | GET /v2/flows/sessions/{id}/attachments | GET /v3/flows/sessions/attachments | get_attachments → get_attachments_v3 | getAttachments → getAttachmentsV3 |
| Nahranie prílohy | POST /v2/flows/sessions/{id}/attachments | POST /v3/flows/sessions/attachments | upload_attachments → upload_attachments_v3 | uploadAttachments → uploadAttachmentsV3 |
| Odstránenie prílohy | DELETE /v2/flows/sessions/{id}/attachments/{file_id} | DELETE /v3/flows/sessions/attachments/{file_id} | delete_attachment → delete_attachment_v3 | deleteAttachment → deleteAttachmentV3 |
| Spätná väzba na správu | POST /v2/flows/sessions/{id}/feedback | POST /v3/flows/sessions/feedback | create_message_feedback → create_message_feedback_v3 | createMessageFeedback → createMessageFeedbackV3 |
| Čítanie artefaktu | GET /v2/flows/sessions/{id}/artefacts/{artefact_id} | GET /v3/flows/sessions/artefacts/{artefact_id} | get_artefact_content → get_artefact_content_v3 | getArtefactContent → getArtefactContentV3 |
| Vyhľadávanie počas písania (nové, bez v2) | žiadne | POST /v3/flows/sessions/search | invoke_search_v3 | invokeSearchV3 |
Sťahovanie prílohy (GET /v2/flows/sessions/{id}/attachments/{file_id}) nemá verziu vo v3. Je to volanie z prihláseného dashboardu a nie je súčasťou tejto migrácie.
API kľúč potrebujú len dve volania na vytvorenie session. from_flow/create spúšťa session pre flow vo vašom pracovnom priestore a kľúč vyžaduje. create je anonymná session chatbota, ktorú používa vložený chat widget, takže kľúč neprijíma. Obe vracajú session_id a created_at s HTTP 201. Každé ďalšie volanie session vo v3 potrebuje iba hlavičku X-FH-Session-Id.
Prílohy zatiaľ nahrávajte cez HTTP
Vo verzii 4.0.0 nemôžu upload_attachments_v3 a uploadAttachmentsV3 poslať súbor. API vracia 422 „Expected UploadFile“ a metóda v Pythone odmietne bajty ešte pred odoslaním požiadavky. Metódy na nahrávanie z 3.x majú ten istý problém. Kým to nebude opravené, posielajte súbor ako multipart/form-data na POST /v3/flows/sessions/attachments s hlavičkou X-FH-Session-Id. Karta HTTP nižšie ukazuje toto volanie.
Pred a po#
Tento príklad spustí session pre publikovaný flow, pošle „Hello“ a vypíše odpoveď flow. Každá karta najprv ukazuje kód z 3.x a potom kód zo 4.0, ktorý sme spustili proti https://api.flowhunt.io. Kód zo 4.0 načíta API kľúč, ID pracovného priestoru a ID flow z premenných prostredia FLOWHUNT_API_KEY, FLOWHUNT_WORKSPACE_ID a 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 # uchovajte v tajnosti, nikdy ho nelogujte
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(); // uchovajte v tajnosti, nikdy ho nelogujte
$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);
// Všimnite si poradie: najprv časová značka, potom ID session.
$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
API kľúč posiela len volanie na vytvorenie. Každé nasledujúce volanie posiela ID session v hlavičke 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"Predtým bol ID session súčasťou každej cesty, napríklad /v2/flows/sessions/$SESSION_ID/invoke. Volanie vo v3 bez hlavičky vráti 401.
Ako funguje zisťovanie udalostí#
from_timestampje počet milisekúnd od epochy. Zisťovanie vráti udalosti, ktorýchcreated_at_timestampje striktne väčší.- Začnite od
created_atz odpovede na invoke, čo je milisekundová hodnota poslaná ako reťazec, takže ju preveďte na celé číslo. Použite0, ak chcete celú session. Nepoužívajtecreated_atz odpovede na vytvorenie, ktoré je dátumom a časom, nie milisekundami. - Po každom zisťovaní posuňte
from_timestampnacreated_at_timestampnajnovšej udalosti mínus 1 a preskočte udalosti, ktorýchevent_idste už videli. Udalosti vytvorené v tej istej milisekunde môžu prísť v rôznych zisťovaniach. Chat widget FlowHunt zisťuje udalosti rovnako. - Každá udalosť má
event_type(ai,humanalebosystem),action_type(message,loading,tool_call,failed,hook_waiting_for_inputa ďalšie) ametadata. Text odpovede je vmetadata.messageudalostímessagetypuai.
FlowHunt neposiela samostatnú udalosť „beh dokončený“. Keď sme vzorky spustili proti jednostupňovému flow, zisťovanie vrátilo udalosť loading typu system, potom jeden message typu ai s odpoveďou a nič ďalšie. Preto sa vzorky zastavia pri prvom zisťovaní, ktoré po doručení odpovede neprinesie nové udalosti, a vyhodia výnimku pri failed. Ak váš flow posiela viac správ alebo čaká na vstup s hook_waiting_for_input, určite si vlastnú podmienku zastavenia.
Zmenené poradie argumentov pri troch metódach#
Preusporiadajte tieto tri volania
Metódy vo v3 zoraďujú parametre cesty pred hlavičkou s ID session. V PHP a v Pythone, keď argumenty odovzdávate pozične, tieto tri volania zlyhajú s chybou typu alebo potichu pošlú nesprávne hodnoty, ak ich nepreusporiadate.
| 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) |
V Pythone odovzdávajte všade kľúčové argumenty, napríklad x_fh_session_id=session_id, a poradie prestane byť dôležité. Python 4.0 tiež kontroluje typy argumentov, takže from_timestamp musí byť int. Odovzdanie reťazca "0" vyvolá chybu ValidationError z pydantic.
Ďalšie prelomové zmeny v 4.0.0#
Tieto metódy boli vo verzii 3.19.1 a vo verzii 4.0.0 už neexistujú, pretože API endpointy za nimi boli odstránené alebo zmenené. Názvy metód v PHP sú camelCase formou tých pythonských, napríklad get_available_models sa mení na getAvailableModels.
| Odstránená metóda | Endpoint | Čo urobiť |
|---|---|---|
AgentGridsApi.get_agent_grid_preview | GET /v2/agent_grids/{agent_grid_id}/preview | Volanie odstráňte. |
CustomModelsApi.get_available_models | GET /v2/custom-models/available | Volanie odstráňte. |
FineTuningsApi.create_image_ft, delete_image_ft, search_image_fts, update_image_ft | /v2/photo_ai/images/... | Volania odstráňte. |
WorkspacesApi.update_workspace_auto_recharge | PUT /v2/workspaces/{workspace_id}/auto-recharge | Volanie odstráňte. |
FlowBatchApi.export_csv | GET /v2/flows/{flow_id}/batch/{batch_run_id}/export-csv | Zavolajte start_export_csv (POST, rovnaká cesta), potom get_export_csv_status (GET .../export-csv/{task_id}). |
Odstránené boli aj metódy pre kanál Zendesk, fakturáciu Shopify, Replicate a SERP pingback webhooky. Sú to prichádzajúce webhooky pre vlastné servery FlowHunt, nie volania, ktoré robí váš kód.
Uchovajte ID session v tajnosti#
ID session je prihlasovací údaj
Ktokoľvek, kto má ID session, môže túto konverzáciu čítať a pokračovať v nej. Nelogujte ho, nedávajte ho do URL ani do query reťazcov a neposielajte ho do analytiky. Správajte sa k nemu ako ku krátkodobému heslu.
A čo v2?#
Trasy session vo v2 sú od SDK 4.0.0 zastarané a končia 30. novembra 2026. Dovtedy fungujú ďalej a v referencii API sú označené ako zastarané. SDK 4.0.0 stále obsahuje metódy vo v2. V Pythone ich volanie vyvolá DeprecationWarning. V PHP sú v kóde označené @deprecated, čo vám označí IDE alebo statická analýza.