Migrazioni degli SDK

Migra al SDK 4.0 e all'API di sessione v3

Sposta il codice Python e PHP dalle chiamate di sessione di flusso v2 alle v3, che inviano l’id di sessione in un header.

L'API di sessione v2 termina il 30 novembre 2026

L’SDK 4.0.0 depreca le chiamate di sessione di flusso v2, come create_flow_session, invoke_flow_response e poll_flow_response. Le rotte di sessione v2 terminano il loro ciclo di vita il 30 novembre 2026. Sposta il tuo codice sulle chiamate v3 descritte in questa pagina prima di quella data.

La versione 4.0.0 degli SDK FlowHunt per Python e PHP introduce l’API di sessione di flusso v3. Passare a questa versione tiene gli id di sessione della chat fuori dagli URL, e la maggior parte del lavoro consiste nel rinominare i metodi. Questa pagina mostra cosa è cambiato, quali chiamate rinominare e il codice prima e dopo.

Cosa è cambiato#

Le chiamate di sessione v3 accettano l’id di sessione nell’header X-FH-Session-Id, mai nell’URL. I corpi delle richieste e delle risposte sono gli stessi della v2. Le rotte di sessione v2 sono deprecate e terminano il loro ciclo di vita il 30 novembre 2026.

In v2, ogni chiamata di chat mette l’id di sessione nel percorso, per esempio /v2/flows/sessions/{session_id}/invoke. L’id di sessione è l’unica credenziale che ha una sessione di chat anonima, e gli URL finiscono nei log di accesso, nei log dei proxy, nella cronologia del browser e negli header Referer. Un header no.

Installa la 4.0.0#

Python

Il pacchetto su PyPI è flowhunt.

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

PHP

Il pacchetto su Packagist è flowhunt/flowhunt-php-sdk. Richiede PHP 8.1 o successivo.

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

Migrazione in quattro passaggi#

  1. Aggiorna il pacchetto

    Installa la 4.0.0 come mostrato sopra. Le tue chiamate v2 esistenti continuano a funzionare dopo l’aggiornamento, quindi puoi migrare una chiamata alla volta. Concludi prima del 30 novembre 2026.

  2. Rinomina ogni chiamata di sessione

    Aggiungi _v3 al nome del metodo Python o V3 a quello PHP. La mappatura dei metodi elenca tutte le coppie.

  3. Passa l’id di sessione come argomento dell’header

    L’argomento dell’id di sessione ora è x_fh_session_id. In Python passalo per keyword. In PHP tre metodi lo ricevono come secondo argomento invece che come primo. Vedi ordine degli argomenti cambiato per tre metodi.

  4. Controlla i metodi rimossi

    Se chiami uno dei metodi rimossi nella 4.0.0, passa al sostituto o rimuovi la chiamata.

Mappatura dei metodi#

I metodi Python sono su flowhunt.FlowsApi, e gli stessi metodi v3 esistono anche su flowhunt.V3Api. I metodi PHP sono su FlowHunt\Api\FlowsApi.

