Di chuyển SDK

Chuyển sang SDK 4.0 và API phiên v3

Chuyển mã Python và PHP từ các lệnh gọi phiên luồng v2 sang v3, vốn gửi id phiên trong một header.

API phiên v2 sẽ ngừng hoạt động vào ngày 30 tháng 11 năm 2026

SDK 4.0.0 đánh dấu không dùng nữa các lệnh gọi phiên luồng v2, như create_flow_session, invoke_flow_response và poll_flow_response. Các route phiên v2 sẽ ngừng hoạt động vào ngày 30 tháng 11 năm 2026. Hãy chuyển mã của bạn sang các lệnh gọi v3 trên trang này trước thời điểm đó.

Phiên bản 4.0.0 của SDK FlowHunt cho Python và PHP bổ sung API phiên luồng v3. Chuyển sang nó giúp giữ id phiên trò chuyện của bạn khỏi URL, và phần lớn công việc chỉ là đổi tên phương thức. Trang này cho thấy những gì đã thay đổi, những lệnh gọi nào cần đổi tên, cùng mã trước và sau.

Những gì đã thay đổi#

Các lệnh gọi phiên v3 nhận id phiên trong header X-FH-Session-Id, không bao giờ trong URL. Phần thân yêu cầu và phản hồi giống như ở v2. Các route phiên v2 đã bị đánh dấu không dùng nữa và sẽ ngừng hoạt động vào ngày 30 tháng 11 năm 2026.

Trên v2, mọi lệnh gọi trò chuyện đều đặt id phiên trong đường dẫn, ví dụ /v2/flows/sessions/{session_id}/invoke. Id phiên là thông tin xác thực duy nhất mà một phiên trò chuyện ẩn danh có, và URL lại xuất hiện trong log truy cập, log proxy, lịch sử trình duyệt và header Referer. Header thì không.

Cài đặt 4.0.0#

Python

Gói trên PyPI là flowhunt.

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

PHP

Gói trên Packagist là flowhunt/flowhunt-php-sdk. Nó cần PHP 8.1 trở lên.

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

Di chuyển trong bốn bước#

  1. Nâng cấp gói

    Cài đặt 4.0.0 như hướng dẫn ở trên. Các lệnh gọi v2 hiện có của bạn vẫn hoạt động sau khi nâng cấp, nên bạn có thể chuyển từng lệnh gọi một. Hãy hoàn tất trước ngày 30 tháng 11 năm 2026.

  2. Đổi tên từng lệnh gọi phiên

    Thêm _v3 vào tên phương thức Python hoặc V3 vào tên phương thức PHP. Phần ánh xạ phương thức liệt kê mọi cặp.

  3. Truyền id phiên dưới dạng đối số header

    Đối số id phiên giờ là x_fh_session_id. Trong Python, hãy truyền nó bằng từ khóa. Trong PHP, ba phương thức nhận nó ở vị trí thứ hai thay vì thứ nhất. Xem thứ tự đối số đã thay đổi với ba phương thức.

  4. Kiểm tra các phương thức đã bị loại bỏ

    Nếu bạn gọi bất kỳ phương thức nào bị loại bỏ trong 4.0.0, hãy chuyển sang phương án thay thế hoặc xóa lệnh gọi đó.

Ánh xạ phương thức#

Các phương thức Python nằm trên flowhunt.FlowsApi, và các phương thức v3 tương tự cũng có trên flowhunt.V3Api. Các phương thức PHP nằm trên FlowHunt\Api\FlowsApi.

