SDK-migreringar

Migrera till SDK 4.0 och v3-sessions-API:et

Flytta Python- och PHP-kod från v2-anropen för flow-sessioner till v3, som skickar sessions-id:t i en header.

v2-sessions-API:et upphör att fungera den 30 november 2026

SDK 4.0.0 markerar v2-anropen för flow-sessioner som föråldrade, till exempel create_flow_session, invoke_flow_response och poll_flow_response. v2-sessionsrutterna upphör att fungera den 30 november 2026. Flytta din kod till v3-anropen på den här sidan innan dess.

Version 4.0.0 av FlowHunts Python- och PHP-SDK:er lägger till v3-API:et för flow-sessioner. Genom att byta till det hålls dina chattsessions-id:n borta från URL:er, och det mesta av arbetet består i att byta namn på metoder. Den här sidan visar vad som har ändrats, vilka anrop som ska byta namn och koden före och efter.

Vad som har ändrats#

v3-sessionsanrop tar sessions-id:t i headern X-FH-Session-Id, aldrig i URL:en. Förfrågnings- och svarskropparna är desamma som i v2. v2-sessionsrutterna är föråldrade och upphör att fungera den 30 november 2026.

I v2 lägger varje chattanrop sessions-id:t i sökvägen, till exempel /v2/flows/sessions/{session_id}/invoke. Sessions-id:t är den enda autentiseringsuppgift en anonym chattsession har, och URL:er hamnar i åtkomstloggar, proxyloggar, webbläsarhistorik och Referer-headers. En header gör inte det.

Installera 4.0.0#

Python

Paketet på PyPI heter flowhunt.

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

PHP

Paketet på Packagist heter flowhunt/flowhunt-php-sdk. Det kräver PHP 8.1 eller senare.

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

Migrera i fyra steg#

  1. Uppgradera paketet

    Installera 4.0.0 enligt ovan. Dina befintliga v2-anrop fortsätter att fungera efter uppgraderingen, så du kan flytta ett anrop i taget. Bli klar före den 30 november 2026.

  2. Byt namn på varje sessionsanrop

    Lägg till _v3 i Python-metodnamnet eller V3 i PHP-metodnamnet. Metodmappningen listar alla par.

  3. Skicka sessions-id:t som header-argument

    Argumentet för sessions-id heter nu x_fh_session_id. I Python skickar du det som nyckelord. I PHP tar tre metoder det som andra argument i stället för första. Se ändrad argumentordning för tre metoder.

  4. Kontrollera de borttagna metoderna

    Om du anropar någon av de metoder som togs bort i 4.0.0 byter du till ersättaren eller tar bort anropet.

Metodmappning#

Python-metoderna finns på flowhunt.FlowsApi, och samma v3-metoder finns även på flowhunt.V3Api. PHP-metoderna finns på FlowHunt\Api\FlowsApi.

