SDK-migraties
Migreer naar SDK 4.0 en de v3-sessie-API
Verplaats Python- en PHP-code van de v2 flow-sessieaanroepen naar v3, dat de sessie-id in een header verstuurt.
De v2-sessie-API bereikt end of life op 30 november 2026
SDK 4.0.0 markeert de v2 flow-sessieaanroepen, zoals create_flow_session, invoke_flow_response en poll_flow_response, als deprecated. De v2-sessieroutes bereiken end of life op 30 november 2026. Verplaats je code vóór die tijd naar de v3-aanroepen op deze pagina.
Versie 4.0.0 van de FlowHunt Python- en PHP-SDK’s voegt de v3 flow-sessie-API toe. Als je daarop overstapt, blijven je chat-sessie-id’s uit URL’s, en het meeste werk is methoden hernoemen. Deze pagina laat zien wat er is veranderd, welke aanroepen je moet hernoemen, en de code voor en na.
Wat is er veranderd#
v3-sessieaanroepen nemen de sessie-id mee in de header X-FH-Session-Id, nooit in de URL. De request- en response-bodies zijn hetzelfde als in v2. De v2-sessieroutes zijn deprecated en bereiken end of life op 30 november 2026.
In v2 zet elke chat-aanroep de sessie-id in het pad, bijvoorbeeld /v2/flows/sessions/{session_id}/invoke. De sessie-id is de enige credential die een anonieme chatsessie heeft, en URL’s belanden in access logs, proxylogs, browsergeschiedenis en Referer-headers. Een header niet.
Installeer 4.0.0#
Python
Het pakket op PyPI is flowhunt.
pip install --upgrade "flowhunt>=4,<5"PHP
Het pakket op Packagist is flowhunt/flowhunt-php-sdk. Het vereist PHP 8.1 of nieuwer.
composer require flowhunt/flowhunt-php-sdk:^4.0Migreren in vier stappen#
Upgrade het pakket
Installeer 4.0.0 zoals hierboven beschreven. Je bestaande v2-aanroepen blijven na de upgrade werken, dus je kunt één aanroep per keer verplaatsen. Rond alles af vóór 30 november 2026.
Hernoem elke sessieaanroep
Voeg
_v3toe aan de Python-methodenaam ofV3aan de PHP-naam. De methodemapping geeft elk paar weer.Geef de sessie-id door als header-argument
Het argument voor de sessie-id heet nu
x_fh_session_id. Geef het in Python door als keyword-argument. In PHP nemen drie methoden het als tweede argument in plaats van als eerste. Zie argumentvolgorde gewijzigd voor drie methoden.Controleer de verwijderde methoden
Als je een van de methoden die in 4.0.0 zijn verwijderd aanroept, schakel dan over op de vervanger of verwijder de aanroep.
Methodemapping#
Python-methoden staan op flowhunt.FlowsApi, en dezelfde v3-methoden bestaan ook op flowhunt.V3Api. PHP-methoden staan op FlowHunt\Api\FlowsApi.
| Wat | v2 HTTP | v3 HTTP (sessie-id in X-FH-Session-Id) | Python 3.x → 4.0 | PHP 3.x → 4.0 |
|---|---|---|---|---|
| Flow-sessie starten (API-key) | POST /v2/flows/sessions/from_flow/create | POST /v3/flows/sessions/from_flow/create | create_flow_session → create_flow_session_v3 | createFlowSession → createFlowSessionV3 |
| Chatbot-sessie starten (anoniem) | POST /v2/flows/sessions/create | POST /v3/flows/sessions/create | create_chatbot_session → create_chatbot_session_v3 | createChatbotSession → createChatbotSessionV3 |
| Een bericht versturen | POST /v2/flows/sessions/{id}/invoke | POST /v3/flows/sessions/invoke | invoke_flow_response → invoke_flow_response_v3 | invokeFlowResponse → invokeFlowResponseV3 |
| Op events pollen | 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 |
| Een run annuleren | POST /v2/flows/sessions/{id}/cancel | POST /v3/flows/sessions/cancel | cancel_flow_session → cancel_flow_session_v3 | cancelFlowSession → cancelFlowSessionV3 |
| Terug naar de vorige anchor | POST /v2/flows/sessions/{id}/back | POST /v3/flows/sessions/back | go_back → go_back_v3 | goBack → goBackV3 |
| Een chat-hook afvuren | POST /v2/flows/sessions/{id}/hook | POST /v3/flows/sessions/hook | fire_chat_hook → fire_chat_hook_v3 | fireChatHook → fireChatHookV3 |
| Een wachtende hook hervatten | POST /v2/flows/sessions/{id}/resume-hook | POST /v3/flows/sessions/resume-hook | resume_hook → resume_hook_v3 | resumeHook → resumeHookV3 |
| Flowvariabelen instellen | PATCH /v2/flows/sessions/{id}/variables | PATCH /v3/flows/sessions/variables | update_session_variables → update_session_variables_v3 | updateSessionVariables → updateSessionVariablesV3 |
| Bijlagen weergeven | GET /v2/flows/sessions/{id}/attachments | GET /v3/flows/sessions/attachments | get_attachments → get_attachments_v3 | getAttachments → getAttachmentsV3 |
| Bijlage uploaden | POST /v2/flows/sessions/{id}/attachments | POST /v3/flows/sessions/attachments | upload_attachments → upload_attachments_v3 | uploadAttachments → uploadAttachmentsV3 |
| Bijlage verwijderen | DELETE /v2/flows/sessions/{id}/attachments/{file_id} | DELETE /v3/flows/sessions/attachments/{file_id} | delete_attachment → delete_attachment_v3 | deleteAttachment → deleteAttachmentV3 |
| Berichtfeedback | POST /v2/flows/sessions/{id}/feedback | POST /v3/flows/sessions/feedback | create_message_feedback → create_message_feedback_v3 | createMessageFeedback → createMessageFeedbackV3 |
| Een artefact lezen | GET /v2/flows/sessions/{id}/artefacts/{artefact_id} | GET /v3/flows/sessions/artefacts/{artefact_id} | get_artefact_content → get_artefact_content_v3 | getArtefactContent → getArtefactContentV3 |
| Zoeken op type (nieuw, geen v2) | geen | POST /v3/flows/sessions/search | invoke_search_v3 | invokeSearchV3 |
Het downloaden van een bijlage (GET /v2/flows/sessions/{id}/attachments/{file_id}) heeft geen v3-versie. Het is een dashboardaanroep waarvoor je bent ingelogd en maakt geen deel uit van deze migratie.
Alleen de twee create-aanroepen hebben je API-key nodig. from_flow/create start een sessie voor een flow in je workspace en vereist de key. create is de anonieme chatbotsessie die de embedded chatwidget gebruikt, dus die heeft geen key nodig. Beide retourneren session_id en created_at met HTTP 201. Elke andere v3-sessieaanroep heeft alleen de header X-FH-Session-Id nodig.
Upload bijlagen voorlopig via HTTP
In 4.0.0 kunnen upload_attachments_v3 en uploadAttachmentsV3 geen bestand versturen. De API retourneert 422 “Expected UploadFile” en de Python-methode weigert bytes voordat het request wordt verstuurd. De uploadmethoden van 3.x hebben hetzelfde probleem. Totdat dit is opgelost, stuur je het bestand als multipart/form-data naar POST /v3/flows/sessions/attachments met de header X-FH-Session-Id. Het HTTP-tabblad hieronder toont de aanroep.
Voor en na#
Dit voorbeeld start een sessie voor een gepubliceerde flow, verstuurt “Hello” en print het antwoord van de flow. Elk tabblad toont eerst de 3.x-code en daarna de 4.0-code die we tegen https://api.flowhunt.io hebben uitgevoerd. De 4.0-code leest de API-key, workspace-id en flow-id uit de omgevingsvariabelen FLOWHUNT_API_KEY, FLOWHUNT_WORKSPACE_ID en 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 # houd geheim, log het nooit
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(); // houd geheim, log het nooit
$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);
// Let op de volgorde: eerst de timestamp, dan de sessie-id.
$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
Alleen de create-aanroep verstuurt de API-key. Elke aanroep daarna verstuurt de sessie-id in de header X-FH-Session-Id.
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"Voorheen maakte de sessie-id deel uit van elk pad, bijvoorbeeld /v2/flows/sessions/$SESSION_ID/invoke. Een v3-aanroep zonder de header retourneert 401.
Hoe pollen werkt#
from_timestampis het aantal milliseconden sinds de epoch. De poll retourneert de events waarvancreated_at_timestampstrikt groter is.- Begin bij de
created_atvan het invoke-response. Dat is een millisecondenwaarde die als string wordt verstuurd, dus converteer die naar een integer. Gebruik0om de hele sessie op te halen. Gebruik niet decreated_atvan het create-response; dat is een datum en tijd, geen milliseconden. - Na elke poll zet je
from_timestampop decreated_at_timestampvan het nieuwste event min 1 en sla je events over waarvan je deevent_idal hebt gezien. Events die in dezelfde milliseconde zijn aangemaakt, kunnen in verschillende polls binnenkomen. De FlowHunt-chatwidget pollt op dezelfde manier. - Elk event heeft een
event_type(ai,humanofsystem), eenaction_type(message,loading,tool_call,failed,hook_waiting_for_inputen andere) enmetadata. De antwoordtekst staat inmetadata.messagevan deai-message-events.
FlowHunt verstuurt geen apart “run finished”-event. Toen we de voorbeelden tegen een flow met één stap uitvoerden, retourneerde de poll een system-loading-event, daarna één ai-message met het antwoord, en daarna niets meer. Daarom stoppen de voorbeelden bij de eerste poll die geen nieuwe events oplevert nadat een antwoord is binnengekomen, en gooien ze een fout bij failed. Als je flow meerdere berichten verstuurt of op input wacht met hook_waiting_for_input, bepaal dan je eigen stopconditie.
Argumentvolgorde gewijzigd voor drie methoden#
Herschik deze drie aanroepen
De v3-methoden zetten padparameters vóór de sessie-id-header. In PHP, en in Python wanneer je argumenten op positie doorgeeft, mislukken deze drie aanroepen met een typefout of versturen ze stilletjes de verkeerde waarden, tenzij je ze herschikt.
| 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) |
Geef in Python overal keyword-argumenten door, bijvoorbeeld x_fh_session_id=session_id, dan maakt de volgorde niet meer uit. Python 4.0 controleert ook argumenttypes, dus from_timestamp moet een int zijn. De string "0" doorgeven levert een pydantic ValidationError op.
Overige breaking changes in 4.0.0#
Deze methoden zaten in 3.19.1 en zijn verdwenen in 4.0.0, omdat de API-endpoints erachter zijn verwijderd of gewijzigd. PHP-methodenamen zijn de camelCase-vorm van de Python-namen, bijvoorbeeld get_available_models wordt getAvailableModels.
| Verwijderde methode | Endpoint | Wat te doen |
|---|---|---|
AgentGridsApi.get_agent_grid_preview | GET /v2/agent_grids/{agent_grid_id}/preview | Verwijder de aanroep. |
CustomModelsApi.get_available_models | GET /v2/custom-models/available | Verwijder de aanroep. |
FineTuningsApi.create_image_ft, delete_image_ft, search_image_fts, update_image_ft | /v2/photo_ai/images/... | Verwijder de aanroepen. |
WorkspacesApi.update_workspace_auto_recharge | PUT /v2/workspaces/{workspace_id}/auto-recharge | Verwijder de aanroep. |
FlowBatchApi.export_csv | GET /v2/flows/{flow_id}/batch/{batch_run_id}/export-csv | Roep start_export_csv aan (POST, zelfde pad) en daarna get_export_csv_status (GET .../export-csv/{task_id}). |
De methoden voor het Zendesk-kanaal, Shopify-billing, Replicate en SERP-pingback-webhooks zijn ook verwijderd. Dat zijn inkomende webhooks voor de servers van FlowHunt zelf, geen aanroepen die jouw code doet.
Houd de sessie-id geheim#
De sessie-id is een credential
Iedereen met een sessie-id kan dat gesprek lezen en voortzetten. Log hem niet, zet hem niet in URL’s of querystrings en stuur hem niet naar analytics. Behandel hem als een kortlevend wachtwoord.
En v2?#
De v2-sessieroutes zijn deprecated sinds SDK 4.0.0 en bereiken end of life op 30 november 2026. Tot dan blijven ze werken, en ze zijn als deprecated gemarkeerd in de API-referentie. SDK 4.0.0 bevat de v2-methoden nog steeds. In Python levert een aanroep een DeprecationWarning op. In PHP zijn ze in de code gemarkeerd met @deprecated, wat je IDE of statische analyse zal signaleren.