Migrações de SDK
Migrar para o SDK 4.0 e a API de sessão v3
Migre o código Python e PHP das chamadas de sessão de fluxo v2 para as v3, que enviam o id da sessão em um cabeçalho.
A API de sessão v2 chega ao fim do ciclo de vida em 30 de novembro de 2026
O SDK 4.0.0 descontinua as chamadas de sessão de fluxo v2, como create_flow_session, invoke_flow_response e poll_flow_response. As rotas de sessão v2 chegam ao fim do ciclo de vida em 30 de novembro de 2026. Migre seu código para as chamadas v3 desta página antes disso.
A versão 4.0.0 dos SDKs Python e PHP do FlowHunt adiciona a API de sessão de fluxo v3. Migrar para ela mantém os ids das suas sessões de chat fora das URLs, e a maior parte do trabalho é renomear métodos. Esta página mostra o que mudou, quais chamadas renomear e o código antes e depois.
O que mudou#
As chamadas de sessão v3 recebem o id da sessão no cabeçalho X-FH-Session-Id, nunca na URL. Os corpos de requisição e resposta são os mesmos da v2. As rotas de sessão v2 estão descontinuadas e chegam ao fim do ciclo de vida em 30 de novembro de 2026.
Na v2, toda chamada de chat coloca o id da sessão no caminho, por exemplo /v2/flows/sessions/{session_id}/invoke. O id da sessão é a única credencial que uma sessão de chat anônima tem, e as URLs acabam em logs de acesso, logs de proxy, histórico do navegador e cabeçalhos Referer. Um cabeçalho não acaba.
Instalar a versão 4.0.0#
Python
O pacote no PyPI é flowhunt.
pip install --upgrade "flowhunt>=4,<5"PHP
O pacote no Packagist é flowhunt/flowhunt-php-sdk. Ele exige PHP 8.1 ou superior.
composer require flowhunt/flowhunt-php-sdk:^4.0Migrar em quatro etapas#
Atualize o pacote
Instale a versão 4.0.0 como mostrado acima. Suas chamadas v2 existentes continuam funcionando após a atualização, então você pode migrar uma chamada por vez. Termine antes de 30 de novembro de 2026.
Renomeie cada chamada de sessão
Adicione
_v3ao nome do método Python ouV3ao do PHP. O mapeamento de métodos lista todos os pares.Passe o id da sessão como argumento do cabeçalho
O argumento do id da sessão agora é
x_fh_session_id. Em Python, passe-o por palavra-chave. Em PHP, três métodos o recebem como segundo argumento em vez do primeiro. Veja ordem de argumentos alterada para três métodos.Verifique os métodos removidos
Se você chama algum dos métodos removidos na 4.0.0, mude para o substituto ou remova a chamada.
Mapeamento de métodos#
Os métodos Python estão em flowhunt.FlowsApi, e os mesmos métodos v3 também existem em flowhunt.V3Api. Os métodos PHP estão em FlowHunt\Api\FlowsApi.
| O que | HTTP v2 | HTTP v3 (id da sessão em X-FH-Session-Id) | Python 3.x → 4.0 | PHP 3.x → 4.0 |
|---|---|---|---|---|
| Iniciar sessão de fluxo (chave de API) | POST /v2/flows/sessions/from_flow/create | POST /v3/flows/sessions/from_flow/create | create_flow_session → create_flow_session_v3 | createFlowSession → createFlowSessionV3 |
| Iniciar sessão de chatbot (anônima) | POST /v2/flows/sessions/create | POST /v3/flows/sessions/create | create_chatbot_session → create_chatbot_session_v3 | createChatbotSession → createChatbotSessionV3 |
| Enviar uma mensagem | POST /v2/flows/sessions/{id}/invoke | POST /v3/flows/sessions/invoke | invoke_flow_response → invoke_flow_response_v3 | invokeFlowResponse → invokeFlowResponseV3 |
| Consultar eventos | 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 uma execução | POST /v2/flows/sessions/{id}/cancel | POST /v3/flows/sessions/cancel | cancel_flow_session → cancel_flow_session_v3 | cancelFlowSession → cancelFlowSessionV3 |
| Voltar à âncora anterior | POST /v2/flows/sessions/{id}/back | POST /v3/flows/sessions/back | go_back → go_back_v3 | goBack → goBackV3 |
| Disparar um hook de chat | POST /v2/flows/sessions/{id}/hook | POST /v3/flows/sessions/hook | fire_chat_hook → fire_chat_hook_v3 | fireChatHook → fireChatHookV3 |
| Retomar um hook em espera | POST /v2/flows/sessions/{id}/resume-hook | POST /v3/flows/sessions/resume-hook | resume_hook → resume_hook_v3 | resumeHook → resumeHookV3 |
| Definir variáveis do fluxo | PATCH /v2/flows/sessions/{id}/variables | PATCH /v3/flows/sessions/variables | update_session_variables → update_session_variables_v3 | updateSessionVariables → updateSessionVariablesV3 |
| Listar anexos | GET /v2/flows/sessions/{id}/attachments | GET /v3/flows/sessions/attachments | get_attachments → get_attachments_v3 | getAttachments → getAttachmentsV3 |
| Enviar anexo | POST /v2/flows/sessions/{id}/attachments | POST /v3/flows/sessions/attachments | upload_attachments → upload_attachments_v3 | uploadAttachments → uploadAttachmentsV3 |
| Excluir anexo | DELETE /v2/flows/sessions/{id}/attachments/{file_id} | DELETE /v3/flows/sessions/attachments/{file_id} | delete_attachment → delete_attachment_v3 | deleteAttachment → deleteAttachmentV3 |
| Feedback de mensagem | POST /v2/flows/sessions/{id}/feedback | POST /v3/flows/sessions/feedback | create_message_feedback → create_message_feedback_v3 | createMessageFeedback → createMessageFeedbackV3 |
| Ler um artefato | GET /v2/flows/sessions/{id}/artefacts/{artefact_id} | GET /v3/flows/sessions/artefacts/{artefact_id} | get_artefact_content → get_artefact_content_v3 | getArtefactContent → getArtefactContentV3 |
| Pesquisa conforme digita (nova, sem v2) | nenhuma | POST /v3/flows/sessions/search | invoke_search_v3 | invokeSearchV3 |
O download de um anexo (GET /v2/flows/sessions/{id}/attachments/{file_id}) não tem versão v3. É uma chamada de painel com autenticação e não faz parte desta migração.
Apenas as duas chamadas de criação precisam da sua chave de API. from_flow/create inicia uma sessão para um fluxo no seu workspace e exige a chave. create é a sessão de chatbot anônima usada pelo widget de chat incorporado, portanto não exige chave. Ambas retornam session_id e created_at com HTTP 201. Todas as outras chamadas de sessão v3 precisam apenas do cabeçalho X-FH-Session-Id.
Envie anexos por HTTP por enquanto
Na 4.0.0, upload_attachments_v3 e uploadAttachmentsV3 não conseguem enviar um arquivo. A API retorna 422 “Expected UploadFile”, e o método Python rejeita bytes antes de a requisição ser enviada. Os métodos de envio da 3.x têm o mesmo problema. Até que isso seja corrigido, envie o arquivo como multipart/form-data para POST /v3/flows/sessions/attachments com o cabeçalho X-FH-Session-Id. A aba HTTP abaixo mostra a chamada.
Antes e depois#
Este exemplo inicia uma sessão para um fluxo publicado, envia “Hello” e imprime a resposta do fluxo. Cada aba mostra primeiro o código 3.x e depois o código 4.0 que executamos contra https://api.flowhunt.io. O código 4.0 lê a chave de API, o id do workspace e o id do fluxo das variáveis de ambiente FLOWHUNT_API_KEY, FLOWHUNT_WORKSPACE_ID e 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 # 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:
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(); // 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
Apenas a chamada de criação envia a chave de API. Todas as chamadas seguintes enviam o id da sessão no cabeçalho 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, o id da sessão fazia parte de cada caminho, por exemplo /v2/flows/sessions/$SESSION_ID/invoke. Uma chamada v3 sem o cabeçalho retorna 401.
Como funciona a consulta de eventos#
from_timestampé em milissegundos desde a época. A consulta retorna os eventos cujocreated_at_timestampé estritamente maior.- Comece pelo
created_atda resposta do invoke, que é um valor em milissegundos enviado como string, então converta-o para inteiro. Use0para obter a sessão inteira. Não use ocreated_atda resposta de criação, que é uma data e hora, não milissegundos. - Após cada consulta, mova
from_timestamppara ocreated_at_timestampdo evento mais novo menos 1 e ignore os eventos cujoevent_idvocê já viu. Eventos criados no mesmo milissegundo podem chegar em consultas diferentes. O widget de chat do FlowHunt consulta da mesma forma. - Cada evento tem um
event_type(ai,humanousystem), umaction_type(message,loading,tool_call,failed,hook_waiting_for_inpute outros) emetadata. O texto da resposta está emmetadata.messagedos eventosaido tipomessage.
O FlowHunt não envia um evento separado de “execução concluída”. Quando executamos os exemplos contra um fluxo de uma etapa, a consulta retornou um evento system do tipo loading, depois um ai do tipo message com a resposta, e nada depois disso. É por isso que os exemplos param na primeira consulta que não traz novos eventos depois de uma resposta ter chegado, e lançam erro em failed. Se o seu fluxo envia várias mensagens ou espera por entrada com hook_waiting_for_input, defina sua própria condição de parada.
Ordem de argumentos alterada para três métodos#
Reordene estas três chamadas
Os métodos v3 colocam os parâmetros de caminho antes do cabeçalho do id da sessão. Em PHP, e em Python quando você passa argumentos por posição, estas três chamadas falham com um erro de tipo ou enviam silenciosamente os valores errados, a menos que você as 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) |
Em Python, passe argumentos por palavra-chave em todos os lugares, por exemplo x_fh_session_id=session_id, e a ordem deixa de importar. O Python 4.0 também verifica os tipos dos argumentos, então from_timestamp deve ser um int. Passar a string "0" gera um ValidationError do pydantic.
Outras mudanças incompatíveis na 4.0.0#
Estes métodos existiam na 3.19.1 e não existem mais na 4.0.0, porque os endpoints da API por trás deles foram removidos ou alterados. Os nomes dos métodos PHP são a forma camelCase dos nomes Python, por exemplo get_available_models se torna getAvailableModels.
| Método removido | Endpoint | O que fazer |
|---|---|---|
AgentGridsApi.get_agent_grid_preview | GET /v2/agent_grids/{agent_grid_id}/preview | Remova a chamada. |
CustomModelsApi.get_available_models | GET /v2/custom-models/available | Remova a chamada. |
FineTuningsApi.create_image_ft, delete_image_ft, search_image_fts, update_image_ft | /v2/photo_ai/images/... | Remova as chamadas. |
WorkspacesApi.update_workspace_auto_recharge | PUT /v2/workspaces/{workspace_id}/auto-recharge | Remova a chamada. |
FlowBatchApi.export_csv | GET /v2/flows/{flow_id}/batch/{batch_run_id}/export-csv | Chame start_export_csv (POST, mesmo caminho), depois get_export_csv_status (GET .../export-csv/{task_id}). |
Os métodos do canal Zendesk, do faturamento Shopify, do Replicate e dos webhooks de pingback do SERP também foram removidos. Esses são webhooks de entrada para os próprios servidores do FlowHunt, não chamadas que o seu código faz.
Mantenha o id da sessão em segredo#
O id da sessão é uma credencial
Qualquer pessoa que tenha um id de sessão pode ler e continuar aquela conversa. Não o registre em log, não o coloque em URLs ou strings de consulta e não o envie para ferramentas de análise. Trate-o como uma senha de curta duração.
E a v2?#
As rotas de sessão v2 estão descontinuadas a partir do SDK 4.0.0 e chegam ao fim do ciclo de vida em 30 de novembro de 2026. Até lá, elas continuam funcionando e estão marcadas como descontinuadas na referência da API. O SDK 4.0.0 ainda inclui os métodos v2. Em Python, chamar um deles gera um DeprecationWarning. Em PHP, eles estão marcados como @deprecated no código, o que sua IDE ou análise estática vai sinalizar.