SDK-migreringer

Migrer til SDK 4.0 og v3-session-API'et

Flyt Python- og PHP-kode fra v2-flow-session-kaldene til v3, som sender session-id’et i en header.

v2-session-API'et udgår den 30. november 2026

SDK 4.0.0 markerer v2-flow-session-kaldene som forældede, for eksempel create_flow_session, invoke_flow_response og poll_flow_response. v2-sessionruterne udgår den 30. november 2026. Flyt din kode til v3-kaldene på denne side inden da.

Version 4.0.0 af FlowHunts Python- og PHP-SDK’er tilføjer v3-flow-session-API’et. Når du skifter til det, holdes dine chat-session-id’er ude af URL’er, og det meste af arbejdet består i at omdøbe metoder. Denne side viser, hvad der er ændret, hvilke kald du skal omdøbe, og koden før og efter.

Hvad er ændret#

v3-sessionskald tager session-id’et i headeren X-FH-Session-Id, aldrig i URL’en. Request- og response-bodies er de samme som i v2. v2-sessionruterne er forældede og udgår den 30. november 2026.

I v2 lægger hvert chatkald session-id’et i stien, for eksempel /v2/flows/sessions/{session_id}/invoke. Session-id’et er den eneste legitimationsoplysning, en anonym chatsession har, og URL’er ender i accesslogs, proxylogs, browserhistorik og Referer-headere. Det gør en header ikke.

Installér 4.0.0#

Python

Pakken på PyPI hedder flowhunt.

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

PHP

Pakken på Packagist hedder flowhunt/flowhunt-php-sdk. Den kræver PHP 8.1 eller nyere.

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

Migrér i fire trin#

  1. Opgrader pakken

    Installér 4.0.0 som vist ovenfor. Dine eksisterende v2-kald virker stadig efter opgraderingen, så du kan flytte ét kald ad gangen. Afslut inden den 30. november 2026.

  2. Omdøb hvert sessionskald

    Tilføj _v3 til Python-metodens navn eller V3 til PHP-metodens. Metodetilknytningen viser hvert par.

  3. Send session-id’et som header-argument

    Argumentet for session-id er nu x_fh_session_id. I Python sendes det som keyword-argument. I PHP tager tre metoder det som det andet argument i stedet for det første. Se argumentrækkefølgen er ændret for tre metoder.

  4. Tjek de fjernede metoder

    Hvis du kalder nogen af de metoder, der er fjernet i 4.0.0, skal du skifte til erstatningen eller fjerne kaldet.

Metodetilknytning#

Python-metoderne ligger på flowhunt.FlowsApi, og de samme v3-metoder findes også på flowhunt.V3Api. PHP-metoderne ligger på FlowHunt\Api\FlowsApi.

