SDK-migraatiot

Siirry SDK 4.0:aan ja v3-istunto-API:in

Siirrä Python- ja PHP-koodi v2:n flow-istuntokutsuista v3:een, joka lähettää istuntotunnisteen otsakkeessa.

v2-istunto-API poistuu käytöstä 30. marraskuuta 2026

SDK 4.0.0 poistaa käytöstä v2:n flow-istuntokutsut, kuten create_flow_session, invoke_flow_response ja poll_flow_response. v2:n istuntoreitit poistuvat käytöstä 30. marraskuuta 2026. Siirrä koodisi tämän sivun v3-kutsuihin ennen sitä.

FlowHuntin Python- ja PHP-SDK:iden versio 4.0.0 tuo v3-flow-istunto-API:n. Siihen siirtyminen pitää chat-istuntotunnisteesi poissa URL-osoitteista, ja suurin osa työstä on menetelmien uudelleennimeämistä. Tällä sivulla kerrotaan, mikä muuttui, mitkä kutsut nimetään uudelleen sekä koodi ennen ja jälkeen.

Mikä muuttui#

v3-istuntokutsut ottavat istuntotunnisteen X-FH-Session-Id-otsakkeesta, eivät koskaan URL-osoitteesta. Pyynnön ja vastauksen rungot ovat samat kuin v2:ssa. v2:n istuntoreitit ovat vanhentuneita ja poistuvat käytöstä 30. marraskuuta 2026.

v2:ssa jokainen chat-kutsu laittaa istuntotunnisteen polkuun, esimerkiksi /v2/flows/sessions/{session_id}/invoke. Istuntotunniste on ainoa tunnistautumistieto, joka anonyymilla chat-istunnolla on, ja URL-osoitteet päätyvät käyttölokeihin, välityspalvelinten lokeihin, selaimen historiaan ja Referer-otsakkeisiin. Otsake ei päädy samoihin paikkoihin.

Asenna 4.0.0#

Python

PyPI:n paketti on flowhunt.

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

PHP

Packagistin paketti on flowhunt/flowhunt-php-sdk. Se vaatii PHP 8.1:n tai uudemman.

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

Siirrä neljässä vaiheessa#

  1. Päivitä paketti

    Asenna 4.0.0 yllä kuvatulla tavalla. Nykyiset v2-kutsusi toimivat edelleen päivityksen jälkeen, joten voit siirtää yhden kutsun kerrallaan. Lopeta ennen 30. marraskuuta 2026.

  2. Nimeä jokainen istuntokutsu uudelleen

    Lisää _v3 Python-menetelmän nimeen tai V3 PHP-menetelmän nimeen. Menetelmien vastaavuus luettelee jokaisen parin.

  3. Anna istuntotunniste otsake-argumenttina

    Istuntotunnisteen argumentti on nyt x_fh_session_id. Pythonissa anna se avainsanana. PHP:ssa kolme menetelmää ottaa sen toisena ensimmäisen sijaan. Katso argumenttien järjestys muuttui kolmessa menetelmässä.

  4. Tarkista poistetut menetelmät

    Jos kutsut jotain versiossa 4.0.0 poistetuista menetelmistä, vaihda korvaavaan tai poista kutsu.

Menetelmien vastaavuus#

Python-menetelmät ovat flowhunt.FlowsApi-luokassa, ja samat v3-menetelmät ovat myös flowhunt.V3Api-luokassa. PHP-menetelmät ovat FlowHunt\Api\FlowsApi-luokassa.