Vadv2 HTTPv3 HTTP (sessions-id i X-FH-Session-Id)Python 3.x → 4.0PHP 3.x → 4.0
Starta flow-session (API-nyckel)POST /v2/flows/sessions/from_flow/createPOST /v3/flows/sessions/from_flow/createcreate_flow_session → create_flow_session_v3createFlowSession → createFlowSessionV3
Starta chatbottsession (anonym)POST /v2/flows/sessions/createPOST /v3/flows/sessions/createcreate_chatbot_session → create_chatbot_session_v3createChatbotSession → createChatbotSessionV3
Skicka ett meddelandePOST /v2/flows/sessions/{id}/invokePOST /v3/flows/sessions/invokeinvoke_flow_response → invoke_flow_response_v3invokeFlowResponse → invokeFlowResponseV3
Polla efter händelserPOST /v2/flows/sessions/{id}/invocation_response/{from_timestamp}POST /v3/flows/sessions/invocation_response/{from_timestamp}poll_flow_response → poll_flow_response_v3pollFlowResponse → pollFlowResponseV3
Avbryt en körningPOST /v2/flows/sessions/{id}/cancelPOST /v3/flows/sessions/cancelcancel_flow_session → cancel_flow_session_v3cancelFlowSession → cancelFlowSessionV3
Gå tillbaka till föregående ankarePOST /v2/flows/sessions/{id}/backPOST /v3/flows/sessions/backgo_back → go_back_v3goBack → goBackV3
Utlös en chatthookPOST /v2/flows/sessions/{id}/hookPOST /v3/flows/sessions/hookfire_chat_hook → fire_chat_hook_v3fireChatHook → fireChatHookV3
Återuppta en väntande hookPOST /v2/flows/sessions/{id}/resume-hookPOST /v3/flows/sessions/resume-hookresume_hook → resume_hook_v3resumeHook → resumeHookV3
Ange flow-variablerPATCH /v2/flows/sessions/{id}/variablesPATCH /v3/flows/sessions/variablesupdate_session_variables → update_session_variables_v3updateSessionVariables → updateSessionVariablesV3
Lista bilagorGET /v2/flows/sessions/{id}/attachmentsGET /v3/flows/sessions/attachmentsget_attachments → get_attachments_v3getAttachments → getAttachmentsV3
Ladda upp bilagaPOST /v2/flows/sessions/{id}/attachmentsPOST /v3/flows/sessions/attachmentsupload_attachments → upload_attachments_v3uploadAttachments → uploadAttachmentsV3
Ta bort bilagaDELETE /v2/flows/sessions/{id}/attachments/{file_id}DELETE /v3/flows/sessions/attachments/{file_id}delete_attachment → delete_attachment_v3deleteAttachment → deleteAttachmentV3
Återkoppling på meddelandePOST /v2/flows/sessions/{id}/feedbackPOST /v3/flows/sessions/feedbackcreate_message_feedback → create_message_feedback_v3createMessageFeedback → createMessageFeedbackV3
Läs en artefaktGET /v2/flows/sessions/{id}/artefacts/{artefact_id}GET /v3/flows/sessions/artefacts/{artefact_id}get_artefact_content → get_artefact_content_v3getArtefactContent → getArtefactContentV3
Sökning vid skrivning (ny, ingen v2)ingenPOST /v3/flows/sessions/searchinvoke_search_v3invokeSearchV3

Nedladdning av en bilaga (GET /v2/flows/sessions/{id}/attachments/{file_id}) har ingen v3-version. Det är ett inloggat dashboardanrop och ingår inte i den här migreringen.

Endast de två create-anropen behöver din API-nyckel. from_flow/create startar en session för en flow i din arbetsyta och kräver nyckeln. create är den anonyma chatbottsession som den inbäddade chattwidgeten använder och tar därför ingen nyckel. Båda returnerar session_id och created_at med HTTP 201. Alla andra v3-sessionsanrop behöver bara headern X-FH-Session-Id.

Ladda upp bilagor över HTTP tills vidare

I 4.0.0 kan upload_attachments_v3 och uploadAttachmentsV3 inte skicka en fil. API:et returnerar 422 “Expected UploadFile”, och Python-metoden avvisar bytes innan förfrågan skickas. Uppladdningsmetoderna i 3.x har samma problem. Tills det är åtgärdat skickar du filen som multipart/form-data till POST /v3/flows/sessions/attachments med headern X-FH-Session-Id. Fliken HTTP nedan visar anropet.

Före och efter#

Det här exemplet startar en session för en publicerad flow, skickar “Hello” och skriver ut flowens svar. Varje flik visar 3.x-koden först och sedan 4.0-koden som vi körde mot https://api.flowhunt.io. 4.0-koden läser API-nyckeln, arbetsyte-id:t och flow-id:t från miljövariablerna FLOWHUNT_API_KEY, FLOWHUNT_WORKSPACE_ID och 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

Endast create-anropet skickar API-nyckeln. Varje anrop efter det skickar sessions-id:t i headern 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"

Tidigare ingick sessions-id:t i varje sökväg, till exempel /v2/flows/sessions/$SESSION_ID/invoke. Ett v3-anrop utan headern returnerar 401.

