Migracje SDK

Migracja do SDK 4.0 i interfejsu API sesji v3

Przenieś kod w Pythonie i PHP z wywołań sesji flow w wersji v2 na v3, które przesyła identyfikator sesji w nagłówku.

Interfejs API sesji v2 kończy życie 30 listopada 2026 r.

SDK 4.0.0 deprecjonuje wywołania sesji flow v2, takie jak create_flow_session, invoke_flow_response i poll_flow_response. Trasy sesji v2 kończą życie 30 listopada 2026 r. Przenieś swój kod na wywołania v3 opisane na tej stronie, zanim to nastąpi.

Wersja 4.0.0 SDK FlowHunt dla Pythona i PHP dodaje interfejs API sesji flow v3. Przejście na niego sprawia, że identyfikatory sesji czatu nie trafiają do adresów URL, a większość pracy polega na zmianie nazw metod. Ta strona pokazuje, co się zmieniło, które wywołania trzeba przemianować oraz kod przed i po.

Co się zmieniło#

Wywołania sesji v3 przekazują identyfikator sesji w nagłówku X-FH-Session-Id, nigdy w adresie URL. Treść żądań i odpowiedzi jest taka sama jak w v2. Trasy sesji v2 są przestarzałe i kończą życie 30 listopada 2026 r.

W v2 każde wywołanie czatu umieszcza identyfikator sesji w ścieżce, na przykład /v2/flows/sessions/{session_id}/invoke. Identyfikator sesji to jedyne poświadczenie, jakie ma anonimowa sesja czatu, a adresy URL trafiają do logów dostępu, logów proxy, historii przeglądarki i nagłówków Referer. Nagłówek nie.

Instalacja 4.0.0#

Python

Pakiet na PyPI to flowhunt.

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

PHP

Pakiet na Packagist to flowhunt/flowhunt-php-sdk. Wymaga PHP 8.1 lub nowszego.

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

Migracja w czterech krokach#

  1. Zaktualizuj pakiet

    Zainstaluj 4.0.0 w sposób pokazany powyżej. Twoje istniejące wywołania v2 nadal działają po aktualizacji, więc możesz przenosić wywołania jedno po drugim. Zdąż przed 30 listopada 2026 r.

  2. Zmień nazwę każdego wywołania sesji

    Dodaj _v3 do nazwy metody w Pythonie lub V3 do nazwy w PHP. Mapowanie metod zawiera listę wszystkich par.

  3. Przekaż identyfikator sesji jako argument nagłówka

    Argument identyfikatora sesji to teraz x_fh_session_id. W Pythonie przekazuj go jako argument nazwany. W PHP trzy metody przyjmują go jako drugi argument, a nie pierwszy. Zobacz Zmieniona kolejność argumentów w trzech metodach.

  4. Sprawdź usunięte metody

    Jeśli wywołujesz którąkolwiek z metod usuniętych w 4.0.0, przełącz się na zamiennik lub usuń wywołanie.

Mapowanie metod#

Metody Pythona znajdują się w flowhunt.FlowsApi, a te same metody v3 istnieją również w flowhunt.V3Api. Metody PHP znajdują się w FlowHunt\Api\FlowsApi.

