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.
pip install --upgrade "flowhunt>=4,<5"PHP
El paquete en Packagist es flowhunt/flowhunt-php-sdk. Requiere PHP 8.1 o superior.
composer require flowhunt/flowhunt-php-sdk:^4.0Migrar en cuatro pasos#
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.
Renombre cada llamada de sesión
Añada
_v3al nombre del método de Python oV3al de PHP. La correspondencia de métodos enumera todos los pares.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.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 v2 | HTTP v3 (id de sesión en X-FH-Session-Id) | Python 3.x → 4.0 | PHP 3.x → 4.0 |
|---|---|---|---|---|
| Iniciar sesión de flujo (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 |
| Iniciar sesión de chatbot (anónima) | POST /v2/flows/sessions/create | POST /v3/flows/sessions/create | create_chatbot_session → create_chatbot_session_v3 | createChatbotSession → createChatbotSessionV3 |
| Enviar un mensaje | POST /v2/flows/sessions/{id}/invoke | POST /v3/flows/sessions/invoke | invoke_flow_response → invoke_flow_response_v3 | invokeFlowResponse → 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_v3 | pollFlowResponse → pollFlowResponseV3 |
| Cancelar una ejecución | POST /v2/flows/sessions/{id}/cancel | POST /v3/flows/sessions/cancel | cancel_flow_session → cancel_flow_session_v3 | cancelFlowSession → cancelFlowSessionV3 |
| Volver al ancla anterior | POST /v2/flows/sessions/{id}/back | POST /v3/flows/sessions/back | go_back → go_back_v3 | goBack → goBackV3 |
| Disparar un hook de chat | POST /v2/flows/sessions/{id}/hook | POST /v3/flows/sessions/hook | fire_chat_hook → fire_chat_hook_v3 | fireChatHook → fireChatHookV3 |
| Reanudar un hook en espera | POST /v2/flows/sessions/{id}/resume-hook | POST /v3/flows/sessions/resume-hook | resume_hook → resume_hook_v3 | resumeHook → resumeHookV3 |
| Establecer variables de flujo | PATCH /v2/flows/sessions/{id}/variables | PATCH /v3/flows/sessions/variables | update_session_variables → update_session_variables_v3 | updateSessionVariables → updateSessionVariablesV3 |
| Listar adjuntos | GET /v2/flows/sessions/{id}/attachments | GET /v3/flows/sessions/attachments | get_attachments → get_attachments_v3 | getAttachments → getAttachmentsV3 |
| Subir un adjunto | POST /v2/flows/sessions/{id}/attachments | POST /v3/flows/sessions/attachments | upload_attachments → upload_attachments_v3 | uploadAttachments → uploadAttachmentsV3 |
| Eliminar un adjunto | DELETE /v2/flows/sessions/{id}/attachments/{file_id} | DELETE /v3/flows/sessions/attachments/{file_id} | delete_attachment → delete_attachment_v3 | deleteAttachment → deleteAttachmentV3 |
| Feedback de mensaje | POST /v2/flows/sessions/{id}/feedback | POST /v3/flows/sessions/feedback | create_message_feedback → create_message_feedback_v3 | createMessageFeedback → createMessageFeedbackV3 |
| Leer un artefacto | GET /v2/flows/sessions/{id}/artefacts/{artefact_id} | GET /v3/flows/sessions/artefacts/{artefact_id} | get_artefact_content → get_artefact_content_v3 | getArtefactContent → getArtefactContentV3 |
| Buscar al escribir (nuevo, sin v2) | ninguna | POST /v3/flows/sessions/search | invoke_search_v3 | invokeSearchV3 |
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
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 # 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:
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(); // 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.
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"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_timestampson milisegundos desde la época. El polling devuelve los eventos cuyocreated_at_timestampes estrictamente mayor.- Empiece por el
created_atde la respuesta de invocación, que es un valor en milisegundos enviado como cadena, así que conviértalo a entero. Use0para obtener la sesión completa. No use elcreated_atde la respuesta de creación, que es una fecha y hora, no milisegundos. - Después de cada polling, mueva
from_timestampalcreated_at_timestampdel evento más reciente menos 1 y omita los eventos cuyoevent_idya 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,humanosystem), unaction_type(message,loading,tool_call,failed,hook_waiting_for_inputy otros) ymetadata. El texto de la respuesta está enmetadata.messagede los eventosmessagede tipoai.
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.
| 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) |
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 eliminado | Endpoint | Qué hacer |
|---|---|---|
AgentGridsApi.get_agent_grid_preview | GET /v2/agent_grids/{agent_grid_id}/preview | Elimine la llamada. |
CustomModelsApi.get_available_models | GET /v2/custom-models/available | Elimine 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_recharge | PUT /v2/workspaces/{workspace_id}/auto-recharge | Elimine la llamada. |
FlowBatchApi.export_csv | GET /v2/flows/{flow_id}/batch/{batch_run_id}/export-csv | Llame 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á.