Migrations des SDK

Migrer vers le SDK 4.0 et l'API de session v3

Faites passer le code Python et PHP des appels de session de flux v2 à la v3, qui envoie l’id de session dans un en-tête.

L'API de session v2 arrive en fin de vie le 30 novembre 2026

Le SDK 4.0.0 déprécie les appels de session de flux v2, comme create_flow_session, invoke_flow_response et poll_flow_response. Les routes de session v2 arrivent en fin de vie le 30 novembre 2026. Migrez votre code vers les appels v3 présentés sur cette page avant cette date.

La version 4.0.0 des SDK Python et PHP de FlowHunt ajoute l’API de session de flux v3. Y passer permet de garder vos id de session de chat hors des URL, et l’essentiel du travail consiste à renommer des méthodes. Cette page présente ce qui a changé, quels appels renommer, et le code avant et après.

Ce qui a changé#

Les appels de session v3 transmettent l’id de session dans l’en-tête X-FH-Session-Id, jamais dans l’URL. Les corps de requête et de réponse sont identiques à ceux de la v2. Les routes de session v2 sont dépréciées et arrivent en fin de vie le 30 novembre 2026.

En v2, chaque appel de chat place l’id de session dans le chemin, par exemple /v2/flows/sessions/{session_id}/invoke. L’id de session est le seul identifiant dont dispose une session de chat anonyme, et les URL finissent dans les journaux d’accès, les journaux de proxy, l’historique du navigateur et les en-têtes Referer. Un en-tête, non.

Installer la version 4.0.0#

Python

Le paquet sur PyPI est flowhunt.

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

PHP

Le paquet sur Packagist est flowhunt/flowhunt-php-sdk. Il nécessite PHP 8.1 ou une version plus récente.

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

Migrer en quatre étapes#

  1. Mettre à jour le paquet

    Installez la version 4.0.0 comme indiqué ci-dessus. Vos appels v2 existants continuent de fonctionner après la mise à jour, vous pouvez donc migrer un appel à la fois. Terminez avant le 30 novembre 2026.

  2. Renommer chaque appel de session

    Ajoutez _v3 au nom de la méthode Python ou V3 à celui de la méthode PHP. La correspondance des méthodes liste toutes les paires.

  3. Passer l’id de session comme argument d’en-tête

    L’argument d’id de session est désormais x_fh_session_id. En Python, passez-le par mot-clé. En PHP, trois méthodes le prennent en deuxième position au lieu de la première. Voir l’ordre des arguments modifié pour trois méthodes.

  4. Vérifier les méthodes supprimées

    Si vous appelez l’une des méthodes supprimées dans la 4.0.0, passez à la méthode de remplacement ou supprimez l’appel.

Correspondance des méthodes#

Les méthodes Python se trouvent sur flowhunt.FlowsApi, et les mêmes méthodes v3 existent aussi sur flowhunt.V3Api. Les méthodes PHP se trouvent sur FlowHunt\Api\FlowsApi.

