Migrări SDK
Migrarea la SDK 4.0 și API-ul de sesiuni v3
Mută codul Python și PHP de la apelurile de sesiune de flow v2 la v3, care trimite id-ul sesiunii într-un header.
API-ul de sesiuni v2 ajunge la sfârșitul ciclului de viață pe 30 noiembrie 2026
SDK 4.0.0 depreciază apelurile de sesiune de flow v2, cum ar fi create_flow_session, invoke_flow_response și poll_flow_response. Rutele de sesiune v2 ajung la sfârșitul ciclului de viață pe 30 noiembrie 2026. Mută-ți codul la apelurile v3 din această pagină înainte de acel moment.
Versiunea 4.0.0 a SDK-urilor FlowHunt pentru Python și PHP adaugă API-ul de sesiuni de flow v3. Trecerea la el ține id-urile sesiunilor de chat în afara URL-urilor, iar cea mai mare parte a muncii constă în redenumirea metodelor. Această pagină arată ce s-a schimbat, ce apeluri trebuie redenumite și codul înainte și după.
Ce s-a schimbat#
Apelurile de sesiune v3 trimit id-ul sesiunii în headerul X-FH-Session-Id, niciodată în URL. Corpurile cererilor și răspunsurilor sunt aceleași ca în v2. Rutele de sesiune v2 sunt depreciate și ajung la sfârșitul ciclului de viață pe 30 noiembrie 2026.
În v2, fiecare apel de chat pune id-ul sesiunii în cale, de exemplu /v2/flows/sessions/{session_id}/invoke. Id-ul sesiunii este singura credențială pe care o are o sesiune de chat anonimă, iar URL-urile ajung în logurile de acces, logurile de proxy, istoricul browserului și header-ele Referer. Un header nu ajunge.
Instalare 4.0.0#
Python
Pachetul de pe PyPI este flowhunt.
pip install --upgrade "flowhunt>=4,<5"PHP
Pachetul de pe Packagist este flowhunt/flowhunt-php-sdk. Necesită PHP 8.1 sau mai nou.
composer require flowhunt/flowhunt-php-sdk:^4.0Migrare în patru pași#
Actualizează pachetul
Instalează 4.0.0 așa cum se arată mai sus. Apelurile v2 existente continuă să funcționeze după actualizare, așa că poți migra câte un apel pe rând. Termină înainte de 30 noiembrie 2026.
Redenumește fiecare apel de sesiune
Adaugă
_v3la numele metodei Python sauV3la cel PHP. Corespondența metodelor listează fiecare pereche.Trimite id-ul sesiunii ca argument de header
Argumentul pentru id-ul sesiunii este acum
x_fh_session_id. În Python, trimite-l ca argument numit. În PHP, trei metode îl primesc pe poziția a doua în loc de prima. Vezi ordinea argumentelor s-a schimbat pentru trei metode.Verifică metodele eliminate
Dacă apelezi vreuna dintre metodele eliminate în 4.0.0, treci la înlocuitor sau elimină apelul.
Corespondența metodelor#
Metodele Python sunt în flowhunt.FlowsApi, iar aceleași metode v3 există și în flowhunt.V3Api. Metodele PHP sunt în FlowHunt\Api\FlowsApi.
| Ce | HTTP v2 | HTTP v3 (id-ul sesiunii în X-FH-Session-Id) | Python 3.x → 4.0 | PHP 3.x → 4.0 |
|---|---|---|---|---|
| Pornește o sesiune de flow (cheie API) | POST /v2/flows/sessions/from_flow/create | POST /v3/flows/sessions/from_flow/create | create_flow_session → create_flow_session_v3 | createFlowSession → createFlowSessionV3 |
| Pornește o sesiune de chatbot (anonimă) | POST /v2/flows/sessions/create | POST /v3/flows/sessions/create | create_chatbot_session → create_chatbot_session_v3 | createChatbotSession → createChatbotSessionV3 |
| Trimite un mesaj | POST /v2/flows/sessions/{id}/invoke | POST /v3/flows/sessions/invoke | invoke_flow_response → invoke_flow_response_v3 | invokeFlowResponse → invokeFlowResponseV3 |
| Interoghează evenimentele | 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 |
| Anulează o rulare | POST /v2/flows/sessions/{id}/cancel | POST /v3/flows/sessions/cancel | cancel_flow_session → cancel_flow_session_v3 | cancelFlowSession → cancelFlowSessionV3 |
| Revino la ancora anterioară | POST /v2/flows/sessions/{id}/back | POST /v3/flows/sessions/back | go_back → go_back_v3 | goBack → goBackV3 |
| Declanșează un hook de chat | POST /v2/flows/sessions/{id}/hook | POST /v3/flows/sessions/hook | fire_chat_hook → fire_chat_hook_v3 | fireChatHook → fireChatHookV3 |
| Reia un hook în așteptare | POST /v2/flows/sessions/{id}/resume-hook | POST /v3/flows/sessions/resume-hook | resume_hook → resume_hook_v3 | resumeHook → resumeHookV3 |
| Setează variabilele de flow | PATCH /v2/flows/sessions/{id}/variables | PATCH /v3/flows/sessions/variables | update_session_variables → update_session_variables_v3 | updateSessionVariables → updateSessionVariablesV3 |
| Listează atașamentele | GET /v2/flows/sessions/{id}/attachments | GET /v3/flows/sessions/attachments | get_attachments → get_attachments_v3 | getAttachments → getAttachmentsV3 |
| Încarcă un atașament | POST /v2/flows/sessions/{id}/attachments | POST /v3/flows/sessions/attachments | upload_attachments → upload_attachments_v3 | uploadAttachments → uploadAttachmentsV3 |
| Șterge un atașament | DELETE /v2/flows/sessions/{id}/attachments/{file_id} | DELETE /v3/flows/sessions/attachments/{file_id} | delete_attachment → delete_attachment_v3 | deleteAttachment → deleteAttachmentV3 |
| Feedback pe mesaj | POST /v2/flows/sessions/{id}/feedback | POST /v3/flows/sessions/feedback | create_message_feedback → create_message_feedback_v3 | createMessageFeedback → createMessageFeedbackV3 |
| Citește un artefact | GET /v2/flows/sessions/{id}/artefacts/{artefact_id} | GET /v3/flows/sessions/artefacts/{artefact_id} | get_artefact_content → get_artefact_content_v3 | getArtefactContent → getArtefactContentV3 |
| Căutare la tastare (nou, fără v2) | niciunul | POST /v3/flows/sessions/search | invoke_search_v3 | invokeSearchV3 |
Descărcarea unui atașament (GET /v2/flows/sessions/{id}/attachments/{file_id}) nu are versiune v3. Este un apel de dashboard autentificat și nu face parte din această migrare.
Doar cele două apeluri de creare au nevoie de cheia ta API. from_flow/create pornește o sesiune pentru un flow din workspace-ul tău și necesită cheia. create este sesiunea de chatbot anonimă folosită de widgetul de chat încorporat, așa că nu cere nicio cheie. Ambele returnează session_id și created_at cu HTTP 201. Orice alt apel de sesiune v3 are nevoie doar de headerul X-FH-Session-Id.
Deocamdată încarcă atașamentele prin HTTP
În 4.0.0, upload_attachments_v3 și uploadAttachmentsV3 nu pot trimite un fișier. API-ul returnează 422 „Expected UploadFile”, iar metoda Python respinge bytes înainte de a trimite cererea. Metodele de încărcare din 3.x au aceeași problemă. Până când se rezolvă, trimite fișierul ca multipart/form-data la POST /v3/flows/sessions/attachments cu headerul X-FH-Session-Id. Fila HTTP de mai jos arată apelul.
Înainte și după#
Acest exemplu pornește o sesiune pentru un flow publicat, trimite „Hello” și afișează răspunsul flow-ului. Fiecare filă arată mai întâi codul 3.x, apoi codul 4.0 pe care l-am rulat împotriva https://api.flowhunt.io. Codul 4.0 citește cheia API, id-ul workspace-ului și id-ul flow-ului din variabilele de mediu FLOWHUNT_API_KEY, FLOWHUNT_WORKSPACE_ID și 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 # keep secret, never log it
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);
// Note the order: timestamp first, session id second.
$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
Doar apelul de creare trimite cheia API. Fiecare apel de după el trimite id-ul sesiunii în headerul 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"Înainte, id-ul sesiunii făcea parte din fiecare cale, de exemplu /v2/flows/sessions/$SESSION_ID/invoke. Un apel v3 fără header returnează 401.
Cum funcționează interogarea periodică#
from_timestampeste exprimat în milisecunde de la epoch. Interogarea returnează evenimentele al cărorcreated_at_timestampeste strict mai mare.- Pornește de la
created_atal răspunsului de invocare, care este o valoare în milisecunde trimisă ca șir de caractere, așa că transformă-o în întreg. Folosește0pentru a obține întreaga sesiune. Nu folosicreated_atal răspunsului de creare, care este o dată și oră, nu milisecunde. - După fiecare interogare, mută
from_timestamplacreated_at_timestampal celui mai nou eveniment minus 1 și sari peste evenimentele al cărorevent_idl-ai văzut deja. Evenimentele create în aceeași milisecundă pot sosi în interogări diferite. Widgetul de chat FlowHunt interoghează la fel. - Fiecare eveniment are un
event_type(ai,humansausystem), unaction_type(message,loading,tool_call,failed,hook_waiting_for_inputși altele) șimetadata. Textul răspunsului se află înmetadata.messageal evenimenteloraide tipmessage.
FlowHunt nu trimite un eveniment separat de tip „rulare terminată”. Când am rulat exemplele împotriva unui flow cu un singur pas, interogarea a returnat un eveniment system de tip loading, apoi un ai de tip message cu răspunsul, și nimic după aceea. De aceea exemplele se opresc la prima interogare care nu aduce evenimente noi după ce a sosit un răspuns și aruncă o excepție la failed. Dacă flow-ul tău trimite mai multe mesaje sau așteaptă input cu hook_waiting_for_input, decide-ți propria condiție de oprire.
Ordinea argumentelor s-a schimbat pentru trei metode#
Reordonează aceste trei apeluri
Metodele v3 pun parametrii de cale înaintea headerului cu id-ul sesiunii. În PHP, și în Python când trimiți argumentele pozițional, aceste trei apeluri eșuează cu o eroare de tip sau trimit în liniște valori greșite dacă nu le reordonezi.
| 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) |
În Python, trimite argumente numite peste tot, de exemplu x_fh_session_id=session_id, iar ordinea nu mai contează. Python 4.0 verifică și tipurile argumentelor, așa că from_timestamp trebuie să fie un int. Trimiterea șirului "0" ridică o ValidationError pydantic.
Alte modificări incompatibile în 4.0.0#
Aceste metode existau în 3.19.1 și au dispărut în 4.0.0, pentru că endpoint-urile API din spatele lor au fost eliminate sau modificate. Numele metodelor PHP sunt forma camelCase a celor Python, de exemplu get_available_models devine getAvailableModels.
| Metodă eliminată | Endpoint | Ce să faci |
|---|---|---|
AgentGridsApi.get_agent_grid_preview | GET /v2/agent_grids/{agent_grid_id}/preview | Elimină apelul. |
CustomModelsApi.get_available_models | GET /v2/custom-models/available | Elimină apelul. |
FineTuningsApi.create_image_ft, delete_image_ft, search_image_fts, update_image_ft | /v2/photo_ai/images/... | Elimină apelurile. |
WorkspacesApi.update_workspace_auto_recharge | PUT /v2/workspaces/{workspace_id}/auto-recharge | Elimină apelul. |
FlowBatchApi.export_csv | GET /v2/flows/{flow_id}/batch/{batch_run_id}/export-csv | Apelează start_export_csv (POST, aceeași cale), apoi get_export_csv_status (GET .../export-csv/{task_id}). |
Au fost eliminate și metodele pentru canalul Zendesk, facturarea Shopify, Replicate și webhook-urile de tip pingback SERP. Acelea sunt webhook-uri de intrare pentru serverele proprii ale FlowHunt, nu apeluri pe care le face codul tău.
Păstrează id-ul sesiunii secret#
Id-ul sesiunii este o credențială
Oricine are un id de sesiune poate citi și continua acea conversație. Nu îl scrie în loguri, nu îl pune în URL-uri sau șiruri de interogare și nu îl trimite către instrumente de analiză. Tratează-l ca pe o parolă cu durată scurtă de viață.
Ce se întâmplă cu v2?#
Rutele de sesiune v2 sunt depreciate începând cu SDK 4.0.0 și ajung la sfârșitul ciclului de viață pe 30 noiembrie 2026. Până atunci continuă să funcționeze și sunt marcate ca depreciate în referința API. SDK 4.0.0 încă include metodele v2. În Python, apelarea uneia ridică un DeprecationWarning. În PHP, sunt marcate @deprecated în cod, ceea ce IDE-ul sau analiza statică le va semnala.