SDK-migreringer

Migrer til SDK 4.0 og v3-sesjons-API-et

Flytt Python- og PHP-kode fra v2-kallene for flytsesjoner til v3, som sender sesjons-id-en i en header.

v2-sesjons-API-et når slutten på levetiden 30. november 2026

SDK 4.0.0 avskriver v2-kallene for flytsesjoner, som create_flow_session, invoke_flow_response og poll_flow_response. v2-sesjonsrutene når slutten på levetiden 30. november 2026. Flytt koden din til v3-kallene på denne siden før den tid.

Versjon 4.0.0 av FlowHunt sine Python- og PHP-SDK-er legger til v3-API-et for flytsesjoner. Ved å flytte over til det holder du sesjons-id-ene for chatten din unna URL-er, og mesteparten av arbeidet er å gi metoder nye navn. Denne siden viser hva som er endret, hvilke kall som skal gis nye navn, og koden før og etter.

Hva som er endret#

v3-sesjonskall tar sesjons-id-en i X-FH-Session-Id-headeren, aldri i URL-en. Forespørsels- og svartekstene er de samme som i v2. v2-sesjonsrutene er avskrevet og når slutten på levetiden 30. november 2026.

I v2 legger hvert chatkall sesjons-id-en i stien, for eksempel /v2/flows/sessions/{session_id}/invoke. Sesjons-id-en er den eneste legitimasjonen en anonym chatøkt har, og URL-er havner i tilgangslogger, proxy-logger, nettleserhistorikk og Referer-headere. Det gjør ikke en header.

Installer 4.0.0#

Python

Pakken på PyPI er flowhunt.

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

PHP

Pakken på Packagist er flowhunt/flowhunt-php-sdk. Den krever PHP 8.1 eller nyere.

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

Migrer i fire trinn#

  1. Oppgrader pakken

    Installer 4.0.0 som vist over. De eksisterende v2-kallene dine fortsetter å virke etter oppgraderingen, så du kan flytte ett kall om gangen. Bli ferdig før 30. november 2026.

  2. Gi hvert sesjonskall nytt navn

    Legg til _v3 i Python-metodenavnet eller V3 i PHP-navnet. Metodetilordningen lister opp hvert par.

  3. Send sesjons-id-en som header-argumentet

    Argumentet for sesjons-id er nå x_fh_session_id. I Python sender du det som nøkkelordargument. I PHP tar tre metoder det som andre argument i stedet for første. Se argumentrekkefølgen er endret for tre metoder.

  4. Sjekk de fjernede metodene

    Hvis du kaller noen av metodene som er fjernet i 4.0.0, bytt til erstatningen eller fjern kallet.

Metodetilordning#

Python-metodene ligger på flowhunt.FlowsApi, og de samme v3-metodene finnes også på flowhunt.V3Api. PHP-metodene ligger på FlowHunt\Api\FlowsApi.

Hvav2 HTTPv3 HTTP (sesjons-id i X-FH-Session-Id)Python 3.x → 4.0PHP 3.x → 4.0
Start flytsesjon (API-nøkkel)POST /v2/flows/sessions/from_flow/createPOST /v3/flows/sessions/from_flow/createcreate_flow_session → create_flow_session_v3createFlowSession → createFlowSessionV3
Start chatbotsesjon (anonym)POST /v2/flows/sessions/createPOST /v3/flows/sessions/createcreate_chatbot_session → create_chatbot_session_v3createChatbotSession → createChatbotSessionV3
Send en meldingPOST /v2/flows/sessions/{id}/invokePOST /v3/flows/sessions/invokeinvoke_flow_response → invoke_flow_response_v3invokeFlowResponse → invokeFlowResponseV3
Poll for hendelserPOST /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 kjøringPOST /v2/flows/sessions/{id}/cancelPOST /v3/flows/sessions/cancelcancel_flow_session → cancel_flow_session_v3cancelFlowSession → cancelFlowSessionV3
Gå tilbake til forrige ankerPOST /v2/flows/sessions/{id}/backPOST /v3/flows/sessions/backgo_back → go_back_v3goBack → goBackV3
Utløs en chat-hookPOST /v2/flows/sessions/{id}/hookPOST /v3/flows/sessions/hookfire_chat_hook → fire_chat_hook_v3fireChatHook → fireChatHookV3
Gjenoppta en ventende hookPOST /v2/flows/sessions/{id}/resume-hookPOST /v3/flows/sessions/resume-hookresume_hook → resume_hook_v3resumeHook → resumeHookV3
Sett flytvariablerPATCH /v2/flows/sessions/{id}/variablesPATCH /v3/flows/sessions/variablesupdate_session_variables → update_session_variables_v3updateSessionVariables → updateSessionVariablesV3
List vedleggGET /v2/flows/sessions/{id}/attachmentsGET /v3/flows/sessions/attachmentsget_attachments → get_attachments_v3getAttachments → getAttachmentsV3
Last opp vedleggPOST /v2/flows/sessions/{id}/attachmentsPOST /v3/flows/sessions/attachmentsupload_attachments → upload_attachments_v3uploadAttachments → uploadAttachmentsV3
Slett vedleggDELETE /v2/flows/sessions/{id}/attachments/{file_id}DELETE /v3/flows/sessions/attachments/{file_id}delete_attachment → delete_attachment_v3deleteAttachment → deleteAttachmentV3
Tilbakemelding på meldingPOST /v2/flows/sessions/{id}/feedbackPOST /v3/flows/sessions/feedbackcreate_message_feedback → create_message_feedback_v3createMessageFeedback → createMessageFeedbackV3
Les 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øk mens du skriver (ny, ingen v2)ingenPOST /v3/flows/sessions/searchinvoke_search_v3invokeSearchV3

