Migraciones de SDK

Migrar al SDK 4.0 y a la API de sesiones v3

Mueva el código de Python y PHP de las llamadas de sesión de flujo v2 a v3, que envía el id de sesión en una cabecera.

La API de sesiones v2 llega al fin de su vida útil el 30 de noviembre de 2026

El SDK 4.0.0 marca como obsoletas las llamadas de sesión de flujo v2, como create_flow_session, invoke_flow_response y poll_flow_response. Las rutas de sesión v2 llegan al fin de su vida útil el 30 de noviembre de 2026. Migre su código a las llamadas v3 de esta página antes de esa fecha.

La versión 4.0.0 de los SDK de Python y PHP de FlowHunt añade la API de sesión de flujo v3. Al pasarse a ella, los ids de sesión de chat dejan de aparecer en las URL, y la mayor parte del trabajo consiste en renombrar métodos. Esta página muestra qué ha cambiado, qué llamadas hay que renombrar y el código de antes y después.

Qué ha cambiado#

Las llamadas de sesión v3 llevan el id de sesión en la cabecera X-FH-Session-Id, nunca en la URL. Los cuerpos de petición y respuesta son los mismos que en v2. Las rutas de sesión v2 están obsoletas y llegan al fin de su vida útil el 30 de noviembre de 2026.

En v2, todas las llamadas de chat ponen el id de sesión en la ruta, por ejemplo /v2/flows/sessions/{session_id}/invoke. El id de sesión es la única credencial que tiene una sesión de chat anónima, y las URL acaban en los logs de acceso, los logs de los proxies, el historial del navegador y las cabeceras Referer. Una cabecera no.

Instalar 4.0.0#

Python

El paquete en PyPI es flowhunt.

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

PHP

El paquete en Packagist es flowhunt/flowhunt-php-sdk. Requiere PHP 8.1 o superior.

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

Migrar en cuatro pasos#

  1. Actualice el paquete

    Instale 4.0.0 como se indica arriba. Sus llamadas v2 actuales siguen funcionando después de la actualización, así que puede migrar una llamada cada vez. Termine antes del 30 de noviembre de 2026.

  2. Renombre cada llamada de sesión

    Añada _v3 al nombre del método de Python o V3 al de PHP. La correspondencia de métodos enumera todos los pares.

  3. Pase el id de sesión como argumento de cabecera

    El argumento del id de sesión ahora es x_fh_session_id. En Python, pásalo por nombre. En PHP, tres métodos lo reciben en segunda posición en lugar de la primera. Consulte cambió el orden de los argumentos en tres métodos.

  4. Revise los métodos eliminados

    Si llama a alguno de los métodos eliminados en 4.0.0, cambie a la alternativa o elimine la llamada.

Correspondencia de métodos#

Los métodos de Python están en flowhunt.FlowsApi, y los mismos métodos v3 también existen en flowhunt.V3Api. Los métodos de PHP están en FlowHunt\Api\FlowsApi.

