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.

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

PHP

O pacote no Packagist é flowhunt/flowhunt-php-sdk. Ele exige PHP 8.1 ou superior.

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

Migrar em quatro etapas#

  1. 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.

  2. Renomeie cada chamada de sessão

    Adicione _v3 ao nome do método Python ou V3 ao do PHP. O mapeamento de métodos lista todos os pares.

  3. 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.

  4. 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 queHTTP v2HTTP v3 (id da sessão em X-FH-Session-Id)Python 3.x → 4.0PHP 3.x → 4.0
Iniciar sessão de fluxo (chave de API)POST /v2/flows/sessions/from_flow/createPOST /v3/flows/sessions/from_flow/createcreate_flow_session → create_flow_session_v3createFlowSession → createFlowSessionV3
Iniciar sessão de chatbot (anônima)POST /v2/flows/sessions/createPOST /v3/flows/sessions/createcreate_chatbot_session → create_chatbot_session_v3createChatbotSession → createChatbotSessionV3
Enviar uma mensagemPOST /v2/flows/sessions/{id}/invokePOST /v3/flows/sessions/invokeinvoke_flow_response → invoke_flow_response_v3invokeFlowResponse → invokeFlowResponseV3
Consultar eventosPOST /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 uma execuçãoPOST /v2/flows/sessions/{id}/cancelPOST /v3/flows/sessions/cancelcancel_flow_session → cancel_flow_session_v3cancelFlowSession → cancelFlowSessionV3
Voltar à âncora anteriorPOST /v2/flows/sessions/{id}/backPOST /v3/flows/sessions/backgo_back → go_back_v3goBack → goBackV3
Disparar um hook de chatPOST /v2/flows/sessions/{id}/hookPOST /v3/flows/sessions/hookfire_chat_hook → fire_chat_hook_v3fireChatHook → fireChatHookV3
Retomar um hook em esperaPOST /v2/flows/sessions/{id}/resume-hookPOST /v3/flows/sessions/resume-hookresume_hook → resume_hook_v3resumeHook → resumeHookV3
Definir variáveis do fluxoPATCH /v2/flows/sessions/{id}/variablesPATCH /v3/flows/sessions/variablesupdate_session_variables → update_session_variables_v3updateSessionVariables → updateSessionVariablesV3
Listar anexosGET /v2/flows/sessions/{id}/attachmentsGET /v3/flows/sessions/attachmentsget_attachments → get_attachments_v3getAttachments → getAttachmentsV3
Enviar anexoPOST /v2/flows/sessions/{id}/attachmentsPOST /v3/flows/sessions/attachmentsupload_attachments → upload_attachments_v3uploadAttachments → uploadAttachmentsV3
Excluir anexoDELETE /v2/flows/sessions/{id}/attachments/{file_id}DELETE /v3/flows/sessions/attachments/{file_id}delete_attachment → delete_attachment_v3deleteAttachment → deleteAttachmentV3
Feedback de mensagemPOST /v2/flows/sessions/{id}/feedbackPOST /v3/flows/sessions/feedbackcreate_message_feedback → create_message_feedback_v3createMessageFeedback → createMessageFeedbackV3
Ler um artefatoGET /v2/flows/sessions/{id}/artefacts/{artefact_id}GET /v3/flows/sessions/artefacts/{artefact_id}get_artefact_content → get_artefact_content_v3getArtefactContent → getArtefactContentV3
Pesquisa conforme digita (nova, sem v2)nenhumaPOST /v3/flows/sessions/searchinvoke_search_v3invokeSearchV3

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

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

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.

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"

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 cujo created_at_timestamp é estritamente maior.
  • Comece pelo created_at da resposta do invoke, que é um valor em milissegundos enviado como string, então converta-o para inteiro. Use 0 para obter a sessão inteira. Não use o created_at da resposta de criação, que é uma data e hora, não milissegundos.
  • Após cada consulta, mova from_timestamp para o created_at_timestamp do evento mais novo menos 1 e ignore os eventos cujo event_id você 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, human ou system), um action_type (message, loading, tool_call, failed, hook_waiting_for_input e outros) e metadata. O texto da resposta está em metadata.message dos eventos ai do tipo message.

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.

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)

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 removidoEndpointO que fazer
AgentGridsApi.get_agent_grid_previewGET /v2/agent_grids/{agent_grid_id}/previewRemova a chamada.
CustomModelsApi.get_available_modelsGET /v2/custom-models/availableRemova 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_rechargePUT /v2/workspaces/{workspace_id}/auto-rechargeRemova a chamada.
FlowBatchApi.export_csvGET /v2/flows/{flow_id}/batch/{batch_run_id}/export-csvChame 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.