Migrace SDK
Migrace na SDK 4.0 a v3 session API
Přesuňte kód v Pythonu a PHP z volání flow-session ve verzi v2 na v3, která posílá ID relace v hlavičce.
API relací v2 končí 30. listopadu 2026
SDK 4.0.0 označuje volání flow-session ve verzi v2 jako zastaralá, například create_flow_session, invoke_flow_response a poll_flow_response. Routy relací v2 dosáhnou konce životnosti 30. listopadu 2026. Do té doby přesuňte svůj kód na volání v3 popsaná na této stránce.
Verze 4.0.0 SDK pro Python a PHP od FlowHunt přidává v3 API pro flow-session. Přechod na něj udrží ID chatových relací mimo URL a většina práce spočívá v přejmenování metod. Tato stránka ukazuje, co se změnilo, která volání přejmenovat a kód před změnou i po ní.
Co se změnilo#
Volání relací ve verzi v3 předávají ID relace v hlavičce X-FH-Session-Id, nikdy v URL. Těla požadavků a odpovědí jsou stejná jako ve verzi v2. Routy relací v2 jsou zastaralé a dosáhnou konce životnosti 30. listopadu 2026.
Ve verzi v2 obsahuje každé chatové volání ID relace v cestě, například /v2/flows/sessions/{session_id}/invoke. ID relace je jediný přihlašovací údaj, který anonymní chatová relace má, a URL končí v přístupových protokolech, protokolech proxy, historii prohlížeče a hlavičkách Referer. Hlavička ne.
Instalace 4.0.0#
Python
Balíček na PyPI je flowhunt.
pip install --upgrade "flowhunt>=4,<5"PHP
Balíček na Packagistu je flowhunt/flowhunt-php-sdk. Vyžaduje PHP 8.1 nebo novější.
composer require flowhunt/flowhunt-php-sdk:^4.0Migrace ve čtyřech krocích#
Aktualizujte balíček
Nainstalujte 4.0.0 podle výše uvedeného postupu. Vaše stávající volání v2 fungují i po aktualizaci, takže můžete přesouvat volání jedno po druhém. Dokončete to do 30. listopadu 2026.
Přejmenujte každé volání relace
Přidejte
_v3k názvu metody v Pythonu neboV3k názvu metody v PHP. Mapování metod uvádí všechny dvojice.Předávejte ID relace jako argument hlavičky
Argument ID relace se nyní jmenuje
x_fh_session_id. V Pythonu jej předávejte jako klíčový argument. V PHP jej tři metody přijímají jako druhý místo prvního. Viz Změna pořadí argumentů u tří metod.Zkontrolujte odstraněné metody
Pokud voláte některou z metod odstraněných ve verzi 4.0.0, přejděte na náhradu nebo volání odstraňte.
Mapování metod#
Metody v Pythonu jsou na flowhunt.FlowsApi a stejné metody v3 existují také na flowhunt.V3Api. Metody v PHP jsou na FlowHunt\Api\FlowsApi.
| Co | v2 HTTP | v3 HTTP (ID relace v X-FH-Session-Id) | Python 3.x → 4.0 | PHP 3.x → 4.0 |
|---|---|---|---|---|
| Zahájení relace flow (API klíč) | POST /v2/flows/sessions/from_flow/create | POST /v3/flows/sessions/from_flow/create | create_flow_session → create_flow_session_v3 | createFlowSession → createFlowSessionV3 |
| Zahájení relace chatbota (anonymní) | POST /v2/flows/sessions/create | POST /v3/flows/sessions/create | create_chatbot_session → create_chatbot_session_v3 | createChatbotSession → createChatbotSessionV3 |
| Odeslání zprávy | POST /v2/flows/sessions/{id}/invoke | POST /v3/flows/sessions/invoke | invoke_flow_response → invoke_flow_response_v3 | invokeFlowResponse → invokeFlowResponseV3 |
| Dotazování na události | 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šení běhu | POST /v2/flows/sessions/{id}/cancel | POST /v3/flows/sessions/cancel | cancel_flow_session → cancel_flow_session_v3 | cancelFlowSession → cancelFlowSessionV3 |
| Návrat na předchozí ukotvení | POST /v2/flows/sessions/{id}/back | POST /v3/flows/sessions/back | go_back → go_back_v3 | goBack → goBackV3 |
| Spuštění chat hooku | POST /v2/flows/sessions/{id}/hook | POST /v3/flows/sessions/hook | fire_chat_hook → fire_chat_hook_v3 | fireChatHook → fireChatHookV3 |
| Obnovení čekajícího hooku | POST /v2/flows/sessions/{id}/resume-hook | POST /v3/flows/sessions/resume-hook | resume_hook → resume_hook_v3 | resumeHook → resumeHookV3 |
| Nastavení proměnných flow | PATCH /v2/flows/sessions/{id}/variables | PATCH /v3/flows/sessions/variables | update_session_variables → update_session_variables_v3 | updateSessionVariables → updateSessionVariablesV3 |
| Výpis příloh | GET /v2/flows/sessions/{id}/attachments | GET /v3/flows/sessions/attachments | get_attachments → get_attachments_v3 | getAttachments → getAttachmentsV3 |
| Nahrání přílohy | POST /v2/flows/sessions/{id}/attachments | POST /v3/flows/sessions/attachments | upload_attachments → upload_attachments_v3 | uploadAttachments → uploadAttachmentsV3 |
| Smazání přílohy | DELETE /v2/flows/sessions/{id}/attachments/{file_id} | DELETE /v3/flows/sessions/attachments/{file_id} | delete_attachment → delete_attachment_v3 | deleteAttachment → deleteAttachmentV3 |
| Zpětná vazba ke zprávě | POST /v2/flows/sessions/{id}/feedback | POST /v3/flows/sessions/feedback | create_message_feedback → create_message_feedback_v3 | createMessageFeedback → createMessageFeedbackV3 |
| Čtení 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 |
| Vyhledávání při psaní (novinka, bez v2) | žádné | POST /v3/flows/sessions/search | invoke_search_v3 | invokeSearchV3 |
Stažení přílohy (GET /v2/flows/sessions/{id}/attachments/{file_id}) nemá verzi v3. Jde o volání z přihlášeného dashboardu a není součástí této migrace.
API klíč potřebují pouze dvě volání pro vytvoření. from_flow/create zahájí relaci pro flow ve vašem pracovním prostoru a klíč vyžaduje. create je anonymní relace chatbota, kterou používá vložený chatovací widget, takže klíč nebere. Obě vrací session_id a created_at s HTTP 201. Všechna ostatní volání relací v3 potřebují pouze hlavičku X-FH-Session-Id.
Přílohy zatím nahrávejte přes HTTP
Ve verzi 4.0.0 nemohou upload_attachments_v3 ani uploadAttachmentsV3 odeslat soubor. API vrací 422 “Expected UploadFile” a metoda v Pythonu odmítne bajty ještě před odesláním požadavku. Metody pro nahrávání ve verzi 3.x mají stejný problém. Dokud to nebude opraveno, posílejte soubor jako multipart/form-data na POST /v3/flows/sessions/attachments s hlavičkou X-FH-Session-Id. Volání ukazuje níže uvedená karta HTTP.
Před a po#
Tento příklad zahájí relaci publikovaného flow, odešle “Hello” a vypíše odpověď flow. Každá karta nejprve ukazuje kód pro 3.x a poté kód pro 4.0, který jsme spustili proti https://api.flowhunt.io. Kód pro 4.0 čte API klíč, ID pracovního prostoru a ID flow z proměnných prostředí 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 # uchovejte v tajnosti, nikdy jej 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(); // uchovejte v tajnosti, nikdy jej 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);
// Pozor na pořadí: nejprve časové razítko, potom ID relace.
$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 klíč posílá pouze volání pro vytvoření. Každé následující volání posílá ID relace v hlavičce 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"Dříve bylo ID relace součástí každé cesty, například /v2/flows/sessions/$SESSION_ID/invoke. Volání v3 bez hlavičky vrací 401.
Jak funguje polling#
from_timestampje počet milisekund od epochy. Dotaz vrací události, jejichžcreated_at_timestampje striktně větší.- Začněte hodnotou
created_atz odpovědi na invoke, což je milisekundová hodnota odeslaná jako řetězec, takže ji převeďte na celé číslo. Pro celou relaci použijte0. Nepoužívejtecreated_atz odpovědi na vytvoření, což je datum a čas, ne milisekundy. - Po každém dotazu posuňte
from_timestampnacreated_at_timestampnejnovější události minus 1 a přeskakujte události, jejichževent_idjste již viděli. Události vytvořené ve stejné milisekundě mohou dorazit v různých dotazech. Chatovací widget FlowHunt dotazuje stejným způsobem. - Každá událost má
event_type(ai,humannebosystem),action_type(message,loading,tool_call,failed,hook_waiting_for_inputa další) ametadata. Text odpovědi je vmetadata.messageudálostíais typemmessage.
FlowHunt neposílá samostatnou událost “běh dokončen”. Když jsme ukázky spustili proti jednostupňovému flow, dotaz vrátil událost system typu loading, potom jednu událost ai typu message s odpovědí a pak už nic. Proto se ukázky zastaví u prvního dotazu, který po příchodu odpovědi nepřinese žádné nové události, a vyhodí výjimku při failed. Pokud vaše flow posílá několik zpráv nebo čeká na vstup s hook_waiting_for_input, zvolte si vlastní podmínku ukončení.
Změna pořadí argumentů u tří metod#
Přeuspořádejte tato tři volání
Metody v3 řadí parametry cesty před hlavičku s ID relace. V PHP a v Pythonu, když argumenty předáváte pozičně, tato tři volání selžou s chybou typu nebo tiše odešlou špatné hodnoty, pokud je nepřeuspořádáte.
| 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 Pythonu předávejte všude klíčové argumenty, například x_fh_session_id=session_id, a pořadí pak nehraje roli. Python 4.0 navíc kontroluje typy argumentů, takže from_timestamp musí být int. Předání řetězce "0" vyvolá pydantic ValidationError.
Další zásadní změny ve verzi 4.0.0#
Tyto metody byly ve verzi 3.19.1 a ve verzi 4.0.0 už nejsou, protože koncové body API za nimi byly odstraněny nebo změněny. Názvy metod v PHP odpovídají formě camelCase těch pythoních, například z get_available_models je getAvailableModels.
| Odstraněná metoda | Koncový bod | Co dělat |
|---|---|---|
AgentGridsApi.get_agent_grid_preview | GET /v2/agent_grids/{agent_grid_id}/preview | Volání odstraňte. |
CustomModelsApi.get_available_models | GET /v2/custom-models/available | Volání odstraňte. |
FineTuningsApi.create_image_ft, delete_image_ft, search_image_fts, update_image_ft | /v2/photo_ai/images/... | Volání odstraňte. |
WorkspacesApi.update_workspace_auto_recharge | PUT /v2/workspaces/{workspace_id}/auto-recharge | Volání odstraňte. |
FlowBatchApi.export_csv | GET /v2/flows/{flow_id}/batch/{batch_run_id}/export-csv | Zavolejte start_export_csv (POST, stejná cesta) a potom get_export_csv_status (GET .../export-csv/{task_id}). |
Odstraněny byly také metody pro kanál Zendesk, Shopify billing, Replicate a SERP pingback webhooky. Jde o příchozí webhooky pro vlastní servery FlowHunt, ne o volání, která dělá váš kód.
Uchovejte ID relace v tajnosti#
ID relace je přihlašovací údaj
Kdokoli, kdo má ID relace, může tu konverzaci číst a pokračovat v ní. Nelogujte ho, nedávejte ho do URL ani do parametrů dotazu a neposílejte ho do analytiky. Chovejte se k němu jako ke krátkodobému heslu.
A co v2?#
Routy relací v2 jsou od SDK 4.0.0 zastaralé a dosáhnou konce životnosti 30. listopadu 2026. Do té doby fungují a v referenci API jsou označené jako zastaralé. SDK 4.0.0 stále obsahuje metody v2. V Pythonu jejich volání vyvolá DeprecationWarning. V PHP jsou v kódu označené jako @deprecated, což váš IDE nebo statická analýza označí.