SDKマイグレーション

SDK 4.0 と v3 セッション API への移行

Python と PHP のコードを、セッション ID をヘッダーで送信する v3 へ、v2 のフローセッション呼び出しから移行します。

v2 セッション API は 2026年11月30日に提供終了となります

SDK 4.0.0 では、create_flow_session、invoke_flow_response、poll_flow_response などの v2 のフローセッション呼び出しが非推奨になります。v2 のセッションルートは 2026年11月30日 に提供終了となります。それまでに、コードをこのページに記載の v3 呼び出しへ移行してください。

FlowHunt の Python SDK と PHP SDK のバージョン 4.0.0 では、v3 のフローセッション API が追加されました。これに移行すると、チャットのセッション ID が URL に含まれなくなり、作業のほとんどはメソッド名の変更です。このページでは、何が変わったのか、どの呼び出しをリネームするのか、そして変更前と変更後のコードを説明します。

変更点#

v3 のセッション呼び出しでは、セッション ID を URL ではなく X-FH-Session-Id ヘッダーで渡します。リクエストボディとレスポンスボディは v2 と同じです。v2 のセッションルートは非推奨であり、2026年11月30日に提供終了となります。

v2 では、すべてのチャット呼び出しがセッション ID をパスに含めていました。たとえば /v2/flows/sessions/{session_id}/invoke です。セッション ID は匿名チャットセッションが持つ唯一の認証情報であり、URL はアクセスログ、プロキシログ、ブラウザ履歴、Referer ヘッダーに残ってしまいます。ヘッダーなら残りません。

4.0.0 のインストール#

Python

PyPI 上のパッケージは flowhunt です。

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

PHP

Packagist 上のパッケージは flowhunt/flowhunt-php-sdk です。PHP 8.1 以降が必要です。

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

4 つのステップで移行する#

  1. パッケージをアップグレードする

    上記のとおり 4.0.0 をインストールします。アップグレード後も既存の v2 呼び出しは動作し続けるため、1 つずつ移行できます。2026年11月30日までに完了してください。

  2. 各セッション呼び出しをリネームする

    Python のメソッド名には _v3 を、PHP のメソッド名には V3 を追加します。メソッド対応表にすべての対応が記載されています。

  3. セッション ID をヘッダー引数として渡す

    セッション ID の引数は x_fh_session_id になりました。Python ではキーワードで渡してください。PHP では 3 つのメソッドで、第 1 引数ではなく第 2 引数として受け取ります。詳しくは3 つのメソッドで引数の順序が変更を参照してください。

  4. 削除されたメソッドを確認する

    4.0.0 で削除されたメソッドのいずれかを呼び出している場合は、代替の呼び出しに切り替えるか、その呼び出しを削除してください。

メソッド対応表#

Python のメソッドは flowhunt.FlowsApi にあり、同じ v3 メソッドは flowhunt.V3Api にも存在します。PHP のメソッドは FlowHunt\Api\FlowsApi にあります。