ÉlémentHTTP v2HTTP v3 (id de session dans X-FH-Session-Id)Python 3.x → 4.0PHP 3.x → 4.0
Démarrer une session de flux (clé API)POST /v2/flows/sessions/from_flow/createPOST /v3/flows/sessions/from_flow/createcreate_flow_session → create_flow_session_v3createFlowSession → createFlowSessionV3
Démarrer une session de chatbot (anonyme)POST /v2/flows/sessions/createPOST /v3/flows/sessions/createcreate_chatbot_session → create_chatbot_session_v3createChatbotSession → createChatbotSessionV3
Envoyer un messagePOST /v2/flows/sessions/{id}/invokePOST /v3/flows/sessions/invokeinvoke_flow_response → invoke_flow_response_v3invokeFlowResponse → invokeFlowResponseV3
Interroger les événementsPOST /v2/flows/sessions/{id}/invocation_response/{from_timestamp}POST /v3/flows/sessions/invocation_response/{from_timestamp}poll_flow_response → poll_flow_response_v3pollFlowResponse → pollFlowResponseV3
Annuler une exécutionPOST /v2/flows/sessions/{id}/cancelPOST /v3/flows/sessions/cancelcancel_flow_session → cancel_flow_session_v3cancelFlowSession → cancelFlowSessionV3
Revenir à l’ancre précédentePOST /v2/flows/sessions/{id}/backPOST /v3/flows/sessions/backgo_back → go_back_v3goBack → goBackV3
Déclencher un hook de chatPOST /v2/flows/sessions/{id}/hookPOST /v3/flows/sessions/hookfire_chat_hook → fire_chat_hook_v3fireChatHook → fireChatHookV3
Reprendre un hook en attentePOST /v2/flows/sessions/{id}/resume-hookPOST /v3/flows/sessions/resume-hookresume_hook → resume_hook_v3resumeHook → resumeHookV3
Définir les variables du fluxPATCH /v2/flows/sessions/{id}/variablesPATCH /v3/flows/sessions/variablesupdate_session_variables → update_session_variables_v3updateSessionVariables → updateSessionVariablesV3
Lister les pièces jointesGET /v2/flows/sessions/{id}/attachmentsGET /v3/flows/sessions/attachmentsget_attachments → get_attachments_v3getAttachments → getAttachmentsV3
Envoyer une pièce jointePOST /v2/flows/sessions/{id}/attachmentsPOST /v3/flows/sessions/attachmentsupload_attachments → upload_attachments_v3uploadAttachments → uploadAttachmentsV3
Supprimer une pièce jointeDELETE /v2/flows/sessions/{id}/attachments/{file_id}DELETE /v3/flows/sessions/attachments/{file_id}delete_attachment → delete_attachment_v3deleteAttachment → deleteAttachmentV3
Avis sur un messagePOST /v2/flows/sessions/{id}/feedbackPOST /v3/flows/sessions/feedbackcreate_message_feedback → create_message_feedback_v3createMessageFeedback → createMessageFeedbackV3
Lire un artefactGET /v2/flows/sessions/{id}/artefacts/{artefact_id}GET /v3/flows/sessions/artefacts/{artefact_id}get_artefact_content → get_artefact_content_v3getArtefactContent → getArtefactContentV3
Recherche à la saisie (nouveau, pas de v2)aucunePOST /v3/flows/sessions/searchinvoke_search_v3invokeSearchV3

Le téléchargement d’une pièce jointe (GET /v2/flows/sessions/{id}/attachments/{file_id}) n’a pas de version v3. C’est un appel authentifié du tableau de bord et il ne fait pas partie de cette migration.

Seuls les deux appels de création demandent votre clé API. from_flow/create démarre une session pour un flux de votre espace de travail et exige la clé. create est la session de chatbot anonyme utilisée par le widget de chat intégré, elle ne prend donc pas de clé. Les deux renvoient session_id et created_at avec un code HTTP 201. Tous les autres appels de session v3 n’ont besoin que de l’en-tête X-FH-Session-Id.

Envoyez les pièces jointes en HTTP pour l'instant

Dans la 4.0.0, upload_attachments_v3 et uploadAttachmentsV3 ne peuvent pas envoyer de fichier. L’API renvoie 422 « Expected UploadFile » et la méthode Python rejette les octets avant même l’envoi de la requête. Les méthodes d’envoi de la 3.x ont le même problème. En attendant une correction, envoyez le fichier en multipart/form-data vers POST /v3/flows/sessions/attachments avec l’en-tête X-FH-Session-Id. L’onglet HTTP ci-dessous montre l’appel.

Avant et après#

Cet exemple démarre une session pour un flux publié, envoie « Hello » et affiche la réponse du flux. Chaque onglet montre d’abord le code 3.x, puis le code 4.0 que nous avons exécuté contre https://api.flowhunt.io. Le code 4.0 lit la clé API, l’id de l’espace de travail et l’id du flux dans les variables d’environnement FLOWHUNT_API_KEY, FLOWHUNT_WORKSPACE_ID et 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  # à garder secret, ne jamais le journaliser

    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(); // à garder secret, ne jamais le journaliser

$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);
    // Attention à l'ordre : d'abord l'horodatage, ensuite l'id de session.
    $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

Seul l’appel de création envoie la clé API. Chaque appel suivant envoie l’id de session dans l’en-tête X-FH-Session-Id.

Démarrer une session (clé API)
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\"}"
Envoyer un 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"}'
Interroger les événements
curl -X POST "https://api.flowhunt.io/v3/flows/sessions/invocation_response/$FROM_TIMESTAMP" \
  -H "X-FH-Session-Id: $SESSION_ID"
Envoyer une pièce jointe
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"

Auparavant, l’id de session faisait partie de chaque chemin, par exemple /v2/flows/sessions/$SESSION_ID/invoke. Un appel v3 sans l’en-tête renvoie 401.

