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.

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

PHP

Balíček na Packagistu je flowhunt/flowhunt-php-sdk. Vyžaduje PHP 8.1 nebo novější.

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

Migrace ve čtyřech krocích#

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

  2. Přejmenujte každé volání relace

    Přidejte _v3 k názvu metody v Pythonu nebo V3 k názvu metody v PHP. Mapování metod uvádí všechny dvojice.

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

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

Cov2 HTTPv3 HTTP (ID relace v X-FH-Session-Id)Python 3.x → 4.0PHP 3.x → 4.0
Zahájení relace flow (API klíč)POST /v2/flows/sessions/from_flow/createPOST /v3/flows/sessions/from_flow/createcreate_flow_session → create_flow_session_v3createFlowSession → createFlowSessionV3
Zahájení relace chatbota (anonymní)POST /v2/flows/sessions/createPOST /v3/flows/sessions/createcreate_chatbot_session → create_chatbot_session_v3createChatbotSession → createChatbotSessionV3
Odeslání zprávyPOST /v2/flows/sessions/{id}/invokePOST /v3/flows/sessions/invokeinvoke_flow_response → invoke_flow_response_v3invokeFlowResponse → invokeFlowResponseV3
Dotazování na událostiPOST /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šení běhuPOST /v2/flows/sessions/{id}/cancelPOST /v3/flows/sessions/cancelcancel_flow_session → cancel_flow_session_v3cancelFlowSession → cancelFlowSessionV3
Návrat na předchozí ukotveníPOST /v2/flows/sessions/{id}/backPOST /v3/flows/sessions/backgo_back → go_back_v3goBack → goBackV3
Spuštění chat hookuPOST /v2/flows/sessions/{id}/hookPOST /v3/flows/sessions/hookfire_chat_hook → fire_chat_hook_v3fireChatHook → fireChatHookV3
Obnovení čekajícího hookuPOST /v2/flows/sessions/{id}/resume-hookPOST /v3/flows/sessions/resume-hookresume_hook → resume_hook_v3resumeHook → resumeHookV3
Nastavení proměnných flowPATCH /v2/flows/sessions/{id}/variablesPATCH /v3/flows/sessions/variablesupdate_session_variables → update_session_variables_v3updateSessionVariables → updateSessionVariablesV3
Výpis přílohGET /v2/flows/sessions/{id}/attachmentsGET /v3/flows/sessions/attachmentsget_attachments → get_attachments_v3getAttachments → getAttachmentsV3
Nahrání přílohyPOST /v2/flows/sessions/{id}/attachmentsPOST /v3/flows/sessions/attachmentsupload_attachments → upload_attachments_v3uploadAttachments → uploadAttachmentsV3
Smazání přílohyDELETE /v2/flows/sessions/{id}/attachments/{file_id}DELETE /v3/flows/sessions/attachments/{file_id}delete_attachment → delete_attachment_v3deleteAttachment → deleteAttachmentV3
Zpětná vazba ke zprávěPOST /v2/flows/sessions/{id}/feedbackPOST /v3/flows/sessions/feedbackcreate_message_feedback → create_message_feedback_v3createMessageFeedback → createMessageFeedbackV3
Čtení artefaktuGET /v2/flows/sessions/{id}/artefacts/{artefact_id}GET /v3/flows/sessions/artefacts/{artefact_id}get_artefact_content → get_artefact_content_v3getArtefactContent → getArtefactContentV3
Vyhledávání při psaní (novinka, bez v2)žádnéPOST /v3/flows/sessions/searchinvoke_search_v3invokeSearchV3

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

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

Zahájení relace (API klíč)
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\"}"
Odeslání zprá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"}'
Dotazování na události
curl -X POST "https://api.flowhunt.io/v3/flows/sessions/invocation_response/$FROM_TIMESTAMP" \
  -H "X-FH-Session-Id: $SESSION_ID"
Nahrání pří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"

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_timestamp je počet milisekund od epochy. Dotaz vrací události, jejichž created_at_timestamp je striktně větší.
  • Začněte hodnotou created_at z 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žijte 0. Nepoužívejte created_at z odpovědi na vytvoření, což je datum a čas, ne milisekundy.
  • Po každém dotazu posuňte from_timestamp na created_at_timestamp nejnovější události minus 1 a přeskakujte události, jejichž event_id jste 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, human nebo system), action_type (message, loading, tool_call, failed, hook_waiting_for_input a další) a metadata. Text odpovědi je v metadata.message událostí ai s typem message.

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.

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 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á metodaKoncový bodCo dělat
AgentGridsApi.get_agent_grid_previewGET /v2/agent_grids/{agent_grid_id}/previewVolání odstraňte.
CustomModelsApi.get_available_modelsGET /v2/custom-models/availableVolá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_rechargePUT /v2/workspaces/{workspace_id}/auto-rechargeVolání odstraňte.
FlowBatchApi.export_csvGET /v2/flows/{flow_id}/batch/{batch_run_id}/export-csvZavolejte 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čí.