内容v2 HTTPv3 HTTP(セッション ID を X-FH-Session-Id で送信)Python 3.x → 4.0PHP 3.x → 4.0
フローセッションを開始(API キー)POST /v2/flows/sessions/from_flow/createPOST /v3/flows/sessions/from_flow/createcreate_flow_session → create_flow_session_v3createFlowSession → createFlowSessionV3
チャットボットセッションを開始(匿名)POST /v2/flows/sessions/createPOST /v3/flows/sessions/createcreate_chatbot_session → create_chatbot_session_v3createChatbotSession → createChatbotSessionV3
メッセージを送信POST /v2/flows/sessions/{id}/invokePOST /v3/flows/sessions/invokeinvoke_flow_response → invoke_flow_response_v3invokeFlowResponse → invokeFlowResponseV3
イベントをポーリング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
実行をキャンセルPOST /v2/flows/sessions/{id}/cancelPOST /v3/flows/sessions/cancelcancel_flow_session → cancel_flow_session_v3cancelFlowSession → cancelFlowSessionV3
前のアンカーに戻るPOST /v2/flows/sessions/{id}/backPOST /v3/flows/sessions/backgo_back → go_back_v3goBack → goBackV3
チャットフックを発火POST /v2/flows/sessions/{id}/hookPOST /v3/flows/sessions/hookfire_chat_hook → fire_chat_hook_v3fireChatHook → fireChatHookV3
待機中のフックを再開POST /v2/flows/sessions/{id}/resume-hookPOST /v3/flows/sessions/resume-hookresume_hook → resume_hook_v3resumeHook → resumeHookV3
フロー変数を設定PATCH /v2/flows/sessions/{id}/variablesPATCH /v3/flows/sessions/variablesupdate_session_variables → update_session_variables_v3updateSessionVariables → updateSessionVariablesV3
添付ファイルを一覧表示GET /v2/flows/sessions/{id}/attachmentsGET /v3/flows/sessions/attachmentsget_attachments → get_attachments_v3getAttachments → getAttachmentsV3
添付ファイルをアップロードPOST /v2/flows/sessions/{id}/attachmentsPOST /v3/flows/sessions/attachmentsupload_attachments → upload_attachments_v3uploadAttachments → uploadAttachmentsV3
添付ファイルを削除DELETE /v2/flows/sessions/{id}/attachments/{file_id}DELETE /v3/flows/sessions/attachments/{file_id}delete_attachment → delete_attachment_v3deleteAttachment → deleteAttachmentV3
メッセージのフィードバックPOST /v2/flows/sessions/{id}/feedbackPOST /v3/flows/sessions/feedbackcreate_message_feedback → create_message_feedback_v3createMessageFeedback → createMessageFeedbackV3
アーティファクトを読み取りGET /v2/flows/sessions/{id}/artefacts/{artefact_id}GET /v3/flows/sessions/artefacts/{artefact_id}get_artefact_content → get_artefact_content_v3getArtefactContent → getArtefactContentV3
入力中の検索(新規、v2 にはなし)nonePOST /v3/flows/sessions/searchinvoke_search_v3invokeSearchV3

添付ファイルのダウンロード(GET /v2/flows/sessions/{id}/attachments/{file_id})には v3 版がありません。これはサインイン済みのダッシュボード用の呼び出しであり、この移行の対象外です。

API キーが必要なのは 2 つの create 呼び出しだけです。from_flow/create はワークスペース内のフローのセッションを開始するもので、キーが必要です。create は埋め込みチャットウィジェットが使用する匿名のチャットボットセッションであるため、キーは不要です。どちらも session_id と created_at を HTTP 201 で返します。それ以外のすべての v3 セッション呼び出しでは、X-FH-Session-Id ヘッダーのみが必要です。

現時点では HTTP で添付ファイルをアップロードしてください

4.0.0 では、upload_attachments_v3 と uploadAttachmentsV3 はファイルを送信できません。API は 422「Expected UploadFile」を返し、Python のメソッドはリクエストが送信される前にバイト列を拒否します。3.x のアップロードメソッドにも同じ問題があります。修正されるまでは、X-FH-Session-Id ヘッダーを付けて、ファイルを multipart/form-data として POST /v3/flows/sessions/attachments に送信してください。下記の HTTP タブに呼び出し例を示します。

変更前と変更後#

この例では、公開済みのフローのセッションを開始し、「Hello」を送信して、フローの回答を出力します。各タブでは、まず 3.x のコードを示し、次に https://api.flowhunt.io に対して実行した 4.0 のコードを示します。4.0 のコードは、API キー、ワークスペース ID、フロー ID を環境変数 FLOWHUNT_API_KEY、FLOWHUNT_WORKSPACE_ID、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  # 秘密情報として扱い、決してログに出力しないでください

    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(); // 秘密情報として扱い、決してログに出力しないでください

$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);
    // 引数の順序に注意: 第 1 引数がタイムスタンプ、第 2 引数がセッション ID です。
    $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

API キーを送信するのは create 呼び出しだけです。それ以降のすべての呼び出しは、セッション ID を X-FH-Session-Id ヘッダーで送信します。

セッションを開始(API キー)
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"

以前は、セッション ID が各パスの一部でした。たとえば /v2/flows/sessions/$SESSION_ID/invoke です。ヘッダーのない v3 呼び出しは 401 を返します。

