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 です。
pip install --upgrade "flowhunt>=4,<5"PHP
Packagist 上のパッケージは flowhunt/flowhunt-php-sdk です。PHP 8.1 以降が必要です。
composer require flowhunt/flowhunt-php-sdk:^4.04 つのステップで移行する#
パッケージをアップグレードする
上記のとおり 4.0.0 をインストールします。アップグレード後も既存の v2 呼び出しは動作し続けるため、1 つずつ移行できます。2026年11月30日までに完了してください。
各セッション呼び出しをリネームする
Python のメソッド名には
_v3を、PHP のメソッド名にはV3を追加します。メソッド対応表にすべての対応が記載されています。セッション ID をヘッダー引数として渡す
セッション ID の引数は
x_fh_session_idになりました。Python ではキーワードで渡してください。PHP では 3 つのメソッドで、第 1 引数ではなく第 2 引数として受け取ります。詳しくは3 つのメソッドで引数の順序が変更を参照してください。削除されたメソッドを確認する
4.0.0 で削除されたメソッドのいずれかを呼び出している場合は、代替の呼び出しに切り替えるか、その呼び出しを削除してください。
メソッド対応表#
Python のメソッドは flowhunt.FlowsApi にあり、同じ v3 メソッドは flowhunt.V3Api にも存在します。PHP のメソッドは FlowHunt\Api\FlowsApi にあります。
| 内容 | v2 HTTP | v3 HTTP(セッション ID を X-FH-Session-Id で送信) | Python 3.x → 4.0 | PHP 3.x → 4.0 |
|---|---|---|---|---|
| フローセッションを開始(API キー) | POST /v2/flows/sessions/from_flow/create | POST /v3/flows/sessions/from_flow/create | create_flow_session → create_flow_session_v3 | createFlowSession → createFlowSessionV3 |
| チャットボットセッションを開始(匿名) | POST /v2/flows/sessions/create | POST /v3/flows/sessions/create | create_chatbot_session → create_chatbot_session_v3 | createChatbotSession → createChatbotSessionV3 |
| メッセージを送信 | POST /v2/flows/sessions/{id}/invoke | POST /v3/flows/sessions/invoke | invoke_flow_response → invoke_flow_response_v3 | invokeFlowResponse → invokeFlowResponseV3 |
| イベントをポーリング | 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 |
| 実行をキャンセル | POST /v2/flows/sessions/{id}/cancel | POST /v3/flows/sessions/cancel | cancel_flow_session → cancel_flow_session_v3 | cancelFlowSession → cancelFlowSessionV3 |
| 前のアンカーに戻る | POST /v2/flows/sessions/{id}/back | POST /v3/flows/sessions/back | go_back → go_back_v3 | goBack → goBackV3 |
| チャットフックを発火 | POST /v2/flows/sessions/{id}/hook | POST /v3/flows/sessions/hook | fire_chat_hook → fire_chat_hook_v3 | fireChatHook → fireChatHookV3 |
| 待機中のフックを再開 | POST /v2/flows/sessions/{id}/resume-hook | POST /v3/flows/sessions/resume-hook | resume_hook → resume_hook_v3 | resumeHook → resumeHookV3 |
| フロー変数を設定 | PATCH /v2/flows/sessions/{id}/variables | PATCH /v3/flows/sessions/variables | update_session_variables → update_session_variables_v3 | updateSessionVariables → updateSessionVariablesV3 |
| 添付ファイルを一覧表示 | GET /v2/flows/sessions/{id}/attachments | GET /v3/flows/sessions/attachments | get_attachments → get_attachments_v3 | getAttachments → getAttachmentsV3 |
| 添付ファイルをアップロード | POST /v2/flows/sessions/{id}/attachments | POST /v3/flows/sessions/attachments | upload_attachments → upload_attachments_v3 | uploadAttachments → uploadAttachmentsV3 |
| 添付ファイルを削除 | DELETE /v2/flows/sessions/{id}/attachments/{file_id} | DELETE /v3/flows/sessions/attachments/{file_id} | delete_attachment → delete_attachment_v3 | deleteAttachment → deleteAttachmentV3 |
| メッセージのフィードバック | POST /v2/flows/sessions/{id}/feedback | POST /v3/flows/sessions/feedback | create_message_feedback → create_message_feedback_v3 | createMessageFeedback → createMessageFeedbackV3 |
| アーティファクトを読み取り | GET /v2/flows/sessions/{id}/artefacts/{artefact_id} | GET /v3/flows/sessions/artefacts/{artefact_id} | get_artefact_content → get_artefact_content_v3 | getArtefactContent → getArtefactContentV3 |
| 入力中の検索(新規、v2 にはなし) | none | POST /v3/flows/sessions/search | invoke_search_v3 | invokeSearchV3 |
添付ファイルのダウンロード(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
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 # 秘密情報として扱い、決してログに出力しないでください
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(); // 秘密情報として扱い、決してログに出力しないでください
$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 ヘッダーで送信します。
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 つの呼び出しは型エラーで失敗するか、誤った値を静かに送信してしまいます。
| 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) |
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_preview | GET /v2/agent_grids/{agent_grid_id}/preview | 呼び出しを削除します。 |
CustomModelsApi.get_available_models | GET /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_recharge | PUT /v2/workspaces/{workspace_id}/auto-recharge | 呼び出しを削除します。 |
FlowBatchApi.export_csv | GET /v2/flows/{flow_id}/batch/{batch_run_id}/export-csv | start_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 や静的解析が警告します。