Việc cần làmHTTP v2HTTP v3 (id phiên trong X-FH-Session-Id)Python 3.x → 4.0PHP 3.x → 4.0
Bắt đầu phiên luồng (khóa API)POST /v2/flows/sessions/from_flow/createPOST /v3/flows/sessions/from_flow/createcreate_flow_session → create_flow_session_v3createFlowSession → createFlowSessionV3
Bắt đầu phiên chatbot (ẩn danh)POST /v2/flows/sessions/createPOST /v3/flows/sessions/createcreate_chatbot_session → create_chatbot_session_v3createChatbotSession → createChatbotSessionV3
Gửi tin nhắnPOST /v2/flows/sessions/{id}/invokePOST /v3/flows/sessions/invokeinvoke_flow_response → invoke_flow_response_v3invokeFlowResponse → invokeFlowResponseV3
Lấy sự kiện định kỳ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
Hủy một lượt chạyPOST /v2/flows/sessions/{id}/cancelPOST /v3/flows/sessions/cancelcancel_flow_session → cancel_flow_session_v3cancelFlowSession → cancelFlowSessionV3
Quay lại mốc neo trước đóPOST /v2/flows/sessions/{id}/backPOST /v3/flows/sessions/backgo_back → go_back_v3goBack → goBackV3
Kích hoạt một hook trò chuyệnPOST /v2/flows/sessions/{id}/hookPOST /v3/flows/sessions/hookfire_chat_hook → fire_chat_hook_v3fireChatHook → fireChatHookV3
Tiếp tục một hook đang chờPOST /v2/flows/sessions/{id}/resume-hookPOST /v3/flows/sessions/resume-hookresume_hook → resume_hook_v3resumeHook → resumeHookV3
Đặt biến luồngPATCH /v2/flows/sessions/{id}/variablesPATCH /v3/flows/sessions/variablesupdate_session_variables → update_session_variables_v3updateSessionVariables → updateSessionVariablesV3
Liệt kê tệp đính kèmGET /v2/flows/sessions/{id}/attachmentsGET /v3/flows/sessions/attachmentsget_attachments → get_attachments_v3getAttachments → getAttachmentsV3
Tải lên tệp đính kèmPOST /v2/flows/sessions/{id}/attachmentsPOST /v3/flows/sessions/attachmentsupload_attachments → upload_attachments_v3uploadAttachments → uploadAttachmentsV3
Xóa tệp đính kèmDELETE /v2/flows/sessions/{id}/attachments/{file_id}DELETE /v3/flows/sessions/attachments/{file_id}delete_attachment → delete_attachment_v3deleteAttachment → deleteAttachmentV3
Phản hồi tin nhắnPOST /v2/flows/sessions/{id}/feedbackPOST /v3/flows/sessions/feedbackcreate_message_feedback → create_message_feedback_v3createMessageFeedback → createMessageFeedbackV3
Đọc một artefactGET /v2/flows/sessions/{id}/artefacts/{artefact_id}GET /v3/flows/sessions/artefacts/{artefact_id}get_artefact_content → get_artefact_content_v3getArtefactContent → getArtefactContentV3
Tìm kiếm theo kiểu gõ (mới, không có ở v2)không cóPOST /v3/flows/sessions/searchinvoke_search_v3invokeSearchV3

Tải xuống một tệp đính kèm (GET /v2/flows/sessions/{id}/attachments/{file_id}) không có phiên bản v3. Đó là lệnh gọi của bảng điều khiển dành cho người dùng đã đăng nhập và không thuộc phạm vi di chuyển này.

Chỉ hai lệnh gọi tạo phiên cần khóa API của bạn. from_flow/create bắt đầu một phiên cho một luồng trong workspace của bạn và cần khóa. create là phiên chatbot ẩn danh mà widget trò chuyện nhúng sử dụng, nên nó không cần khóa. Cả hai đều trả về session_id và created_at với HTTP 201. Mọi lệnh gọi phiên v3 khác chỉ cần header X-FH-Session-Id.

Tạm thời hãy tải tệp đính kèm qua HTTP

Trong 4.0.0, upload_attachments_v3 và uploadAttachmentsV3 không thể gửi tệp. API trả về 422 “Expected UploadFile”, và phương thức Python từ chối bytes trước khi yêu cầu được gửi đi. Các phương thức tải lên của 3.x cũng gặp vấn đề tương tự. Cho đến khi lỗi này được sửa, hãy gửi tệp dưới dạng multipart/form-data tới POST /v3/flows/sessions/attachments kèm header X-FH-Session-Id. Tab HTTP bên dưới minh họa lệnh gọi này.

Trước và sau#

Ví dụ này bắt đầu một phiên cho một luồng đã xuất bản, gửi “Hello” và in câu trả lời của luồng. Mỗi tab hiển thị mã 3.x trước, rồi đến mã 4.0 mà chúng tôi đã chạy với https://api.flowhunt.io. Mã 4.0 đọc khóa API, id workspace và id luồng từ các biến môi trường FLOWHUNT_API_KEY, FLOWHUNT_WORKSPACE_ID và 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

Chỉ lệnh gọi tạo phiên mới gửi khóa API. Mọi lệnh gọi sau đó đều gửi id phiên trong header 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"

Trước đây, id phiên là một phần của mỗi đường dẫn, ví dụ /v2/flows/sessions/$SESSION_ID/invoke. Một lệnh gọi v3 không có header sẽ trả về 401.

