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.

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

PHP

Het pakket op Packagist is flowhunt/flowhunt-php-sdk. Het vereist PHP 8.1 of nieuwer.

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

Migreren in vier stappen#

  1. 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.

  2. Hernoem elke sessieaanroep

    Voeg _v3 toe aan de Python-methodenaam of V3 aan de PHP-naam. De methodemapping geeft elk paar weer.

  3. 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.

  4. 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.

Watv2 HTTPv3 HTTP (sessie-id in X-FH-Session-Id)Python 3.x → 4.0PHP 3.x → 4.0
Flow-sessie starten (API-key)POST /v2/flows/sessions/from_flow/createPOST /v3/flows/sessions/from_flow/createcreate_flow_session → create_flow_session_v3createFlowSession → createFlowSessionV3
Chatbot-sessie starten (anoniem)POST /v2/flows/sessions/createPOST /v3/flows/sessions/createcreate_chatbot_session → create_chatbot_session_v3createChatbotSession → createChatbotSessionV3
Een bericht versturenPOST /v2/flows/sessions/{id}/invokePOST /v3/flows/sessions/invokeinvoke_flow_response → invoke_flow_response_v3invokeFlowResponse → invokeFlowResponseV3
Op events pollenPOST /v2/flows/sessions/{id}/invocation_response/{from_timestamp}POST /v3/flows/sessions/invocation_response/{from_timestamp}poll_flow_response → poll_flow_response_v3pollFlowResponse → pollFlowResponseV3
Een run annulerenPOST /v2/flows/sessions/{id}/cancelPOST /v3/flows/sessions/cancelcancel_flow_session → cancel_flow_session_v3cancelFlowSession → cancelFlowSessionV3
Terug naar de vorige anchorPOST /v2/flows/sessions/{id}/backPOST /v3/flows/sessions/backgo_back → go_back_v3goBack → goBackV3
Een chat-hook afvurenPOST /v2/flows/sessions/{id}/hookPOST /v3/flows/sessions/hookfire_chat_hook → fire_chat_hook_v3fireChatHook → fireChatHookV3
Een wachtende hook hervattenPOST /v2/flows/sessions/{id}/resume-hookPOST /v3/flows/sessions/resume-hookresume_hook → resume_hook_v3resumeHook → resumeHookV3
Flowvariabelen instellenPATCH /v2/flows/sessions/{id}/variablesPATCH /v3/flows/sessions/variablesupdate_session_variables → update_session_variables_v3updateSessionVariables → updateSessionVariablesV3
Bijlagen weergevenGET /v2/flows/sessions/{id}/attachmentsGET /v3/flows/sessions/attachmentsget_attachments → get_attachments_v3getAttachments → getAttachmentsV3
Bijlage uploadenPOST /v2/flows/sessions/{id}/attachmentsPOST /v3/flows/sessions/attachmentsupload_attachments → upload_attachments_v3uploadAttachments → uploadAttachmentsV3
Bijlage verwijderenDELETE /v2/flows/sessions/{id}/attachments/{file_id}DELETE /v3/flows/sessions/attachments/{file_id}delete_attachment → delete_attachment_v3deleteAttachment → deleteAttachmentV3
BerichtfeedbackPOST /v2/flows/sessions/{id}/feedbackPOST /v3/flows/sessions/feedbackcreate_message_feedback → create_message_feedback_v3createMessageFeedback → createMessageFeedbackV3
Een artefact lezenGET /v2/flows/sessions/{id}/artefacts/{artefact_id}GET /v3/flows/sessions/artefacts/{artefact_id}get_artefact_content → get_artefact_content_v3getArtefactContent → getArtefactContentV3
Zoeken op type (nieuw, geen v2)geenPOST /v3/flows/sessions/searchinvoke_search_v3invokeSearchV3

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

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  # 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:
            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(); // 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.

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"

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_timestamp is het aantal milliseconden sinds de epoch. De poll retourneert de events waarvan created_at_timestamp strikt groter is.
  • Begin bij de created_at van het invoke-response. Dat is een millisecondenwaarde die als string wordt verstuurd, dus converteer die naar een integer. Gebruik 0 om de hele sessie op te halen. Gebruik niet de created_at van het create-response; dat is een datum en tijd, geen milliseconden.
  • Na elke poll zet je from_timestamp op de created_at_timestamp van het nieuwste event min 1 en sla je events over waarvan je de event_id al 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, human of system), een action_type (message, loading, tool_call, failed, hook_waiting_for_input en andere) en metadata. De antwoordtekst staat in metadata.message van de ai-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.

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)

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 methodeEndpointWat te doen
AgentGridsApi.get_agent_grid_previewGET /v2/agent_grids/{agent_grid_id}/previewVerwijder de aanroep.
CustomModelsApi.get_available_modelsGET /v2/custom-models/availableVerwijder 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_rechargePUT /v2/workspaces/{workspace_id}/auto-rechargeVerwijder de aanroep.
FlowBatchApi.export_csvGET /v2/flows/{flow_id}/batch/{batch_run_id}/export-csvRoep 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.