CoHTTP v2HTTP v3 (identyfikator sesji w X-FH-Session-Id)Python 3.x → 4.0PHP 3.x → 4.0
Rozpocznij sesję flow (klucz API)POST /v2/flows/sessions/from_flow/createPOST /v3/flows/sessions/from_flow/createcreate_flow_session → create_flow_session_v3createFlowSession → createFlowSessionV3
Rozpocznij sesję chatbota (anonimowo)POST /v2/flows/sessions/createPOST /v3/flows/sessions/createcreate_chatbot_session → create_chatbot_session_v3createChatbotSession → createChatbotSessionV3
Wyślij wiadomośćPOST /v2/flows/sessions/{id}/invokePOST /v3/flows/sessions/invokeinvoke_flow_response → invoke_flow_response_v3invokeFlowResponse → invokeFlowResponseV3
Odpytuj o zdarzeniaPOST /v2/flows/sessions/{id}/invocation_response/{from_timestamp}POST /v3/flows/sessions/invocation_response/{from_timestamp}poll_flow_response → poll_flow_response_v3pollFlowResponse → pollFlowResponseV3
Anuluj uruchomieniePOST /v2/flows/sessions/{id}/cancelPOST /v3/flows/sessions/cancelcancel_flow_session → cancel_flow_session_v3cancelFlowSession → cancelFlowSessionV3
Wróć do poprzedniego anchoraPOST /v2/flows/sessions/{id}/backPOST /v3/flows/sessions/backgo_back → go_back_v3goBack → goBackV3
Wywołaj hook czatuPOST /v2/flows/sessions/{id}/hookPOST /v3/flows/sessions/hookfire_chat_hook → fire_chat_hook_v3fireChatHook → fireChatHookV3
Wznów oczekujący hookPOST /v2/flows/sessions/{id}/resume-hookPOST /v3/flows/sessions/resume-hookresume_hook → resume_hook_v3resumeHook → resumeHookV3
Ustaw zmienne flowPATCH /v2/flows/sessions/{id}/variablesPATCH /v3/flows/sessions/variablesupdate_session_variables → update_session_variables_v3updateSessionVariables → updateSessionVariablesV3
Wyświetl załącznikiGET /v2/flows/sessions/{id}/attachmentsGET /v3/flows/sessions/attachmentsget_attachments → get_attachments_v3getAttachments → getAttachmentsV3
Prześlij załącznikPOST /v2/flows/sessions/{id}/attachmentsPOST /v3/flows/sessions/attachmentsupload_attachments → upload_attachments_v3uploadAttachments → uploadAttachmentsV3
Usuń załącznikDELETE /v2/flows/sessions/{id}/attachments/{file_id}DELETE /v3/flows/sessions/attachments/{file_id}delete_attachment → delete_attachment_v3deleteAttachment → deleteAttachmentV3
Opinia o wiadomościPOST /v2/flows/sessions/{id}/feedbackPOST /v3/flows/sessions/feedbackcreate_message_feedback → create_message_feedback_v3createMessageFeedback → createMessageFeedbackV3
Odczytaj artefaktGET /v2/flows/sessions/{id}/artefacts/{artefact_id}GET /v3/flows/sessions/artefacts/{artefact_id}get_artefact_content → get_artefact_content_v3getArtefactContent → getArtefactContentV3
Wyszukiwanie w trakcie pisania (nowe, brak w v2)brakPOST /v3/flows/sessions/searchinvoke_search_v3invokeSearchV3

Pobieranie załącznika (GET /v2/flows/sessions/{id}/attachments/{file_id}) nie ma wersji v3. To wywołanie z panelu wymagające zalogowania i nie jest częścią tej migracji.

Tylko dwa wywołania tworzenia wymagają Twojego klucza API. from_flow/create rozpoczyna sesję dla flow w Twoim workspace i wymaga klucza. create to anonimowa sesja chatbota używana przez osadzony widget czatu, więc nie wymaga klucza. Oba zwracają session_id i created_at z kodem HTTP 201. Każde inne wywołanie sesji v3 wymaga tylko nagłówka X-FH-Session-Id.

Na razie przesyłaj załączniki przez HTTP

W 4.0.0 upload_attachments_v3 i uploadAttachmentsV3 nie potrafią wysłać pliku. API zwraca 422 „Expected UploadFile”, a metoda Pythona odrzuca bajty przed wysłaniem żądania. Metody przesyłania z 3.x mają ten sam problem. Dopóki nie zostanie to naprawione, wysyłaj plik jako multipart/form-data do POST /v3/flows/sessions/attachments z nagłówkiem X-FH-Session-Id. Zakładka HTTP poniżej pokazuje to wywołanie.

Przed i po#

Ten przykład rozpoczyna sesję dla opublikowanego flow, wysyła „Hello” i wypisuje odpowiedź flow. Każda zakładka pokazuje najpierw kod 3.x, a potem kod 4.0, który uruchomiliśmy przeciwko https://api.flowhunt.io. Kod 4.0 odczytuje klucz API, identyfikator workspace i identyfikator flow ze zmiennych środowiskowych 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  # trzymaj w tajemnicy, nigdy nie loguj

    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("Uruchomienie flow nie powiodło się")
            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(); // trzymaj w tajemnicy, nigdy nie loguj

$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);
    // Zwróć uwagę na kolejność: najpierw znacznik czasu, potem identyfikator sesji.
    $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('Uruchomienie flow nie powiodło się');
        }
        if ($event->getEventType() === 'ai' && $event->getActionType() === 'message') {
            echo $event->getMetadata()->getMessage(), PHP_EOL;
            $answered = true;
        }
    }
    if ($answered && !$newEvents) {
        break;
    }
}

HTTP

Tylko wywołanie tworzenia wysyła klucz API. Każde kolejne wywołanie wysyła identyfikator sesji w nagłówku X-FH-Session-Id.

Rozpocznij sesję (klucz API)
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\"}"
Wyślij wiadomość
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"}'
Odpytuj o zdarzenia
curl -X POST "https://api.flowhunt.io/v3/flows/sessions/invocation_response/$FROM_TIMESTAMP" \
  -H "X-FH-Session-Id: $SESSION_ID"
Prześlij załącznik
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"

Wcześniej identyfikator sesji był częścią każdej ścieżki, na przykład /v2/flows/sessions/$SESSION_ID/invoke. Wywołanie v3 bez nagłówka zwraca 401.