CosaHTTP v2HTTP v3 (id di sessione in X-FH-Session-Id)Python 3.x → 4.0PHP 3.x → 4.0
Avvia sessione di flusso (chiave API)POST /v2/flows/sessions/from_flow/createPOST /v3/flows/sessions/from_flow/createcreate_flow_session → create_flow_session_v3createFlowSession → createFlowSessionV3
Avvia sessione chatbot (anonima)POST /v2/flows/sessions/createPOST /v3/flows/sessions/createcreate_chatbot_session → create_chatbot_session_v3createChatbotSession → createChatbotSessionV3
Invia un messaggioPOST /v2/flows/sessions/{id}/invokePOST /v3/flows/sessions/invokeinvoke_flow_response → invoke_flow_response_v3invokeFlowResponse → invokeFlowResponseV3
Esegui il polling degli eventiPOST /v2/flows/sessions/{id}/invocation_response/{from_timestamp}POST /v3/flows/sessions/invocation_response/{from_timestamp}poll_flow_response → poll_flow_response_v3pollFlowResponse → pollFlowResponseV3
Annulla un’esecuzionePOST /v2/flows/sessions/{id}/cancelPOST /v3/flows/sessions/cancelcancel_flow_session → cancel_flow_session_v3cancelFlowSession → cancelFlowSessionV3
Torna all’ancora precedentePOST /v2/flows/sessions/{id}/backPOST /v3/flows/sessions/backgo_back → go_back_v3goBack → goBackV3
Attiva un hook di chatPOST /v2/flows/sessions/{id}/hookPOST /v3/flows/sessions/hookfire_chat_hook → fire_chat_hook_v3fireChatHook → fireChatHookV3
Riprendi un hook in attesaPOST /v2/flows/sessions/{id}/resume-hookPOST /v3/flows/sessions/resume-hookresume_hook → resume_hook_v3resumeHook → resumeHookV3
Imposta le variabili del flussoPATCH /v2/flows/sessions/{id}/variablesPATCH /v3/flows/sessions/variablesupdate_session_variables → update_session_variables_v3updateSessionVariables → updateSessionVariablesV3
Elenca gli allegatiGET /v2/flows/sessions/{id}/attachmentsGET /v3/flows/sessions/attachmentsget_attachments → get_attachments_v3getAttachments → getAttachmentsV3
Carica un allegatoPOST /v2/flows/sessions/{id}/attachmentsPOST /v3/flows/sessions/attachmentsupload_attachments → upload_attachments_v3uploadAttachments → uploadAttachmentsV3
Elimina un allegatoDELETE /v2/flows/sessions/{id}/attachments/{file_id}DELETE /v3/flows/sessions/attachments/{file_id}delete_attachment → delete_attachment_v3deleteAttachment → deleteAttachmentV3
Feedback sul messaggioPOST /v2/flows/sessions/{id}/feedbackPOST /v3/flows/sessions/feedbackcreate_message_feedback → create_message_feedback_v3createMessageFeedback → createMessageFeedbackV3
Leggi un artefattoGET /v2/flows/sessions/{id}/artefacts/{artefact_id}GET /v3/flows/sessions/artefacts/{artefact_id}get_artefact_content → get_artefact_content_v3getArtefactContent → getArtefactContentV3
Ricerca durante la digitazione (nuova, senza v2)nessunaPOST /v3/flows/sessions/searchinvoke_search_v3invokeSearchV3

Il download di un allegato (GET /v2/flows/sessions/{id}/attachments/{file_id}) non ha una versione v3. È una chiamata della dashboard autenticata e non fa parte di questa migrazione.

Solo le due chiamate di creazione richiedono la tua chiave API. from_flow/create avvia una sessione per un flusso nel tuo workspace e richiede la chiave. create è la sessione chatbot anonima usata dal widget di chat incorporato, quindi non richiede chiave. Entrambe restituiscono session_id e created_at con HTTP 201. Tutte le altre chiamate di sessione v3 richiedono solo l’header X-FH-Session-Id.

Per ora carica gli allegati via HTTP

Nella 4.0.0, upload_attachments_v3 e uploadAttachmentsV3 non riescono a inviare un file. L’API restituisce 422 “Expected UploadFile”, e il metodo Python rifiuta i byte prima che la richiesta venga inviata. I metodi di upload della 3.x hanno lo stesso problema. Finché non viene corretto, invia il file come multipart/form-data a POST /v3/flows/sessions/attachments con l’header X-FH-Session-Id. La scheda HTTP qui sotto mostra la chiamata.

Prima e dopo#

Questo esempio avvia una sessione per un flusso pubblicato, invia “Hello” e stampa la risposta del flusso. Ogni scheda mostra prima il codice 3.x, poi il codice 4.0 che abbiamo eseguito su https://api.flowhunt.io. Il codice 4.0 legge la chiave API, l’id del workspace e l’id del flusso dalle variabili d’ambiente FLOWHUNT_API_KEY, FLOWHUNT_WORKSPACE_ID e 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

Solo la chiamata di creazione invia la chiave API. Ogni chiamata successiva invia l’id di sessione nell’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"

Prima, l’id di sessione faceva parte di ogni percorso, per esempio /v2/flows/sessions/$SESSION_ID/invoke. Una chiamata v3 senza l’header restituisce 401.

