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.

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

PHP

Balíček na Packagiste je flowhunt/flowhunt-php-sdk. Vyžaduje PHP 8.1 alebo novšie.

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

Migrácia v štyroch krokoch#

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

  2. Premenujte každé volanie session

    Pridajte _v3 k názvu metódy v Pythone alebo V3 k názvu v PHP. Mapovanie metód uvádza všetky páry.

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

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

Čov2 HTTPv3 HTTP (ID session v X-FH-Session-Id)Python 3.x → 4.0PHP 3.x → 4.0
Spustenie session flow (API kľúč)POST /v2/flows/sessions/from_flow/createPOST /v3/flows/sessions/from_flow/createcreate_flow_session → create_flow_session_v3createFlowSession → createFlowSessionV3
Spustenie session chatbota (anonymné)POST /v2/flows/sessions/createPOST /v3/flows/sessions/createcreate_chatbot_session → create_chatbot_session_v3createChatbotSession → createChatbotSessionV3
Odoslanie správyPOST /v2/flows/sessions/{id}/invokePOST /v3/flows/sessions/invokeinvoke_flow_response → invoke_flow_response_v3invokeFlowResponse → 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_v3pollFlowResponse → pollFlowResponseV3
Zrušenie behuPOST /v2/flows/sessions/{id}/cancelPOST /v3/flows/sessions/cancelcancel_flow_session → cancel_flow_session_v3cancelFlowSession → cancelFlowSessionV3
Návrat na predchádzajúci anchorPOST /v2/flows/sessions/{id}/backPOST /v3/flows/sessions/backgo_back → go_back_v3goBack → goBackV3
Spustenie chat hookuPOST /v2/flows/sessions/{id}/hookPOST /v3/flows/sessions/hookfire_chat_hook → fire_chat_hook_v3fireChatHook → fireChatHookV3
Obnovenie čakajúceho hookuPOST /v2/flows/sessions/{id}/resume-hookPOST /v3/flows/sessions/resume-hookresume_hook → resume_hook_v3resumeHook → resumeHookV3
Nastavenie premenných flowPATCH /v2/flows/sessions/{id}/variablesPATCH /v3/flows/sessions/variablesupdate_session_variables → update_session_variables_v3updateSessionVariables → updateSessionVariablesV3
Zoznam prílohGET /v2/flows/sessions/{id}/attachmentsGET /v3/flows/sessions/attachmentsget_attachments → get_attachments_v3getAttachments → getAttachmentsV3
Nahranie prílohyPOST /v2/flows/sessions/{id}/attachmentsPOST /v3/flows/sessions/attachmentsupload_attachments → upload_attachments_v3uploadAttachments → uploadAttachmentsV3
Odstránenie prílohyDELETE /v2/flows/sessions/{id}/attachments/{file_id}DELETE /v3/flows/sessions/attachments/{file_id}delete_attachment → delete_attachment_v3deleteAttachment → deleteAttachmentV3
Spätná väzba na správuPOST /v2/flows/sessions/{id}/feedbackPOST /v3/flows/sessions/feedbackcreate_message_feedback → create_message_feedback_v3createMessageFeedback → createMessageFeedbackV3
Čítanie artefaktuGET /v2/flows/sessions/{id}/artefacts/{artefact_id}GET /v3/flows/sessions/artefacts/{artefact_id}get_artefact_content → get_artefact_content_v3getArtefactContent → getArtefactContentV3
Vyhľadávanie počas písania (nové, bez v2)žiadnePOST /v3/flows/sessions/searchinvoke_search_v3invokeSearchV3

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

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  # 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:
            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(); // 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.

Spustenie session (API kľúč)
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\"}"
Odoslanie správy
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"}'
Zisťovanie udalostí
curl -X POST "https://api.flowhunt.io/v3/flows/sessions/invocation_response/$FROM_TIMESTAMP" \
  -H "X-FH-Session-Id: $SESSION_ID"
Nahranie prílohy
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_timestamp je počet milisekúnd od epochy. Zisťovanie vráti udalosti, ktorých created_at_timestamp je striktne väčší.
  • Začnite od created_at z odpovede na invoke, čo je milisekundová hodnota poslaná ako reťazec, takže ju preveďte na celé číslo. Použite 0, ak chcete celú session. Nepoužívajte created_at z odpovede na vytvorenie, ktoré je dátumom a časom, nie milisekundami.
  • Po každom zisťovaní posuňte from_timestamp na created_at_timestamp najnovšej udalosti mínus 1 a preskočte udalosti, ktorých event_id ste 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, human alebo system), action_type (message, loading, tool_call, failed, hook_waiting_for_input a ďalšie) a metadata. Text odpovede je v metadata.message udalostí message typu ai.

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.

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)

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ódaEndpointČo urobiť
AgentGridsApi.get_agent_grid_previewGET /v2/agent_grids/{agent_grid_id}/previewVolanie odstráňte.
CustomModelsApi.get_available_modelsGET /v2/custom-models/availableVolanie 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_rechargePUT /v2/workspaces/{workspace_id}/auto-rechargeVolanie odstráňte.
FlowBatchApi.export_csvGET /v2/flows/{flow_id}/batch/{batch_run_id}/export-csvZavolajte 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.