Nedlasting av et vedlegg (GET /v2/flows/sessions/{id}/attachments/{file_id}) har ingen v3-versjon. Det er et kall fra det innloggede dashbordet og er ikke en del av denne migreringen.

Bare de to opprettelseskallene trenger API-nøkkelen din. from_flow/create starter en sesjon for en flyt i arbeidsområdet ditt og krever nøkkelen. create er den anonyme chatbotsesjonen som den innebygde chat-widgeten bruker, så den tar ingen nøkkel. Begge returnerer session_id og created_at med HTTP 201. Hvert andre v3-sesjonskall trenger bare X-FH-Session-Id-headeren.

Last opp vedlegg over HTTP inntil videre

I 4.0.0 kan ikke upload_attachments_v3 og uploadAttachmentsV3 sende en fil. API-et returnerer 422 “Expected UploadFile”, og Python-metoden avviser bytes før forespørselen sendes. Opplastingsmetodene i 3.x har samme problem. Inntil det er rettet, sender du filen som multipart/form-data til POST /v3/flows/sessions/attachments med X-FH-Session-Id-headeren. HTTP-fanen nedenfor viser kallet.

Før og etter#

Dette eksemplet starter en sesjon for en publisert flyt, sender “Hello” og skriver ut svaret fra flyten. Hver fane viser først 3.x-koden, deretter 4.0-koden vi kjørte mot https://api.flowhunt.io. 4.0-koden leser API-nøkkelen, arbeidsområde-id-en og flyt-id-en 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  # 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

Bare opprettelseskallet sender API-nøkkelen. Hvert kall etter det sender sesjons-id-en i X-FH-Session-Id-headeren.

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"

Tidligere var sesjons-id-en en del av hver sti, for eksempel /v2/flows/sessions/$SESSION_ID/invoke. Et v3-kall uten headeren returnerer 401.

Hvordan polling fungerer#

  • from_timestamp er millisekunder siden epoken. Pollingen returnerer hendelsene der created_at_timestamp er strengt større.
  • Start fra created_at i invoke-svaret, som er en millisekundverdi sendt som en streng, så konverter den til et heltall. Bruk 0 for å få hele sesjonen. Ikke bruk created_at fra opprettelsessvaret, som er en dato og et klokkeslett, ikke millisekunder.
  • Etter hver polling flytter du from_timestamp til den nyeste hendelsens created_at_timestamp minus 1 og hopper over hendelser der du allerede har sett event_id. Hendelser som er opprettet i samme millisekund, kan komme i ulike pollinger. FlowHunt-chatwidgeten poller på samme måte.
  • Hver hendelse har en event_type (ai, human eller system), en action_type (message, loading, tool_call, failed, hook_waiting_for_input og andre) og metadata. Svareteksten ligger i metadata.message i ai-hendelsene av typen message.

FlowHunt sender ikke en egen “kjøring fullført”-hendelse. Da vi kjørte eksemplene mot en flyt med ett trinn, returnerte pollingen en system-hendelse av typen loading, deretter én ai-hendelse av typen message med svaret, og ingenting etter det. Derfor stopper eksemplene ved den første pollingen som ikke gir nye hendelser etter at et svar har kommet inn, og kaster en feil ved failed. Hvis flyten din sender flere meldinger eller venter på input med hook_waiting_for_input, må du bestemme din egen stoppbetingelse.

Argumentrekkefølgen er endret for tre metoder#

Endre rekkefølgen i disse tre kallene

v3-metodene setter sti-parametere før headeren for sesjons-id. I PHP, og i Python når du sender argumenter posisjonsbasert, feiler disse tre kallene med en typefeil eller sender stille og rolig feil verdier med mindre du endrer rekkefølgen.

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 bruke nøkkelordargumenter overalt, for eksempel x_fh_session_id=session_id, og da spiller rekkefølgen ingen rolle. Python 4.0 sjekker også argumenttypene, så from_timestamp må være en int. Sender du strengen "0", kastes en pydantic ValidationError.

Andre brytende endringer i 4.0.0#

Disse metodene fantes i 3.19.1 og er borte i 4.0.0, fordi API-endepunktene bak dem er fjernet eller endret. PHP-metodenavnene er camelCase-formen av Python-navnene, for eksempel blir get_available_models til getAvailableModels.

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

Metodene for Zendesk-kanalen, Shopify-fakturering, Replicate og SERP-pingback-webhooks ble også fjernet. Det er innkommende webhooks for FlowHunt sine egne servere, ikke kall koden din gjør.

Hold sesjons-id-en hemmelig#

Sesjons-id-en er en legitimasjon

Alle som har en sesjons-id, kan lese og fortsette den samtalen. Ikke logg den, ikke legg den i URL-er eller spørringstekster, og ikke send den til analyseverktøy. Behandle den som et kortlevd passord.

Hva med v2?#

v2-sesjonsrutene er avskrevet fra og med SDK 4.0.0 og når slutten på levetiden 30. november 2026. Inntil da fortsetter de å virke, og de er merket som avskrevet i API-referansen. SDK 4.0.0 inneholder fortsatt v2-metodene. I Python gir et kall en DeprecationWarning. I PHP er de merket @deprecated i koden, noe IDE-en eller statisk analyse vil varsle om.