ポーリングの仕組み#

  • from_timestamp はエポックからのミリ秒です。ポーリングは、created_at_timestamp が厳密に大きいイベントを返します。
  • invoke レスポンスの created_at から開始します。これは文字列として送信されるミリ秒の値なので、整数に変換してください。セッション全体を取得するには 0 を使用します。create レスポンスの created_at は日時でありミリ秒ではないため、使用しないでください。
  • 各ポーリングの後、from_timestamp を最新イベントの created_at_timestamp から 1 を引いた値に更新し、event_id をすでに確認したイベントはスキップします。同じミリ秒に作成されたイベントは、別々のポーリングで届くことがあります。FlowHunt のチャットウィジェットも同じ方法でポーリングしています。
  • 各イベントには event_type(ai、human、system)、action_type(message、loading、tool_call、failed、hook_waiting_for_input など)、および metadata があります。回答テキストは ai の message イベントの metadata.message にあります。

FlowHunt は「実行完了」という専用のイベントを送信しません。1 ステップのフローに対してサンプルを実行したところ、ポーリングは system の loading イベントを返し、次に回答を含む ai の message を 1 つ返し、それ以降は何も返しませんでした。そのため、サンプルは回答の到着後に新しいイベントが届かない最初のポーリングで停止し、failed の場合は例外を発生させます。フローが複数のメッセージを送信する場合や、hook_waiting_for_input で入力待ちになる場合は、独自の停止条件を決めてください。

3 つのメソッドで引数の順序が変更#

次の 3 つの呼び出しの引数を並べ替えてください

v3 のメソッドは、パスパラメーターをセッション ID ヘッダーより前に配置します。PHP では、また Python でも引数を位置で渡す場合には、順序を変更しないとこれら 3 つの呼び出しは型エラーで失敗するか、誤った値を静かに送信してしまいます。

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)

Python では、すべての箇所でキーワード引数(たとえば x_fh_session_id=session_id)を渡してください。そうすれば順序は問題になりません。Python 4.0 は引数の型もチェックするため、from_timestamp は int でなければなりません。文字列 "0" を渡すと pydantic の ValidationError が発生します。

4.0.0 で削除されたその他の破壊的変更#

以下のメソッドは 3.19.1 には存在しましたが、4.0.0 では削除されました。その背景にある API エンドポイントが削除または変更されたためです。PHP のメソッド名は Python のメソッド名のキャメルケース形式です。たとえば、get_available_models は getAvailableModels になります。

削除されたメソッドエンドポイント対応方法
AgentGridsApi.get_agent_grid_previewGET /v2/agent_grids/{agent_grid_id}/preview呼び出しを削除します。
CustomModelsApi.get_available_modelsGET /v2/custom-models/available呼び出しを削除します。
FineTuningsApi.create_image_ft、delete_image_ft、search_image_fts、update_image_ft/v2/photo_ai/images/...呼び出しを削除します。
WorkspacesApi.update_workspace_auto_rechargePUT /v2/workspaces/{workspace_id}/auto-recharge呼び出しを削除します。
FlowBatchApi.export_csvGET /v2/flows/{flow_id}/batch/{batch_run_id}/export-csvstart_export_csv(POST、同じパス)を呼び出し、次に get_export_csv_status(GET .../export-csv/{task_id})を呼び出します。

Zendesk チャネル、Shopify の課金、Replicate、SERP pingback の Webhook 用のメソッドも削除されました。これらは FlowHunt 自身のサーバー向けの受信 Webhook であり、お客様のコードが行う呼び出しではありません。

セッション ID を秘密に保つ#

セッション ID は認証情報です

セッション ID を持っている人は誰でも、その会話を読み取り、続行できます。ログに出力したり、URL やクエリ文字列に含めたり、アナリティクスに送信したりしないでください。短命のパスワードと同じように扱ってください。

v2 はどうなるか#

v2 のセッションルートは SDK 4.0.0 で非推奨となり、2026年11月30日に提供終了となります。それまでは動作し続け、API リファレンスでは非推奨としてマークされています。SDK 4.0.0 には依然として v2 メソッドが含まれています。Python では呼び出すと DeprecationWarning が発生します。PHP ではコード内で @deprecated としてマークされているため、IDE や静的解析が警告します。