SDK geçişleri

SDK 4.0'a ve v3 oturum API'sine geçiş

Python ve PHP kodlarını v2 flow-session çağrılarından, oturum kimliğini bir başlıkta gönderen v3’e taşıyın.

v2 oturum API'sinin desteği 30 Kasım 2026'da sona eriyor

SDK 4.0.0, create_flow_session, invoke_flow_response ve poll_flow_response gibi v2 flow-session çağrılarını kullanımdan kaldırır. v2 oturum rotalarının desteği 30 Kasım 2026‘da sona eriyor. Kodunuzu o tarihten önce bu sayfadaki v3 çağrılarına taşıyın.

FlowHunt Python ve PHP SDK’larının 4.0.0 sürümü v3 flow-session API’sini ekler. Buna geçmek sohbet oturum kimliklerinizi URL’lerin dışında tutar ve işin büyük kısmı metotları yeniden adlandırmaktan ibarettir. Bu sayfa nelerin değiştiğini, hangi çağrıların yeniden adlandırılacağını ve kodun önceki ile sonraki halini gösterir.

Neler değişti#

v3 oturum çağrıları oturum kimliğini X-FH-Session-Id başlığında alır, hiçbir zaman URL’de değil. İstek ve yanıt gövdeleri v2’dekiyle aynıdır. v2 oturum rotaları kullanımdan kaldırılmıştır ve 30 Kasım 2026’da destekleri sona erer.

v2’de her sohbet çağrısı oturum kimliğini yolun içine koyar, örneğin /v2/flows/sessions/{session_id}/invoke. Oturum kimliği, anonim bir sohbet oturumunun sahip olduğu tek kimlik bilgisidir ve URL’ler erişim günlüklerine, proxy günlüklerine, tarayıcı geçmişine ve Referer başlıklarına düşer. Bir başlık ise düşmez.

4.0.0 sürümünü yükleme#

Python

PyPI’daki paket flowhunt.

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

PHP

Packagist’teki paket flowhunt/flowhunt-php-sdk. PHP 8.1 veya daha yenisini gerektirir.

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

Dört adımda geçiş#

  1. Paketi yükseltin

    4.0.0’ı yukarıda gösterildiği gibi yükleyin. Mevcut v2 çağrılarınız yükseltmeden sonra çalışmaya devam eder, böylece bir seferde bir çağrıyı taşıyabilirsiniz. 30 Kasım 2026’dan önce bitirin.

  2. Her oturum çağrısını yeniden adlandırın

    Python metot adına _v3, PHP metot adına V3 ekleyin. Metot eşlemesi tüm çiftleri listeler.

  3. Oturum kimliğini başlık argümanı olarak geçirin

    Oturum kimliği argümanı artık x_fh_session_id. Python’da bunu anahtar sözcük argümanı olarak geçirin. PHP’de üç metot bunu ilk sırada değil ikinci sırada alır. Bkz. üç metot için argüman sırası değişti.

  4. Kaldırılan metotları kontrol edin

    4.0.0’da kaldırılan metotlardan herhangi birini çağırıyorsanız, yerine geçen metoda geçin veya çağrıyı kaldırın.

Metot eşlemesi#

Python metotları flowhunt.FlowsApi üzerindedir ve aynı v3 metotları flowhunt.V3Api üzerinde de bulunur. PHP metotları FlowHunt\Api\FlowsApi üzerindedir.

