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.

bash
pip install --upgrade "flowhunt>=4,<5"

PHP

Pachetul de pe Packagist este flowhunt/flowhunt-php-sdk. Necesită PHP 8.1 sau mai nou.

bash
composer require flowhunt/flowhunt-php-sdk:^4.0

Migrare în patru pași#

  1. 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.

  2. Redenumește fiecare apel de sesiune

    Adaugă _v3 la numele metodei Python sau V3 la cel PHP. Corespondența metodelor listează fiecare pereche.

  3. 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.

  4. 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.

CeHTTP v2HTTP v3 (id-ul sesiunii în X-FH-Session-Id)Python 3.x → 4.0PHP 3.x → 4.0
Pornește o sesiune de flow (cheie API)POST /v2/flows/sessions/from_flow/createPOST /v3/flows/sessions/from_flow/createcreate_flow_session → create_flow_session_v3createFlowSession → createFlowSessionV3
Pornește o sesiune de chatbot (anonimă)POST /v2/flows/sessions/createPOST /v3/flows/sessions/createcreate_chatbot_session → create_chatbot_session_v3createChatbotSession → createChatbotSessionV3
Trimite un mesajPOST /v2/flows/sessions/{id}/invokePOST /v3/flows/sessions/invokeinvoke_flow_response → invoke_flow_response_v3invokeFlowResponse → invokeFlowResponseV3
Interoghează evenimentelePOST /v2/flows/sessions/{id}/invocation_response/{from_timestamp}POST /v3/flows/sessions/invocation_response/{from_timestamp}poll_flow_response → poll_flow_response_v3pollFlowResponse → pollFlowResponseV3
Anulează o rularePOST /v2/flows/sessions/{id}/cancelPOST /v3/flows/sessions/cancelcancel_flow_session → cancel_flow_session_v3cancelFlowSession → cancelFlowSessionV3
Revino la ancora anterioarăPOST /v2/flows/sessions/{id}/backPOST /v3/flows/sessions/backgo_back → go_back_v3goBack → goBackV3
Declanșează un hook de chatPOST /v2/flows/sessions/{id}/hookPOST /v3/flows/sessions/hookfire_chat_hook → fire_chat_hook_v3fireChatHook → fireChatHookV3
Reia un hook în așteptarePOST /v2/flows/sessions/{id}/resume-hookPOST /v3/flows/sessions/resume-hookresume_hook → resume_hook_v3resumeHook → resumeHookV3
Setează variabilele de flowPATCH /v2/flows/sessions/{id}/variablesPATCH /v3/flows/sessions/variablesupdate_session_variables → update_session_variables_v3updateSessionVariables → updateSessionVariablesV3
Listează atașamenteleGET /v2/flows/sessions/{id}/attachmentsGET /v3/flows/sessions/attachmentsget_attachments → get_attachments_v3getAttachments → getAttachmentsV3
Încarcă un atașamentPOST /v2/flows/sessions/{id}/attachmentsPOST /v3/flows/sessions/attachmentsupload_attachments → upload_attachments_v3uploadAttachments → uploadAttachmentsV3
Șterge un atașamentDELETE /v2/flows/sessions/{id}/attachments/{file_id}DELETE /v3/flows/sessions/attachments/{file_id}delete_attachment → delete_attachment_v3deleteAttachment → deleteAttachmentV3
Feedback pe mesajPOST /v2/flows/sessions/{id}/feedbackPOST /v3/flows/sessions/feedbackcreate_message_feedback → create_message_feedback_v3createMessageFeedback → createMessageFeedbackV3
Citește un artefactGET /v2/flows/sessions/{id}/artefacts/{artefact_id}GET /v3/flows/sessions/artefacts/{artefact_id}get_artefact_content → get_artefact_content_v3getArtefactContent → getArtefactContentV3
Căutare la tastare (nou, fără v2)niciunulPOST /v3/flows/sessions/searchinvoke_search_v3invokeSearchV3

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

Python, SDK 3.x
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)
Python, SDK 4.0
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:
            break

PHP

PHP, SDK 3.x
$session = $flows->createFlowSession($workspaceId, $request);
$invocation = $flows->invokeFlowResponse($session->getSessionId(), $invokeRequest);
$events = $flows->pollFlowResponse($session->getSessionId(), $fromTimestamp);
PHP, SDK 4.0
<?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.

Start a session (API key)
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\"}"
Send a message
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"}'
Poll for events
curl -X POST "https://api.flowhunt.io/v3/flows/sessions/invocation_response/$FROM_TIMESTAMP" \
  -H "X-FH-Session-Id: $SESSION_ID"
Upload an attachment
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_timestamp este exprimat în milisecunde de la epoch. Interogarea returnează evenimentele al căror created_at_timestamp este strict mai mare.
  • Pornește de la created_at al răspunsului de invocare, care este o valoare în milisecunde trimisă ca șir de caractere, așa că transformă-o în întreg. Folosește 0 pentru a obține întreaga sesiune. Nu folosi created_at al răspunsului de creare, care este o dată și oră, nu milisecunde.
  • După fiecare interogare, mută from_timestamp la created_at_timestamp al celui mai nou eveniment minus 1 și sari peste evenimentele al căror event_id l-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, human sau system), un action_type (message, loading, tool_call, failed, hook_waiting_for_input și altele) și metadata. Textul răspunsului se află în metadata.message al evenimentelor ai de tip message.

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.

v2v3
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ăEndpointCe să faci
AgentGridsApi.get_agent_grid_previewGET /v2/agent_grids/{agent_grid_id}/previewElimină apelul.
CustomModelsApi.get_available_modelsGET /v2/custom-models/availableElimină apelul.
FineTuningsApi.create_image_ft, delete_image_ft, search_image_fts, update_image_ft/v2/photo_ai/images/...Elimină apelurile.
WorkspacesApi.update_workspace_auto_rechargePUT /v2/workspaces/{workspace_id}/auto-rechargeElimină apelul.
FlowBatchApi.export_csvGET /v2/flows/{flow_id}/batch/{batch_run_id}/export-csvApelează 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.