Mitäv2 HTTPv3 HTTP (istuntotunniste otsakkeessa X-FH-Session-Id)Python 3.x → 4.0PHP 3.x → 4.0
Aloita flow-istunto (API-avain)POST /v2/flows/sessions/from_flow/createPOST /v3/flows/sessions/from_flow/createcreate_flow_session → create_flow_session_v3createFlowSession → createFlowSessionV3
Aloita chatbot-istunto (anonyymi)POST /v2/flows/sessions/createPOST /v3/flows/sessions/createcreate_chatbot_session → create_chatbot_session_v3createChatbotSession → createChatbotSessionV3
Lähetä viestiPOST /v2/flows/sessions/{id}/invokePOST /v3/flows/sessions/invokeinvoke_flow_response → invoke_flow_response_v3invokeFlowResponse → invokeFlowResponseV3
Kysy tapahtumiaPOST /v2/flows/sessions/{id}/invocation_response/{from_timestamp}POST /v3/flows/sessions/invocation_response/{from_timestamp}poll_flow_response → poll_flow_response_v3pollFlowResponse → pollFlowResponseV3
Peruuta ajoPOST /v2/flows/sessions/{id}/cancelPOST /v3/flows/sessions/cancelcancel_flow_session → cancel_flow_session_v3cancelFlowSession → cancelFlowSessionV3
Palaa edelliseen ankkuriinPOST /v2/flows/sessions/{id}/backPOST /v3/flows/sessions/backgo_back → go_back_v3goBack → goBackV3
Laukaise chat-koukkuPOST /v2/flows/sessions/{id}/hookPOST /v3/flows/sessions/hookfire_chat_hook → fire_chat_hook_v3fireChatHook → fireChatHookV3
Jatka odottavaa koukkuaPOST /v2/flows/sessions/{id}/resume-hookPOST /v3/flows/sessions/resume-hookresume_hook → resume_hook_v3resumeHook → resumeHookV3
Aseta flown muuttujatPATCH /v2/flows/sessions/{id}/variablesPATCH /v3/flows/sessions/variablesupdate_session_variables → update_session_variables_v3updateSessionVariables → updateSessionVariablesV3
Listaa liitteetGET /v2/flows/sessions/{id}/attachmentsGET /v3/flows/sessions/attachmentsget_attachments → get_attachments_v3getAttachments → getAttachmentsV3
Lataa liitePOST /v2/flows/sessions/{id}/attachmentsPOST /v3/flows/sessions/attachmentsupload_attachments → upload_attachments_v3uploadAttachments → uploadAttachmentsV3
Poista liiteDELETE /v2/flows/sessions/{id}/attachments/{file_id}DELETE /v3/flows/sessions/attachments/{file_id}delete_attachment → delete_attachment_v3deleteAttachment → deleteAttachmentV3
Viestin palautePOST /v2/flows/sessions/{id}/feedbackPOST /v3/flows/sessions/feedbackcreate_message_feedback → create_message_feedback_v3createMessageFeedback → createMessageFeedbackV3
Lue artefaktiGET /v2/flows/sessions/{id}/artefacts/{artefact_id}GET /v3/flows/sessions/artefacts/{artefact_id}get_artefact_content → get_artefact_content_v3getArtefactContent → getArtefactContentV3
Haku kirjoittaessa (uusi, ei v2:ssa)ei mitäänPOST /v3/flows/sessions/searchinvoke_search_v3invokeSearchV3

Liitteen lataamisella (GET /v2/flows/sessions/{id}/attachments/{file_id}) ei ole v3-versiota. Se on kirjautuneen hallintapaneelin kutsu eikä kuulu tähän siirtoon.

Vain kaksi luontikutsua tarvitsevat API-avaimesi. from_flow/create aloittaa istunnon työtilasi flowlle ja vaatii avaimen. create on anonyymi chatbot-istunto, jota upotettu chat-widget käyttää, joten se ei ota avainta. Molemmat palauttavat session_id- ja created_at-arvot HTTP-tilalla 201. Jokainen muu v3-istuntokutsu tarvitsee vain X-FH-Session-Id-otsakkeen.

Lataa liitteet toistaiseksi HTTP:n kautta

Versiossa 4.0.0 upload_attachments_v3 ja uploadAttachmentsV3 eivät voi lähettää tiedostoa. API palauttaa 422 “Expected UploadFile”, ja Python-menetelmä hylkää tavut ennen pyynnön lähettämistä. 3.x:n latausmenetelmissä on sama ongelma. Kunnes se on korjattu, lähetä tiedosto multipart/form-data-muodossa osoitteeseen POST /v3/flows/sessions/attachments X-FH-Session-Id-otsakkeen kanssa. Alla oleva HTTP-välilehti näyttää kutsun.

Ennen ja jälkeen#

Tämä esimerkki aloittaa istunnon julkaistulle flowlle, lähettää “Hello” ja tulostaa flown vastauksen. Jokainen välilehti näyttää ensin 3.x-koodin ja sitten 4.0-koodin, jota ajoimme https://api.flowhunt.io-osoitetta vasten. 4.0-koodi lukee API-avaimen, työtilan tunnisteen ja flown tunnisteen ympäristömuuttujista FLOWHUNT_API_KEY, FLOWHUNT_WORKSPACE_ID ja 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  # pidä salassa, älä koskaan kirjaa sitä lokiin

    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(); // pidä salassa, älä koskaan kirjaa sitä lokiin

$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);
    // Huomaa järjestys: aikaleima ensin, istuntotunniste toisena.
    $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

Vain luontikutsu lähettää API-avaimen. Jokainen sen jälkeinen kutsu lähettää istuntotunnisteen X-FH-Session-Id-otsakkeessa.

Aloita istunto (API-avain)
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\"}"
Lähetä viesti
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"}'
Kysy tapahtumia
curl -X POST "https://api.flowhunt.io/v3/flows/sessions/invocation_response/$FROM_TIMESTAMP" \
  -H "X-FH-Session-Id: $SESSION_ID"
Lataa liite
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"

Aiemmin istuntotunniste oli osa jokaista polkua, esimerkiksi /v2/flows/sessions/$SESSION_ID/invoke. v3-kutsu ilman otsaketta palauttaa 401.