Cách thức hoạt động của việc lấy sự kiện định kỳ#

  • from_timestamp là số mili giây tính từ epoch. Lệnh lấy sự kiện trả về những sự kiện có created_at_timestamp lớn hơn hẳn giá trị này.
  • Bắt đầu từ created_at của phản hồi invoke, vốn là một giá trị mili giây được gửi dưới dạng chuỗi, nên hãy chuyển nó thành số nguyên. Dùng 0 để lấy toàn bộ phiên. Đừng dùng created_at của phản hồi create, vì đó là ngày và giờ, không phải mili giây.
  • Sau mỗi lần lấy, hãy dời from_timestamp đến created_at_timestamp của sự kiện mới nhất trừ 1, và bỏ qua những sự kiện có event_id bạn đã thấy. Các sự kiện được tạo trong cùng một mili giây có thể đến ở những lần lấy khác nhau. Widget trò chuyện của FlowHunt cũng lấy sự kiện theo cách này.
  • Mỗi sự kiện có một event_type (ai, human hoặc system), một action_type (message, loading, tool_call, failed, hook_waiting_for_input và những loại khác) và metadata. Văn bản câu trả lời nằm trong metadata.message của các sự kiện message loại ai.

FlowHunt không gửi một sự kiện “lượt chạy kết thúc” riêng. Khi chúng tôi chạy các ví dụ với một luồng một bước, lệnh lấy sự kiện trả về một sự kiện loading loại system, rồi một sự kiện message loại ai chứa câu trả lời, và không có gì sau đó. Đó là lý do các ví dụ dừng ở lần lấy đầu tiên không mang về sự kiện mới nào sau khi câu trả lời đã đến, và ném lỗi khi gặp failed. Nếu luồng của bạn gửi nhiều tin nhắn hoặc chờ đầu vào với hook_waiting_for_input, hãy tự quyết định điều kiện dừng của riêng bạn.

Thứ tự đối số đã thay đổi với ba phương thức#

Sắp xếp lại ba lệnh gọi này

Các phương thức v3 đặt tham số đường dẫn trước header id phiên. Trong PHP, và trong Python khi bạn truyền đối số theo vị trí, ba lệnh gọi này sẽ lỗi kiểu dữ liệu hoặc âm thầm gửi sai giá trị trừ khi bạn sắp xếp lại chúng.

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)

Trong Python, hãy truyền đối số bằng từ khóa ở mọi nơi, ví dụ x_fh_session_id=session_id, và thứ tự không còn quan trọng nữa. Python 4.0 cũng kiểm tra kiểu đối số, nên from_timestamp phải là int. Truyền chuỗi "0" sẽ gây ra ValidationError của pydantic.

Các thay đổi gây lỗi khác trong 4.0.0#

Những phương thức này có trong 3.19.1 và đã biến mất trong 4.0.0, vì các endpoint API đứng sau chúng đã bị loại bỏ hoặc thay đổi. Tên phương thức PHP là dạng camelCase của tên phương thức Python, ví dụ get_available_models trở thành getAvailableModels.

Phương thức bị loại bỏEndpointViệc cần làm
AgentGridsApi.get_agent_grid_previewGET /v2/agent_grids/{agent_grid_id}/previewXóa lệnh gọi.
CustomModelsApi.get_available_modelsGET /v2/custom-models/availableXóa lệnh gọi.
FineTuningsApi.create_image_ft, delete_image_ft, search_image_fts, update_image_ft/v2/photo_ai/images/...Xóa các lệnh gọi.
WorkspacesApi.update_workspace_auto_rechargePUT /v2/workspaces/{workspace_id}/auto-rechargeXóa lệnh gọi.
FlowBatchApi.export_csvGET /v2/flows/{flow_id}/batch/{batch_run_id}/export-csvGọi start_export_csv (POST, cùng đường dẫn), rồi get_export_csv_status (GET .../export-csv/{task_id}).

Các phương thức cho kênh Zendesk, thanh toán Shopify, Replicate và webhook pingback SERP cũng đã bị loại bỏ. Đó là các webhook đến dành cho máy chủ của chính FlowHunt, không phải những lệnh gọi mà mã của bạn thực hiện.

Giữ bí mật id phiên#

Id phiên là một thông tin xác thực

Bất kỳ ai có id phiên đều có thể đọc và tiếp tục cuộc trò chuyện đó. Đừng ghi nó vào log, đừng đặt nó trong URL hay chuỗi truy vấn, và đừng gửi nó đến các công cụ phân tích. Hãy đối xử với nó như một mật khẩu ngắn hạn.

Còn v2 thì sao?#

Các route phiên v2 đã bị đánh dấu không dùng nữa kể từ SDK 4.0.0 và sẽ ngừng hoạt động vào ngày 30 tháng 11 năm 2026. Cho đến lúc đó chúng vẫn hoạt động, và chúng được đánh dấu là không dùng nữa trong tài liệu tham chiếu API. SDK 4.0.0 vẫn bao gồm các phương thức v2. Trong Python, gọi một phương thức như vậy sẽ phát ra DeprecationWarning. Trong PHP, chúng được đánh dấu @deprecated trong mã, nên IDE hoặc công cụ phân tích tĩnh của bạn sẽ cảnh báo.