Fonctionnement de l’interrogation#

  • from_timestamp est exprimé en millisecondes depuis l’époque Unix. L’interrogation renvoie les événements dont created_at_timestamp est strictement supérieur.
  • Partez du created_at de la réponse d’invocation, qui est une valeur en millisecondes envoyée sous forme de chaîne : convertissez-la en entier. Utilisez 0 pour obtenir toute la session. N’utilisez pas le created_at de la réponse de création, qui est une date et une heure, et non des millisecondes.
  • Après chaque interrogation, positionnez from_timestamp sur la valeur created_at_timestamp de l’événement le plus récent moins 1 et ignorez les événements dont vous avez déjà vu l’event_id. Des événements créés dans la même milliseconde peuvent arriver lors d’interrogations différentes. Le widget de chat FlowHunt interroge de la même manière.
  • Chaque événement possède un event_type (ai, human ou system), un action_type (message, loading, tool_call, failed, hook_waiting_for_input et d’autres) et des metadata. Le texte de la réponse se trouve dans metadata.message des événements ai de type message.

FlowHunt n’envoie pas d’événement distinct de type « exécution terminée ». Lorsque nous avons exécuté les exemples contre un flux à une seule étape, l’interrogation a renvoyé un événement system de type loading, puis un événement ai de type message contenant la réponse, et rien ensuite. C’est pourquoi les exemples s’arrêtent à la première interrogation qui n’apporte aucun nouvel événement après l’arrivée d’une réponse, et lèvent une exception sur failed. Si votre flux envoie plusieurs messages ou attend une saisie avec hook_waiting_for_input, définissez votre propre condition d’arrêt.

Ordre des arguments modifié pour trois méthodes#

Réordonnez ces trois appels

Les méthodes v3 placent les paramètres de chemin avant l’en-tête d’id de session. En PHP, et en Python lorsque vous passez les arguments par position, ces trois appels échouent avec une erreur de type ou envoient silencieusement de mauvaises valeurs si vous ne les réordonnez pas.

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)

En Python, passez des arguments par mot-clé partout, par exemple x_fh_session_id=session_id, et l’ordre n’a plus d’importance. La version 4.0 vérifie aussi les types d’arguments en Python : from_timestamp doit être un int. Passer la chaîne "0" déclenche une ValidationError de pydantic.

Autres changements incompatibles dans la 4.0.0#

Ces méthodes existaient en 3.19.1 et ont disparu en 4.0.0, car les points de terminaison d’API sur lesquels elles reposaient ont été supprimés ou modifiés. Les noms de méthodes PHP sont la forme camelCase des noms Python ; par exemple, get_available_models devient getAvailableModels.

Méthode suppriméePoint de terminaisonQue faire
AgentGridsApi.get_agent_grid_previewGET /v2/agent_grids/{agent_grid_id}/previewSupprimez l’appel.
CustomModelsApi.get_available_modelsGET /v2/custom-models/availableSupprimez l’appel.
FineTuningsApi.create_image_ft, delete_image_ft, search_image_fts, update_image_ft/v2/photo_ai/images/...Supprimez les appels.
WorkspacesApi.update_workspace_auto_rechargePUT /v2/workspaces/{workspace_id}/auto-rechargeSupprimez l’appel.
FlowBatchApi.export_csvGET /v2/flows/{flow_id}/batch/{batch_run_id}/export-csvAppelez start_export_csv (POST, même chemin), puis get_export_csv_status (GET .../export-csv/{task_id}).

Les méthodes pour les webhooks du canal Zendesk, de la facturation Shopify, de Replicate et du pingback SERP ont également été supprimées. Ce sont des webhooks entrants destinés aux propres serveurs de FlowHunt, pas des appels effectués par votre code.

Gardez l’id de session secret#

L'id de session est un identifiant d'authentification

Quiconque possède un id de session peut lire cette conversation et la poursuivre. Ne le journalisez pas, ne le placez pas dans des URL ou des chaînes de requête et ne l’envoyez pas à des outils d’analyse. Traitez-le comme un mot de passe à durée de vie courte.

Et la v2 ?#

Les routes de session v2 sont dépréciées depuis le SDK 4.0.0 et arrivent en fin de vie le 30 novembre 2026. D’ici là, elles continuent de fonctionner et sont signalées comme dépréciées dans la référence de l’API. Le SDK 4.0.0 inclut encore les méthodes v2. En Python, en appeler une lève un DeprecationWarning. En PHP, elles sont marquées @deprecated dans le code, ce que votre IDE ou votre analyse statique signalera.