Come funziona il polling#

  • from_timestamp è in millisecondi dall’epoca. Il polling restituisce gli eventi il cui created_at_timestamp è strettamente maggiore.
  • Parti dal created_at della risposta di invoke, che è un valore in millisecondi inviato come stringa, quindi convertilo in un intero. Usa 0 per ottenere l’intera sessione. Non usare il created_at della risposta di creazione, che è una data e un’ora, non millisecondi.
  • Dopo ogni polling, sposta from_timestamp al created_at_timestamp dell’evento più recente meno 1 e ignora gli eventi il cui event_id hai già visto. Gli eventi creati nello stesso millisecondo possono arrivare in polling diversi. Il widget di chat FlowHunt esegue il polling allo stesso modo.
  • Ogni evento ha un event_type (ai, human o system), un action_type (message, loading, tool_call, failed, hook_waiting_for_input e altri) e metadata. Il testo della risposta è in metadata.message degli eventi message di tipo ai.

FlowHunt non invia un evento separato di “esecuzione terminata”. Quando abbiamo eseguito gli esempi su un flusso a un solo step, il polling ha restituito un evento loading di tipo system, poi un message di tipo ai con la risposta, e nulla dopo. Per questo gli esempi si fermano al primo polling che non porta nuovi eventi dopo l’arrivo di una risposta, e sollevano un errore su failed. Se il tuo flusso invia più messaggi o attende input con hook_waiting_for_input, decidi tu la condizione di arresto.

Ordine degli argomenti cambiato per tre metodi#

Riordina queste tre chiamate

I metodi v3 mettono i parametri del percorso prima dell’header con l’id di sessione. In PHP, e in Python quando passi gli argomenti per posizione, queste tre chiamate falliscono con un errore di tipo o inviano silenziosamente valori sbagliati se non le riordini.

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)

In Python, passa gli argomenti per keyword ovunque, per esempio x_fh_session_id=session_id, e l’ordine non conta più. Python 4.0 controlla anche i tipi degli argomenti, quindi from_timestamp deve essere un int. Passare la stringa "0" solleva un ValidationError di pydantic.

Altre modifiche incompatibili nella 4.0.0#

Questi metodi erano nella 3.19.1 e non esistono più nella 4.0.0, perché gli endpoint API che li supportavano sono stati rimossi o modificati. I nomi dei metodi PHP sono la forma camelCase di quelli Python, per esempio get_available_models diventa getAvailableModels.

Metodo rimossoEndpointCosa fare
AgentGridsApi.get_agent_grid_previewGET /v2/agent_grids/{agent_grid_id}/previewRimuovi la chiamata.
CustomModelsApi.get_available_modelsGET /v2/custom-models/availableRimuovi la chiamata.
FineTuningsApi.create_image_ft, delete_image_ft, search_image_fts, update_image_ft/v2/photo_ai/images/...Rimuovi le chiamate.
WorkspacesApi.update_workspace_auto_rechargePUT /v2/workspaces/{workspace_id}/auto-rechargeRimuovi la chiamata.
FlowBatchApi.export_csvGET /v2/flows/{flow_id}/batch/{batch_run_id}/export-csvChiama start_export_csv (POST, stesso percorso), poi get_export_csv_status (GET .../export-csv/{task_id}).

Sono stati rimossi anche i metodi per il canale Zendesk, la fatturazione Shopify, Replicate e i webhook pingback SERP. Si tratta di webhook in ingresso per i server di FlowHunt, non di chiamate che fa il tuo codice.

Mantieni segreto l’id di sessione#

L'id di sessione è una credenziale

Chiunque abbia un id di sessione può leggere e continuare quella conversazione. Non registrarlo nei log, non inserirlo in URL o stringhe di query e non inviarlo agli strumenti di analytics. Trattalo come una password di breve durata.

E la v2?#

Le rotte di sessione v2 sono deprecate a partire dall’SDK 4.0.0 e terminano il loro ciclo di vita il 30 novembre 2026. Fino a quella data continuano a funzionare, e sono contrassegnate come deprecate nella documentazione API. L’SDK 4.0.0 include ancora i metodi v2. In Python, chiamarne uno solleva un DeprecationWarning. In PHP, sono contrassegnati con @deprecated nel codice, cosa che il tuo IDE o l’analisi statica segnalerà.