Hvadv2 HTTPv3 HTTP (session-id i X-FH-Session-Id)Python 3.x → 4.0PHP 3.x → 4.0
Start flowsession (API-nøgle)POST /v2/flows/sessions/from_flow/createPOST /v3/flows/sessions/from_flow/createcreate_flow_session → create_flow_session_v3createFlowSession → createFlowSessionV3
Start chatbotsession (anonym)POST /v2/flows/sessions/createPOST /v3/flows/sessions/createcreate_chatbot_session → create_chatbot_session_v3createChatbotSession → createChatbotSessionV3
Send en beskedPOST /v2/flows/sessions/{id}/invokePOST /v3/flows/sessions/invokeinvoke_flow_response → invoke_flow_response_v3invokeFlowResponse → invokeFlowResponseV3
Poll efter eventsPOST /v2/flows/sessions/{id}/invocation_response/{from_timestamp}POST /v3/flows/sessions/invocation_response/{from_timestamp}poll_flow_response → poll_flow_response_v3pollFlowResponse → pollFlowResponseV3
Annullér en kørselPOST /v2/flows/sessions/{id}/cancelPOST /v3/flows/sessions/cancelcancel_flow_session → cancel_flow_session_v3cancelFlowSession → cancelFlowSessionV3
Gå tilbage til forrige ankerPOST /v2/flows/sessions/{id}/backPOST /v3/flows/sessions/backgo_back → go_back_v3goBack → goBackV3
Udløs en chat-hookPOST /v2/flows/sessions/{id}/hookPOST /v3/flows/sessions/hookfire_chat_hook → fire_chat_hook_v3fireChatHook → fireChatHookV3
Genoptag en ventende hookPOST /v2/flows/sessions/{id}/resume-hookPOST /v3/flows/sessions/resume-hookresume_hook → resume_hook_v3resumeHook → resumeHookV3
Angiv flowvariablerPATCH /v2/flows/sessions/{id}/variablesPATCH /v3/flows/sessions/variablesupdate_session_variables → update_session_variables_v3updateSessionVariables → updateSessionVariablesV3
Vis vedhæftede filerGET /v2/flows/sessions/{id}/attachmentsGET /v3/flows/sessions/attachmentsget_attachments → get_attachments_v3getAttachments → getAttachmentsV3
Upload vedhæftet filPOST /v2/flows/sessions/{id}/attachmentsPOST /v3/flows/sessions/attachmentsupload_attachments → upload_attachments_v3uploadAttachments → uploadAttachmentsV3
Slet vedhæftet filDELETE /v2/flows/sessions/{id}/attachments/{file_id}DELETE /v3/flows/sessions/attachments/{file_id}delete_attachment → delete_attachment_v3deleteAttachment → deleteAttachmentV3
Feedback på beskedPOST /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øg efter type (ny, ingen v2)ingenPOST /v3/flows/sessions/searchinvoke_search_v3invokeSearchV3

Download af en vedhæftet fil (GET /v2/flows/sessions/{id}/attachments/{file_id}) har ingen v3-version. Det er et dashboard-kald for indloggede brugere og er ikke en del af denne migrering.

Kun de to create-kald kræver din API-nøgle. from_flow/create starter en session for et flow i dit workspace og kræver nøglen. create er den anonyme chatbotsession, som den indlejrede chat-widget bruger, så den tager ingen nøgle. Begge returnerer session_id og created_at med HTTP 201. Alle andre v3-sessionskald kræver kun headeren X-FH-Session-Id.

Upload vedhæftede filer over HTTP indtil videre

I 4.0.0 kan upload_attachments_v3 og uploadAttachmentsV3 ikke sende en fil. API’et returnerer 422 “Expected UploadFile”, og Python-metoden afviser bytes, før requesten sendes. 3.x-uploadmetoderne har samme problem. Indtil det er rettet, skal du sende filen som multipart/form-data til POST /v3/flows/sessions/attachments med headeren X-FH-Session-Id. HTTP-fanen nedenfor viser kaldet.

Før og efter#

Dette eksempel starter en session for et publiceret flow, sender “Hello” og udskriver flowets svar. Hver fane viser først 3.x-koden og derefter 4.0-koden, som vi kørte mod https://api.flowhunt.io. 4.0-koden læser API-nøglen, workspace-id’et og flow-id’et fra miljøvariablene FLOWHUNT_API_KEY, FLOWHUNT_WORKSPACE_ID og 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  # hold den hemmelig, log den aldrig

    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("Flow-kørslen mislykkedes")
            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(); // hold den hemmelig, log den aldrig

$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);
    // Bemærk rækkefølgen: tidsstempel først, session-id derefter.
    $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('Flow-kørslen mislykkedes');
        }
        if ($event->getEventType() === 'ai' && $event->getActionType() === 'message') {
            echo $event->getMetadata()->getMessage(), PHP_EOL;
            $answered = true;
        }
    }
    if ($answered && !$newEvents) {
        break;
    }
}

HTTP

Kun create-kaldet sender API-nøglen. Alle kald efter det sender session-id’et i headeren X-FH-Session-Id.

Start en session (API-nøgle)
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 en besked
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 efter events
curl -X POST "https://api.flowhunt.io/v3/flows/sessions/invocation_response/$FROM_TIMESTAMP" \
  -H "X-FH-Session-Id: $SESSION_ID"
Upload en vedhæftet fil
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"

Tidligere var session-id’et en del af hver sti, for eksempel /v2/flows/sessions/$SESSION_ID/invoke. Et v3-kald uden headeren returnerer 401.