Nev2 HTTPv3 HTTP (oturum kimliği X-FH-Session-Id içinde)Python 3.x → 4.0PHP 3.x → 4.0
Akış oturumu başlat (API anahtarı)POST /v2/flows/sessions/from_flow/createPOST /v3/flows/sessions/from_flow/createcreate_flow_session → create_flow_session_v3createFlowSession → createFlowSessionV3
Chatbot oturumu başlat (anonim)POST /v2/flows/sessions/createPOST /v3/flows/sessions/createcreate_chatbot_session → create_chatbot_session_v3createChatbotSession → createChatbotSessionV3
Mesaj gönderPOST /v2/flows/sessions/{id}/invokePOST /v3/flows/sessions/invokeinvoke_flow_response → invoke_flow_response_v3invokeFlowResponse → invokeFlowResponseV3
Olayları yoklaPOST /v2/flows/sessions/{id}/invocation_response/{from_timestamp}POST /v3/flows/sessions/invocation_response/{from_timestamp}poll_flow_response → poll_flow_response_v3pollFlowResponse → pollFlowResponseV3
Çalıştırmayı iptal etPOST /v2/flows/sessions/{id}/cancelPOST /v3/flows/sessions/cancelcancel_flow_session → cancel_flow_session_v3cancelFlowSession → cancelFlowSessionV3
Önceki bağlantı noktasına geri dönPOST /v2/flows/sessions/{id}/backPOST /v3/flows/sessions/backgo_back → go_back_v3goBack → goBackV3
Sohbet kancasını tetiklePOST /v2/flows/sessions/{id}/hookPOST /v3/flows/sessions/hookfire_chat_hook → fire_chat_hook_v3fireChatHook → fireChatHookV3
Bekleyen kancayı sürdürPOST /v2/flows/sessions/{id}/resume-hookPOST /v3/flows/sessions/resume-hookresume_hook → resume_hook_v3resumeHook → resumeHookV3
Akış değişkenlerini ayarlaPATCH /v2/flows/sessions/{id}/variablesPATCH /v3/flows/sessions/variablesupdate_session_variables → update_session_variables_v3updateSessionVariables → updateSessionVariablesV3
Ekleri listeleGET /v2/flows/sessions/{id}/attachmentsGET /v3/flows/sessions/attachmentsget_attachments → get_attachments_v3getAttachments → getAttachmentsV3
Ek yüklePOST /v2/flows/sessions/{id}/attachmentsPOST /v3/flows/sessions/attachmentsupload_attachments → upload_attachments_v3uploadAttachments → uploadAttachmentsV3
Ek silDELETE /v2/flows/sessions/{id}/attachments/{file_id}DELETE /v3/flows/sessions/attachments/{file_id}delete_attachment → delete_attachment_v3deleteAttachment → deleteAttachmentV3
Mesaj geri bildirimiPOST /v2/flows/sessions/{id}/feedbackPOST /v3/flows/sessions/feedbackcreate_message_feedback → create_message_feedback_v3createMessageFeedback → createMessageFeedbackV3
Artefakt okuGET /v2/flows/sessions/{id}/artefacts/{artefact_id}GET /v3/flows/sessions/artefacts/{artefact_id}get_artefact_content → get_artefact_content_v3getArtefactContent → getArtefactContentV3
Yazdıkça arama (yeni, v2’si yok)yokPOST /v3/flows/sessions/searchinvoke_search_v3invokeSearchV3

Bir eki indirmenin (GET /v2/flows/sessions/{id}/attachments/{file_id}) v3 sürümü yoktur. Bu, oturum açmış kullanıcılar için bir panel çağrısıdır ve bu geçişin parçası değildir.

Yalnızca iki oluşturma çağrısı API anahtarınızı gerektirir. from_flow/create, çalışma alanınızdaki bir akış için oturum başlatır ve anahtarı gerektirir. create, gömülü sohbet widget’ının kullandığı anonim chatbot oturumudur, bu yüzden anahtar almaz. İkisi de HTTP 201 ile session_id ve created_at döndürür. Diğer tüm v3 oturum çağrıları yalnızca X-FH-Session-Id başlığına ihtiyaç duyar.

Şimdilik ekleri HTTP üzerinden yükleyin

4.0.0’da upload_attachments_v3 ve uploadAttachmentsV3 bir dosya gönderemez. API 422 “Expected UploadFile” döndürür ve Python metodu istek gönderilmeden önce bytes değerini reddeder. 3.x yükleme metotlarında da aynı sorun vardır. Sorun düzeltilene kadar dosyayı X-FH-Session-Id başlığıyla POST /v3/flows/sessions/attachments adresine multipart/form-data olarak gönderin. Aşağıdaki HTTP sekmesi çağrıyı gösterir.

Öncesi ve sonrası#

Bu örnek yayımlanmış bir akış için oturum başlatır, “Hello” gönderir ve akışın yanıtını yazdırır. Her sekme önce 3.x kodunu, ardından https://api.flowhunt.io adresine karşı çalıştırdığımız 4.0 kodunu gösterir. 4.0 kodu API anahtarını, çalışma alanı kimliğini ve akış kimliğini FLOWHUNT_API_KEY, FLOWHUNT_WORKSPACE_ID ve FLOWHUNT_FLOW_ID ortam değişkenlerinden okur.

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  # gizli tutun, asla günlüğe yazmayın

    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(); // gizli tutun, asla günlüğe yazmayın

$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);
    // Sıraya dikkat: önce zaman damgası, sonra oturum kimliği.
    $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

Yalnızca oluşturma çağrısı API anahtarını gönderir. Ondan sonraki her çağrı oturum kimliğini X-FH-Session-Id başlığında gönderir.

Oturum başlat (API anahtarı)
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\"}"
Mesaj gönder
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"}'
Olayları yokla
curl -X POST "https://api.flowhunt.io/v3/flows/sessions/invocation_response/$FROM_TIMESTAMP" \
  -H "X-FH-Session-Id: $SESSION_ID"
Ek yükle
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"

Önceden oturum kimliği her yolun bir parçasıydı, örneğin /v2/flows/sessions/$SESSION_ID/invoke. Başlık olmadan yapılan bir v3 çağrısı 401 döndürür.

