Migrate to SDK 4.0 and the v3 session API

Version 4.0.0 of the FlowHunt Python and PHP SDKs adds the v3 flow-session API. Moving to it keeps your chat session ids out of URLs, and most of the work is renaming methods. This page shows what changed, which calls to rename, and the code before and after.

What changed#

v3 session calls take the session id in the X-FH-Session-Id header, never in the URL. The request and response bodies are the same as in v2. The v2 session routes are deprecated and reach end of life on November 30, 2026.

On v2, every chat call puts the session id in the path, for example /v2/flows/sessions/{session_id}/invoke. The session id is the only credential an anonymous chat session has, and URLs end up in access logs, proxy logs, browser history and Referer headers. A header doesn’t.

Install 4.0.0#

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

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

Migrate in four steps#

1. Upgrade the package

   Install 4.0.0 as shown above. Your existing v2 calls keep working after the upgrade, so you can move one call at a time. Finish before November 30, 2026.

2. Rename each session call

   Add _v3 to the Python method name or V3 to the PHP one. The method mapping lists every pair.

3. Pass the session id as the header argument

   The session-id argument is now x_fh_session_id. In Python, pass it by keyword. In PHP, three methods take it second instead of first. See argument order changed for three methods.

4. Check the removed methods

   If you call any of the methods removed in 4.0.0, switch to the replacement or remove the call.

Method mapping#

Python methods are on flowhunt.FlowsApi, and the same v3 methods also exist on flowhunt.V3Api. PHP methods are on FlowHunt\Api\FlowsApi.

Downloading an attachment (GET /v2/flows/sessions/{id}/attachments/{file_id}) has no v3 version. It is a signed-in dashboard call and isn’t part of this migration.

Only the two create calls need your API key. from_flow/create starts a session for a flow in your workspace and requires the key. create is the anonymous chatbot session that the embedded chat widget uses, so it takes no key. Both return session_id and created_at with HTTP 201. Every other v3 session call needs only the X-FH-Session-Id header.

Before and after#

This example starts a session for a published flow, sends “Hello” and prints the flow’s answer. Each tab shows the 3.x code first, then the 4.0 code we ran against https://api.flowhunt.io. The 4.0 code reads the API key, workspace id and flow id from the environment variables FLOWHUNT_API_KEY, FLOWHUNT_WORKSPACE_ID and FLOWHUNT_FLOW_ID.

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:
            break

$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;
    }
}

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"

How polling works#

• from_timestamp is milliseconds since the epoch. The poll returns the events whose created_at_timestamp is strictly greater.
• Start from the created_at of the invoke response, which is a millisecond value sent as a string, so convert it to an integer. Use 0 to get the whole session. Don’t use the created_at of the create response, which is a date and time, not milliseconds.
• After each poll, move from_timestamp to the newest event’s created_at_timestamp minus 1 and skip events whose event_id you have already seen. Events created in the same millisecond can arrive in different polls. The FlowHunt chat widget polls the same way.
• Each event has an event_type (ai, human or system), an action_type (message, loading, tool_call, failed, hook_waiting_for_input and others) and metadata. The answer text is in metadata.message of the ai message events.

FlowHunt doesn’t send a separate “run finished” event. When we ran the samples against a one-step flow, the poll returned a system loading event, then one ai message with the answer, and nothing after that. That is why the samples stop at the first poll that brings no new events after an answer arrived, and raise on failed. If your flow sends several messages or waits for input with hook_waiting_for_input, decide your own stop condition.

Argument order changed for three methods#

In Python, pass keyword arguments everywhere, for example x_fh_session_id=session_id, and the order no longer matters. Python 4.0 also checks argument types, so from_timestamp must be an int. Passing the string "0" raises a pydantic ValidationError.

Other breaking changes in 4.0.0#

These methods were in 3.19.1 and are gone in 4.0.0, because the API endpoints behind them were removed or changed. PHP method names are the camelCase form of the Python ones, for example get_available_models becomes getAvailableModels.

The methods for the Zendesk channel, Shopify billing, Replicate and SERP pingback webhooks were removed too. Those are incoming webhooks for FlowHunt’s own servers, not calls your code makes.

Keep the session id secret#

What about v2?#

The v2 session routes are deprecated as of SDK 4.0.0 and reach end of life on November 30, 2026. Until then they keep working, and they are marked deprecated in the API reference. SDK 4.0.0 still includes the v2 methods. In Python, calling one raises a DeprecationWarning. In PHP, they are marked @deprecated in the code, which your IDE or static analysis will flag.