Sådan fungerer polling#

  • from_timestamp er millisekunder siden epoch. Pollingen returnerer de events, hvis created_at_timestamp er strengt større.
  • Start fra created_at i invoke-response, som er en millisekundværdi sendt som en streng, så konvertér den til et heltal. Brug 0 for at få hele sessionen. Brug ikke created_at fra create-response, som er en dato og et klokkeslæt, ikke millisekunder.
  • Efter hver polling flyttes from_timestamp til det nyeste events created_at_timestamp minus 1, og du springer events over, hvis event_id du allerede har set. Events, der oprettes i samme millisekund, kan ankomme i forskellige pollinger. FlowHunts chat-widget poller på samme måde.
  • Hvert event har en event_type (ai, human eller system), en action_type (message, loading, tool_call, failed, hook_waiting_for_input og andre) og metadata. Svarets tekst findes i metadata.message på ai-events af typen message.

FlowHunt sender ikke et separat “run finished”-event. Da vi kørte eksemplerne mod et flow med ét trin, returnerede pollingen et system loading-event, derefter ét ai message med svaret og intet derefter. Derfor stopper eksemplerne ved den første polling, der ikke bringer nye events, efter at et svar er ankommet, og kaster en fejl ved failed. Hvis dit flow sender flere beskeder eller venter på input med hook_waiting_for_input, må du selv beslutte stopbetingelsen.

Argumentrækkefølgen er ændret for tre metoder#

Omarrangér disse tre kald

v3-metoderne placerer path-parametre før session-id-headeren. I PHP, og i Python når du sender argumenter positionelt, fejler disse tre kald med en typefejl eller sender lydløst de forkerte værdier, medmindre du omarrangerer 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 bør du bruge keyword-argumenter overalt, for eksempel x_fh_session_id=session_id, og så betyder rækkefølgen ikke længere noget. Python 4.0 kontrollerer også argumenttyper, så from_timestamp skal være en int. Sendes strengen "0", udløses en pydantic-ValidationError.

Andre brydende ændringer i 4.0.0#

Disse metoder fandtes i 3.19.1 og er væk i 4.0.0, fordi de bagvedliggende API-endpoints er fjernet eller ændret. PHP-metodernes navne er camelCase-formen af Python-navnene, for eksempel bliver get_available_models til getAvailableModels.

Fjernet metodeEndpointHvad du skal gøre
AgentGridsApi.get_agent_grid_previewGET /v2/agent_grids/{agent_grid_id}/previewFjern kaldet.
CustomModelsApi.get_available_modelsGET /v2/custom-models/availableFjern kaldet.
FineTuningsApi.create_image_ft, delete_image_ft, search_image_fts, update_image_ft/v2/photo_ai/images/...Fjern kaldene.
WorkspacesApi.update_workspace_auto_rechargePUT /v2/workspaces/{workspace_id}/auto-rechargeFjern kaldet.
FlowBatchApi.export_csvGET /v2/flows/{flow_id}/batch/{batch_run_id}/export-csvKald start_export_csv (POST, samme sti), derefter get_export_csv_status (GET .../export-csv/{task_id}).

Metoderne til Zendesk-kanalen, Shopify-fakturering, Replicate og SERP-pingback-webhooks er også fjernet. Det er indgående webhooks til FlowHunts egne servere, ikke kald din kode laver.

Hold session-id’et hemmeligt#

Session-id'et er en legitimationsoplysning

Alle, der har et session-id, kan læse og fortsætte den pågældende samtale. Log det ikke, læg det ikke i URL’er eller query strings, og send det ikke til analyseværktøjer. Behandl det som en kortlivet adgangskode.

Hvad med v2?#

v2-sessionruterne er forældede fra og med SDK 4.0.0 og udgår den 30. november 2026. Indtil da virker de stadig, og de er markeret som forældede i API-referencen. SDK 4.0.0 indeholder stadig v2-metoderne. I Python udløser et kald en DeprecationWarning. I PHP er de markeret med @deprecated i koden, hvilket din IDE eller statisk analyse vil markere.