Miten kysely toimii#

  • from_timestamp on millisekunteja aikakauden alusta. Kysely palauttaa tapahtumat, joiden created_at_timestamp on tiukasti suurempi.
  • Aloita invoke-vastauksen created_at-arvosta, joka on merkkijonona lähetettävä millisekuntiarvo, joten muunna se kokonaisluvuksi. Käytä arvoa 0 saadaksesi koko istunnon. Älä käytä create-vastauksen created_at-arvoa, joka on päivämäärä ja kellonaika, ei millisekunteja.
  • Siirrä jokaisen kyselyn jälkeen from_timestamp uusimman tapahtuman created_at_timestamp-arvoon miinus 1 ja ohita tapahtumat, joiden event_id on jo nähty. Saman millisekunnin aikana luodut tapahtumat voivat saapua eri kyselyissä. FlowHuntin chat-widget kysyy samalla tavalla.
  • Jokaisella tapahtumalla on event_type (ai, human tai system), action_type (message, loading, tool_call, failed, hook_waiting_for_input ja muita) sekä metadata. Vastauksen teksti on ai-tyypin message-tapahtumien metadata.message-kentässä.

FlowHunt ei lähetä erillistä “ajo valmis” -tapahtumaa. Kun ajoimme esimerkkejä yksivaiheista flowta vasten, kysely palautti system-tyypin loading-tapahtuman, sitten yhden ai-tyypin message-tapahtuman vastauksen kanssa, eikä sen jälkeen mitään. Siksi esimerkit pysähtyvät ensimmäiseen kyselyyn, joka ei tuo uusia tapahtumia vastauksen saavuttua, ja nostavat poikkeuksen tilassa failed. Jos flowsi lähettää useita viestejä tai odottaa syötettä tilassa hook_waiting_for_input, päätä oma lopetusehtosi.

Argumenttien järjestys muuttui kolmessa menetelmässä#

Järjestä nämä kolme kutsua uudelleen

v3-menetelmät laittavat polun parametrit ennen istuntotunniste-otsaketta. PHP:ssa ja Pythonissa, kun annat argumentit positionaalisesti, nämä kolme kutsua epäonnistuvat tyyppivirheeseen tai lähettävät hiljaisesti väärät arvot, ellet järjestä niitä uudelleen.

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)

Pythonissa anna avainsana-argumentit kaikkialla, esimerkiksi x_fh_session_id=session_id, jolloin järjestyksellä ei ole enää väliä. Python 4.0 myös tarkistaa argumenttien tyypit, joten from_timestamp-arvon on oltava int. Merkkijonon "0" välittäminen nostaa pydanticin ValidationError-poikkeuksen.

Muut rikkovat muutokset versiossa 4.0.0#

Nämä menetelmät olivat versiossa 3.19.1 ja ovat poissa versiosta 4.0.0, koska niiden taustalla olevat API-päätepisteet poistettiin tai muutettiin. PHP-menetelmien nimet ovat Python-nimien camelCase-muoto, esimerkiksi get_available_models muuttuu muotoon getAvailableModels.

Poistettu menetelmäPäätepisteMitä tehdä
AgentGridsApi.get_agent_grid_previewGET /v2/agent_grids/{agent_grid_id}/previewPoista kutsu.
CustomModelsApi.get_available_modelsGET /v2/custom-models/availablePoista kutsu.
FineTuningsApi.create_image_ft, delete_image_ft, search_image_fts, update_image_ft/v2/photo_ai/images/...Poista kutsut.
WorkspacesApi.update_workspace_auto_rechargePUT /v2/workspaces/{workspace_id}/auto-rechargePoista kutsu.
FlowBatchApi.export_csvGET /v2/flows/{flow_id}/batch/{batch_run_id}/export-csvKutsu start_export_csv (POST, sama polku) ja sitten get_export_csv_status (GET .../export-csv/{task_id}).

Myös Zendesk-kanavan, Shopify-laskutuksen, Replicaten ja SERP-pingback-verkkokoukkujen menetelmät poistettiin. Ne ovat FlowHuntin omien palvelimien saapuvia verkkokoukkuja, eivät koodisi tekemiä kutsuja.

Pidä istuntotunniste salassa#

Istuntotunniste on tunnistautumistieto

Kuka tahansa, jolla on istuntotunniste, voi lukea ja jatkaa kyseistä keskustelua. Älä kirjaa sitä lokiin, älä laita sitä URL-osoitteisiin tai kyselymerkkijonoihin äläkä lähetä sitä analytiikkaan. Kohtele sitä kuin lyhytikäistä salasanaa.

Entä v2?#

v2:n istuntoreitit ovat vanhentuneita SDK 4.0.0:sta alkaen ja poistuvat käytöstä 30. marraskuuta 2026. Siihen asti ne toimivat edelleen, ja ne on merkitty vanhentuneiksi API-viitteessä. SDK 4.0.0 sisältää edelleen v2-menetelmät. Pythonissa niiden kutsuminen nostaa DeprecationWarning-varoituksen. PHP:ssa ne on merkitty koodissa @deprecated-merkinnällä, jonka IDE:si tai staattinen analyysi nostaa esiin.