Så fungerar polling#

  • from_timestamp är millisekunder sedan epoken. Pollingen returnerar de händelser vars created_at_timestamp är strikt större.
  • Utgå från created_at i invoke-svaret, som är ett millisekundvärde skickat som en sträng, och konvertera det därför till ett heltal. Använd 0 för att få hela sessionen. Använd inte created_at i create-svaret, som är ett datum och en tid, inte millisekunder.
  • Efter varje polling flyttar du from_timestamp till den nyaste händelsens created_at_timestamp minus 1 och hoppar över händelser vars event_id du redan har sett. Händelser som skapas i samma millisekund kan komma i olika pollningar. FlowHunts chattwidget pollar på samma sätt.
  • Varje händelse har en event_type (ai, human eller system), en action_type (message, loading, tool_call, failed, hook_waiting_for_input med flera) och metadata. Själva svarstexten finns i metadata.message för ai-händelserna av typen message.

FlowHunt skickar ingen separat “run finished”-händelse. När vi körde exemplen mot en flow med ett steg returnerade pollingen en system-händelse av typen loading, sedan en ai-händelse av typen message med svaret, och inget efter det. Därför stannar exemplen vid den första polling som inte ger några nya händelser efter att ett svar har kommit, och kastar ett fel vid failed. Om din flow skickar flera meddelanden eller väntar på indata med hook_waiting_for_input får du själv bestämma stoppvillkoret.

Ändrad argumentordning för tre metoder#

Byt ordning på dessa tre anrop

v3-metoderna sätter sökvägsparametrar före session-id-headern. I PHP, och i Python när du skickar argument positionellt, misslyckas dessa tre anrop med ett typfel eller skickar tyst fel värden om du inte byter ordning på dem.

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)

I Python skickar du nyckelordargument överallt, till exempel x_fh_session_id=session_id, och då spelar ordningen ingen roll längre. Python 4.0 kontrollerar även argumenttyper, så from_timestamp måste vara en int. Att skicka strängen "0" ger en pydantic-ValidationError.

Andra brytande ändringar i 4.0.0#

De här metoderna fanns i 3.19.1 och är borta i 4.0.0, eftersom API-slutpunkterna bakom dem togs bort eller ändrades. PHP-metodnamnen är camelCase-formen av Python-namnen, till exempel blir get_available_models getAvailableModels.

Borttagen metodSlutpunktVad du ska göra
AgentGridsApi.get_agent_grid_previewGET /v2/agent_grids/{agent_grid_id}/previewTa bort anropet.
CustomModelsApi.get_available_modelsGET /v2/custom-models/availableTa bort anropet.
FineTuningsApi.create_image_ft, delete_image_ft, search_image_fts, update_image_ft/v2/photo_ai/images/...Ta bort anropen.
WorkspacesApi.update_workspace_auto_rechargePUT /v2/workspaces/{workspace_id}/auto-rechargeTa bort anropet.
FlowBatchApi.export_csvGET /v2/flows/{flow_id}/batch/{batch_run_id}/export-csvAnropa start_export_csv (POST, samma sökväg) och sedan get_export_csv_status (GET .../export-csv/{task_id}).

Metoderna för Zendesk-kanalen, Shopify-fakturering, Replicate och SERP-pingback-webhooks togs också bort. Det är inkommande webhooks för FlowHunts egna servrar, inte anrop som din kod gör.

Håll sessions-id:t hemligt#

Sessions-id:t är en autentiseringsuppgift

Den som har ett sessions-id kan läsa och fortsätta den konversationen. Logga det inte, lägg det inte i URL:er eller query-strängar och skicka det inte till analysverktyg. Behandla det som ett kortlivat lösenord.

Vad händer med v2?#

v2-sessionsrutterna är föråldrade från och med SDK 4.0.0 och upphör att fungera den 30 november 2026. Fram till dess fungerar de, och de är markerade som föråldrade i API-referensen. SDK 4.0.0 innehåller fortfarande v2-metoderna. I Python ger ett anrop en DeprecationWarning. I PHP är de markerade med @deprecated i koden, vilket din IDE eller statiska analys flaggar.