QuéHTTP v2HTTP v3 (id de sesión en X-FH-Session-Id)Python 3.x → 4.0PHP 3.x → 4.0
Iniciar sesión de flujo (API key)POST /v2/flows/sessions/from_flow/createPOST /v3/flows/sessions/from_flow/createcreate_flow_session → create_flow_session_v3createFlowSession → createFlowSessionV3
Iniciar sesión de chatbot (anónima)POST /v2/flows/sessions/createPOST /v3/flows/sessions/createcreate_chatbot_session → create_chatbot_session_v3createChatbotSession → createChatbotSessionV3
Enviar un mensajePOST /v2/flows/sessions/{id}/invokePOST /v3/flows/sessions/invokeinvoke_flow_response → invoke_flow_response_v3invokeFlowResponse → invokeFlowResponseV3
Consultar eventos (polling)POST /v2/flows/sessions/{id}/invocation_response/{from_timestamp}POST /v3/flows/sessions/invocation_response/{from_timestamp}poll_flow_response → poll_flow_response_v3pollFlowResponse → pollFlowResponseV3
Cancelar una ejecuciónPOST /v2/flows/sessions/{id}/cancelPOST /v3/flows/sessions/cancelcancel_flow_session → cancel_flow_session_v3cancelFlowSession → cancelFlowSessionV3
Volver al ancla anteriorPOST /v2/flows/sessions/{id}/backPOST /v3/flows/sessions/backgo_back → go_back_v3goBack → goBackV3
Disparar un hook de chatPOST /v2/flows/sessions/{id}/hookPOST /v3/flows/sessions/hookfire_chat_hook → fire_chat_hook_v3fireChatHook → fireChatHookV3
Reanudar un hook en esperaPOST /v2/flows/sessions/{id}/resume-hookPOST /v3/flows/sessions/resume-hookresume_hook → resume_hook_v3resumeHook → resumeHookV3
Establecer variables de flujoPATCH /v2/flows/sessions/{id}/variablesPATCH /v3/flows/sessions/variablesupdate_session_variables → update_session_variables_v3updateSessionVariables → updateSessionVariablesV3
Listar adjuntosGET /v2/flows/sessions/{id}/attachmentsGET /v3/flows/sessions/attachmentsget_attachments → get_attachments_v3getAttachments → getAttachmentsV3
Subir un adjuntoPOST /v2/flows/sessions/{id}/attachmentsPOST /v3/flows/sessions/attachmentsupload_attachments → upload_attachments_v3uploadAttachments → uploadAttachmentsV3
Eliminar un adjuntoDELETE /v2/flows/sessions/{id}/attachments/{file_id}DELETE /v3/flows/sessions/attachments/{file_id}delete_attachment → delete_attachment_v3deleteAttachment → deleteAttachmentV3
Feedback de mensajePOST /v2/flows/sessions/{id}/feedbackPOST /v3/flows/sessions/feedbackcreate_message_feedback → create_message_feedback_v3createMessageFeedback → createMessageFeedbackV3
Leer un artefactoGET /v2/flows/sessions/{id}/artefacts/{artefact_id}GET /v3/flows/sessions/artefacts/{artefact_id}get_artefact_content → get_artefact_content_v3getArtefactContent → getArtefactContentV3
Buscar al escribir (nuevo, sin v2)ningunaPOST /v3/flows/sessions/searchinvoke_search_v3invokeSearchV3

Descargar un adjunto (GET /v2/flows/sessions/{id}/attachments/{file_id}) no tiene versión v3. Es una llamada del panel de control con sesión iniciada y no forma parte de esta migración.

Solo las dos llamadas de creación necesitan su API key. from_flow/create inicia una sesión para un flujo de su espacio de trabajo y requiere la clave. create es la sesión de chatbot anónima que utiliza el widget de chat embebido, así que no requiere clave. Ambas devuelven session_id y created_at con HTTP 201. Todas las demás llamadas de sesión v3 solo necesitan la cabecera X-FH-Session-Id.

Por ahora, suba los adjuntos por HTTP

En 4.0.0, upload_attachments_v3 y uploadAttachmentsV3 no pueden enviar un archivo. La API devuelve 422 “Expected UploadFile”, y el método de Python rechaza los bytes antes de enviar la petición. Los métodos de subida de 3.x tienen el mismo problema. Hasta que se corrija, envíe el archivo como multipart/form-data a POST /v3/flows/sessions/attachments con la cabecera X-FH-Session-Id. La pestaña HTTP de abajo muestra la llamada.

Antes y después#

Este ejemplo inicia una sesión para un flujo publicado, envía “Hello” e imprime la respuesta del flujo. Cada pestaña muestra primero el código de 3.x y después el código de 4.0 que ejecutamos contra https://api.flowhunt.io. El código de 4.0 lee la API key, el id del espacio de trabajo y el id del flujo de las variables de entorno FLOWHUNT_API_KEY, FLOWHUNT_WORKSPACE_ID y 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  # manténgalo en secreto, no lo registre nunca en logs

    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(); // manténgalo en secreto, no lo registre nunca en logs

$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);
    // Fíjese en el orden: primero la marca de tiempo, después el id de sesión.
    $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 llamada de creación envía la API key. Todas las llamadas posteriores envían el id de sesión en la cabecera X-FH-Session-Id.

