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.
pip install --upgrade "flowhunt>=4,<5"PHP
Pakken på Packagist er flowhunt/flowhunt-php-sdk. Den krever PHP 8.1 eller nyere.
composer require flowhunt/flowhunt-php-sdk:^4.0Migrer i fire trinn#
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.
Gi hvert sesjonskall nytt navn
Legg til
_v3i Python-metodenavnet ellerV3i PHP-navnet. Metodetilordningen lister opp hvert par.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.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.
| Hva | v2 HTTP | v3 HTTP (sesjons-id i X-FH-Session-Id) | Python 3.x → 4.0 | PHP 3.x → 4.0 |
|---|---|---|---|---|
| Start flytsesjon (API-nøkkel) | POST /v2/flows/sessions/from_flow/create | POST /v3/flows/sessions/from_flow/create | create_flow_session → create_flow_session_v3 | createFlowSession → createFlowSessionV3 |
| Start chatbotsesjon (anonym) | POST /v2/flows/sessions/create | POST /v3/flows/sessions/create | create_chatbot_session → create_chatbot_session_v3 | createChatbotSession → createChatbotSessionV3 |
| Send en melding | POST /v2/flows/sessions/{id}/invoke | POST /v3/flows/sessions/invoke | invoke_flow_response → invoke_flow_response_v3 | invokeFlowResponse → invokeFlowResponseV3 |
| Poll for hendelser | POST /v2/flows/sessions/{id}/invocation_response/{from_timestamp} | POST /v3/flows/sessions/invocation_response/{from_timestamp} | poll_flow_response → poll_flow_response_v3 | pollFlowResponse → pollFlowResponseV3 |
| Avbryt en kjøring | POST /v2/flows/sessions/{id}/cancel | POST /v3/flows/sessions/cancel | cancel_flow_session → cancel_flow_session_v3 | cancelFlowSession → cancelFlowSessionV3 |
| Gå tilbake til forrige anker | POST /v2/flows/sessions/{id}/back | POST /v3/flows/sessions/back | go_back → go_back_v3 | goBack → goBackV3 |
| Utløs en chat-hook | POST /v2/flows/sessions/{id}/hook | POST /v3/flows/sessions/hook | fire_chat_hook → fire_chat_hook_v3 | fireChatHook → fireChatHookV3 |
| Gjenoppta en ventende hook | POST /v2/flows/sessions/{id}/resume-hook | POST /v3/flows/sessions/resume-hook | resume_hook → resume_hook_v3 | resumeHook → resumeHookV3 |
| Sett flytvariabler | PATCH /v2/flows/sessions/{id}/variables | PATCH /v3/flows/sessions/variables | update_session_variables → update_session_variables_v3 | updateSessionVariables → updateSessionVariablesV3 |
| List vedlegg | GET /v2/flows/sessions/{id}/attachments | GET /v3/flows/sessions/attachments | get_attachments → get_attachments_v3 | getAttachments → getAttachmentsV3 |
| Last opp vedlegg | POST /v2/flows/sessions/{id}/attachments | POST /v3/flows/sessions/attachments | upload_attachments → upload_attachments_v3 | uploadAttachments → uploadAttachmentsV3 |
| Slett vedlegg | DELETE /v2/flows/sessions/{id}/attachments/{file_id} | DELETE /v3/flows/sessions/attachments/{file_id} | delete_attachment → delete_attachment_v3 | deleteAttachment → deleteAttachmentV3 |
| Tilbakemelding på melding | POST /v2/flows/sessions/{id}/feedback | POST /v3/flows/sessions/feedback | create_message_feedback → create_message_feedback_v3 | createMessageFeedback → createMessageFeedbackV3 |
| Les en artefakt | GET /v2/flows/sessions/{id}/artefacts/{artefact_id} | GET /v3/flows/sessions/artefacts/{artefact_id} | get_artefact_content → get_artefact_content_v3 | getArtefactContent → getArtefactContentV3 |
| Søk mens du skriver (ny, ingen v2) | ingen | POST /v3/flows/sessions/search | invoke_search_v3 | invokeSearchV3 |
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
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)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:
breakPHP
$session = $flows->createFlowSession($workspaceId, $request);
$invocation = $flows->invokeFlowResponse($session->getSessionId(), $invokeRequest);
$events = $flows->pollFlowResponse($session->getSessionId(), $fromTimestamp);<?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.
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\"}"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"}'curl -X POST "https://api.flowhunt.io/v3/flows/sessions/invocation_response/$FROM_TIMESTAMP" \
-H "X-FH-Session-Id: $SESSION_ID"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_timestamper millisekunder siden epoken. Pollingen returnerer hendelsene dercreated_at_timestamper strengt større.- Start fra
created_ati invoke-svaret, som er en millisekundverdi sendt som en streng, så konverter den til et heltall. Bruk0for å få hele sesjonen. Ikke brukcreated_atfra opprettelsessvaret, som er en dato og et klokkeslett, ikke millisekunder. - Etter hver polling flytter du
from_timestamptil den nyeste hendelsenscreated_at_timestampminus 1 og hopper over hendelser der du allerede har settevent_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,humanellersystem), enaction_type(message,loading,tool_call,failed,hook_waiting_for_inputog andre) ogmetadata. Svareteksten ligger imetadata.messageiai-hendelsene av typenmessage.
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.
| v2 | v3 |
|---|---|
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 metode | Endepunkt | Hva du skal gjøre |
|---|---|---|
AgentGridsApi.get_agent_grid_preview | GET /v2/agent_grids/{agent_grid_id}/preview | Fjern kallet. |
CustomModelsApi.get_available_models | GET /v2/custom-models/available | Fjern kallet. |
FineTuningsApi.create_image_ft, delete_image_ft, search_image_fts, update_image_ft | /v2/photo_ai/images/... | Fjern kallene. |
WorkspacesApi.update_workspace_auto_recharge | PUT /v2/workspaces/{workspace_id}/auto-recharge | Fjern kallet. |
FlowBatchApi.export_csv | GET /v2/flows/{flow_id}/batch/{batch_run_id}/export-csv | Kall 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.