Yoklama nasıl çalışır#

  • from_timestamp epoch’tan itibaren milisaniye cinsindendir. Yoklama, created_at_timestamp değeri bundan kesinlikle büyük olan olayları döndürür.
  • Invoke yanıtının created_at değerinden başlayın; bu, dize olarak gönderilen bir milisaniye değeridir, bu yüzden onu tam sayıya dönüştürün. Tüm oturumu almak için 0 kullanın. Oluşturma yanıtının created_at değerini kullanmayın; o bir tarih ve saattir, milisaniye değildir.
  • Her yoklamadan sonra from_timestamp değerini en yeni olayın created_at_timestamp değerinin 1 eksiğine taşıyın ve event_id değerini zaten gördüğünüz olayları atlayın. Aynı milisaniyede oluşturulan olaylar farklı yoklamalarda gelebilir. FlowHunt sohbet widget’ı da aynı şekilde yoklar.
  • Her olayın bir event_type (ai, human veya system), bir action_type (message, loading, tool_call, failed, hook_waiting_for_input ve diğerleri) ve metadata değeri vardır. Yanıt metni ai message olaylarının metadata.message alanındadır.

FlowHunt ayrı bir “çalıştırma bitti” olayı göndermez. Örnekleri tek adımlı bir akışa karşı çalıştırdığımızda, yoklama bir system loading olayı, ardından yanıtı içeren bir ai message döndürdü ve sonrasında hiçbir şey gelmedi. Örneklerin, bir yanıt geldikten sonra yeni olay getirmeyen ilk yoklamada durması ve failed durumunda hata fırlatması bu yüzdendir. Akışınız birkaç mesaj gönderiyorsa veya hook_waiting_for_input ile girdi bekliyorsa, kendi durma koşulunuzu belirleyin.

Üç metot için argüman sırası değişti#

Bu üç çağrıyı yeniden sıralayın

v3 metotları yol parametrelerini oturum kimliği başlığından önce koyar. PHP’de ve Python’da argümanları konuma göre geçtiğinizde, bu üç çağrı yeniden sıralamazsanız bir tür hatasıyla başarısız olur veya sessizce yanlış değerler gönderir.

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’da her yerde anahtar sözcük argümanları kullanın, örneğin x_fh_session_id=session_id; o zaman sıra artık önemli değildir. Python 4.0 ayrıca argüman türlerini kontrol eder, bu yüzden from_timestamp bir int olmalıdır. "0" dizesini geçirmek bir pydantic ValidationError hatası verir.

4.0.0’daki diğer kırıcı değişiklikler#

Bu metotlar 3.19.1’de vardı ve 4.0.0’da kaldırıldı, çünkü arkalarındaki API uç noktaları kaldırıldı veya değiştirildi. PHP metot adları Python’dakilerin camelCase biçimidir, örneğin get_available_models → getAvailableModels olur.

Kaldırılan metotUç noktaNe yapmalı
AgentGridsApi.get_agent_grid_previewGET /v2/agent_grids/{agent_grid_id}/previewÇağrıyı kaldırın.
CustomModelsApi.get_available_modelsGET /v2/custom-models/availableÇağrıyı kaldırın.
FineTuningsApi.create_image_ft, delete_image_ft, search_image_fts, update_image_ft/v2/photo_ai/images/...Çağrıları kaldırın.
WorkspacesApi.update_workspace_auto_rechargePUT /v2/workspaces/{workspace_id}/auto-rechargeÇağrıyı kaldırın.
FlowBatchApi.export_csvGET /v2/flows/{flow_id}/batch/{batch_run_id}/export-csvstart_export_csv (POST, aynı yol) çağırın, ardından get_export_csv_status (GET .../export-csv/{task_id}) çağırın.

Zendesk kanalı, Shopify faturalandırma, Replicate ve SERP pingback webhook’ları için olan metotlar da kaldırıldı. Bunlar FlowHunt’ın kendi sunucuları için gelen webhook’lardır, kodunuzun yaptığı çağrılar değildir.

Oturum kimliğini gizli tutun#

Oturum kimliği bir kimlik bilgisidir

Oturum kimliğine sahip olan herkes o konuşmayı okuyabilir ve sürdürebilir. Günlüğe yazmayın, URL’lere veya sorgu dizelerine koymayın ve analitik araçlarına göndermeyin. Kısa ömürlü bir parola gibi davranın.

Peki ya v2?#

v2 oturum rotaları SDK 4.0.0 itibarıyla kullanımdan kaldırılmıştır ve 30 Kasım 2026’da destekleri sona erer. O zamana kadar çalışmaya devam ederler ve API referansında kullanımdan kaldırılmış olarak işaretlenirler. SDK 4.0.0 hâlâ v2 metotlarını içerir. Python’da bunlardan birini çağırmak DeprecationWarning verir. PHP’de kodda @deprecated olarak işaretlenirler; IDE’niz veya statik analiziniz bunu bildirir.