Iniciar una sesión (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\"}"
Enviar un mensaje
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"}'
Consultar eventos (polling)
curl -X POST "https://api.flowhunt.io/v3/flows/sessions/invocation_response/$FROM_TIMESTAMP" \
  -H "X-FH-Session-Id: $SESSION_ID"
Subir un adjunto
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"

Antes, el id de sesión formaba parte de cada ruta, por ejemplo /v2/flows/sessions/$SESSION_ID/invoke. Una llamada v3 sin la cabecera devuelve 401.

Cómo funciona el polling#

  • from_timestamp son milisegundos desde la época. El polling devuelve los eventos cuyo created_at_timestamp es estrictamente mayor.
  • Empiece por el created_at de la respuesta de invocación, que es un valor en milisegundos enviado como cadena, así que conviértalo a entero. Use 0 para obtener la sesión completa. No use el created_at de la respuesta de creación, que es una fecha y hora, no milisegundos.
  • Después de cada polling, mueva from_timestamp al created_at_timestamp del evento más reciente menos 1 y omita los eventos cuyo event_id ya haya visto. Los eventos creados en el mismo milisegundo pueden llegar en pollings distintos. El widget de chat de FlowHunt hace polling de la misma forma.
  • Cada evento tiene un event_type (ai, human o system), un action_type (message, loading, tool_call, failed, hook_waiting_for_input y otros) y metadata. El texto de la respuesta está en metadata.message de los eventos message de tipo ai.

FlowHunt no envía un evento separado de “ejecución finalizada”. Cuando ejecutamos los ejemplos contra un flujo de un solo paso, el polling devolvió un evento loading de tipo system, después un message de tipo ai con la respuesta y nada más. Por eso los ejemplos se detienen en el primer polling que no trae eventos nuevos después de haber recibido una respuesta, y lanzan una excepción si reciben failed. Si su flujo envía varios mensajes o espera entrada con hook_waiting_for_input, defina su propia condición de parada.

Cambió el orden de los argumentos en tres métodos#

Reordene estas tres llamadas

Los métodos v3 colocan los parámetros de ruta antes que la cabecera del id de sesión. En PHP, y en Python cuando pasa los argumentos por posición, estas tres llamadas fallan con un error de tipo o envían valores incorrectos sin avisar, a menos que los reordene.

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, pase argumentos con nombre siempre, por ejemplo x_fh_session_id=session_id, y el orden deja de importar. Python 4.0 también comprueba los tipos de los argumentos, así que from_timestamp debe ser un int. Pasar la cadena "0" lanza un ValidationError de pydantic.

Otros cambios incompatibles en 4.0.0#

Estos métodos estaban en 3.19.1 y ya no existen en 4.0.0, porque los endpoints de la API que los respaldan se eliminaron o cambiaron. Los nombres de los métodos de PHP son la forma camelCase de los de Python, por ejemplo get_available_models pasa a ser getAvailableModels.

Método eliminadoEndpointQué hacer
AgentGridsApi.get_agent_grid_previewGET /v2/agent_grids/{agent_grid_id}/previewElimine la llamada.
CustomModelsApi.get_available_modelsGET /v2/custom-models/availableElimine la llamada.
FineTuningsApi.create_image_ft, delete_image_ft, search_image_fts, update_image_ft/v2/photo_ai/images/...Elimine las llamadas.
WorkspacesApi.update_workspace_auto_rechargePUT /v2/workspaces/{workspace_id}/auto-rechargeElimine la llamada.
FlowBatchApi.export_csvGET /v2/flows/{flow_id}/batch/{batch_run_id}/export-csvLlame a start_export_csv (POST, misma ruta) y después a get_export_csv_status (GET .../export-csv/{task_id}).

También se eliminaron los métodos del canal de Zendesk, la facturación de Shopify, Replicate y los webhooks de pingback de SERP. Son webhooks entrantes para los propios servidores de FlowHunt, no llamadas que haga su código.

Mantenga el id de sesión en secreto#

El id de sesión es una credencial

Cualquiera que tenga un id de sesión puede leer y continuar esa conversación. No lo registre en logs, no lo ponga en URL ni en cadenas de consulta y no lo envíe a herramientas de analítica. Trátelo como una contraseña de corta duración.

¿Y qué pasa con v2?#

Las rutas de sesión v2 están obsoletas desde el SDK 4.0.0 y llegan al fin de su vida útil el 30 de noviembre de 2026. Hasta entonces siguen funcionando y están marcadas como obsoletas en la referencia de la API. El SDK 4.0.0 todavía incluye los métodos v2. En Python, llamar a uno lanza un DeprecationWarning. En PHP, están marcados como @deprecated en el código, lo que su IDE o su análisis estático señalará.