Jak działa odpytywanie#

  • from_timestamp to milisekundy od początku epoki. Odpytanie zwraca zdarzenia, których created_at_timestamp jest ściśle większy.
  • Zacznij od created_at z odpowiedzi na wywołanie invoke, która jest wartością w milisekundach wysłaną jako ciąg znaków, więc przekonwertuj ją na liczbę całkowitą. Użyj 0, aby pobrać całą sesję. Nie używaj created_at z odpowiedzi tworzenia, która jest datą i godziną, a nie milisekundami.
  • Po każdym odpytaniu przesuń from_timestamp na wartość created_at_timestamp najnowszego zdarzenia minus 1 i pomiń zdarzenia, których event_id już widziałeś. Zdarzenia utworzone w tej samej milisekundzie mogą nadejść w różnych odpytaniach. Widget czatu FlowHunt odpytuje w ten sam sposób.
  • Każde zdarzenie ma event_type (ai, human lub system), action_type (message, loading, tool_call, failed, hook_waiting_for_input i inne) oraz metadata. Tekst odpowiedzi znajduje się w metadata.message zdarzeń message typu ai.

FlowHunt nie wysyła osobnego zdarzenia „uruchomienie zakończone”. Gdy uruchomiliśmy próbki na jednostopniowym flow, odpytanie zwróciło zdarzenie system typu loading, potem jedno ai message z odpowiedzią i nic więcej. Dlatego próbki zatrzymują się na pierwszym odpytaniu, które po nadejściu odpowiedzi nie przynosi nowych zdarzeń, i zgłaszają wyjątek przy failed. Jeśli Twój flow wysyła kilka wiadomości lub czeka na dane wejściowe z hook_waiting_for_input, ustal własny warunek zakończenia.

Zmieniona kolejność argumentów w trzech metodach#

Zmień kolejność tych trzech wywołań

Metody v3 umieszczają parametry ścieżki przed nagłówkiem identyfikatora sesji. W PHP, a w Pythonie przy przekazywaniu argumentów pozycyjnie, te trzy wywołania kończą się błędem typu albo po cichu wysyłają niewłaściwe wartości, jeśli nie zmienisz ich kolejności.

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)

W Pythonie przekazuj wszędzie argumenty nazwane, na przykład x_fh_session_id=session_id, a kolejność przestaje mieć znaczenie. Python 4.0 sprawdza też typy argumentów, więc from_timestamp musi być typu int. Przekazanie ciągu "0" powoduje błąd pydantic ValidationError.

Inne zmiany łamiące kompatybilność w 4.0.0#

Te metody były w 3.19.1 i zniknęły w 4.0.0, ponieważ punkty końcowe API za nimi zostały usunięte lub zmienione. Nazwy metod PHP to wersje camelCase nazw pythonowych, na przykład get_available_models staje się getAvailableModels.

Usunięta metodaPunkt końcowyCo zrobić
AgentGridsApi.get_agent_grid_previewGET /v2/agent_grids/{agent_grid_id}/previewUsuń wywołanie.
CustomModelsApi.get_available_modelsGET /v2/custom-models/availableUsuń wywołanie.
FineTuningsApi.create_image_ft, delete_image_ft, search_image_fts, update_image_ft/v2/photo_ai/images/...Usuń wywołania.
WorkspacesApi.update_workspace_auto_rechargePUT /v2/workspaces/{workspace_id}/auto-rechargeUsuń wywołanie.
FlowBatchApi.export_csvGET /v2/flows/{flow_id}/batch/{batch_run_id}/export-csvWywołaj start_export_csv (POST, ta sama ścieżka), a następnie get_export_csv_status (GET .../export-csv/{task_id}).

Usunięto także metody dla kanału Zendesk, płatności Shopify, Replicate i webhooków pingback SERP. To przychodzące webhooki dla serwerów FlowHunt, a nie wywołania z Twojego kodu.

Trzymaj identyfikator sesji w tajemnicy#

Identyfikator sesji to poświadczenie

Każdy, kto ma identyfikator sesji, może odczytać tę rozmowę i ją kontynuować. Nie zapisuj go w logach, nie umieszczaj w adresach URL ani ciągach zapytań i nie wysyłaj do narzędzi analitycznych. Traktuj go jak krótkotrwałe hasło.

A co z v2?#

Trasy sesji v2 są przestarzałe od czasu SDK 4.0.0 i kończą życie 30 listopada 2026 r. Do tego czasu nadal działają i są oznaczone jako przestarzałe w dokumentacji API. SDK 4.0.0 nadal zawiera metody v2. W Pythonie wywołanie jednej z nich zgłasza DeprecationWarning. W PHP są oznaczone w kodzie jako @deprecated, co wskaże Twoje IDE lub analiza statyczna.