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.
pip install --upgrade "flowhunt>=4,<5"PHP
Packagistin paketti on flowhunt/flowhunt-php-sdk. Se vaatii PHP 8.1:n tai uudemman.
composer require flowhunt/flowhunt-php-sdk:^4.0Siirrä neljässä vaiheessa#
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.
Nimeä jokainen istuntokutsu uudelleen
Lisää
_v3Python-menetelmän nimeen taiV3PHP-menetelmän nimeen. Menetelmien vastaavuus luettelee jokaisen parin.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ä.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 HTTP | v3 HTTP (istuntotunniste otsakkeessa X-FH-Session-Id) | Python 3.x → 4.0 | PHP 3.x → 4.0 |
|---|---|---|---|---|
| Aloita flow-istunto (API-avain) | POST /v2/flows/sessions/from_flow/create | POST /v3/flows/sessions/from_flow/create | create_flow_session → create_flow_session_v3 | createFlowSession → createFlowSessionV3 |
| Aloita chatbot-istunto (anonyymi) | POST /v2/flows/sessions/create | POST /v3/flows/sessions/create | create_chatbot_session → create_chatbot_session_v3 | createChatbotSession → createChatbotSessionV3 |
| Lähetä viesti | POST /v2/flows/sessions/{id}/invoke | POST /v3/flows/sessions/invoke | invoke_flow_response → invoke_flow_response_v3 | invokeFlowResponse → invokeFlowResponseV3 |
| Kysy tapahtumia | 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 |
| Peruuta ajo | POST /v2/flows/sessions/{id}/cancel | POST /v3/flows/sessions/cancel | cancel_flow_session → cancel_flow_session_v3 | cancelFlowSession → cancelFlowSessionV3 |
| Palaa edelliseen ankkuriin | POST /v2/flows/sessions/{id}/back | POST /v3/flows/sessions/back | go_back → go_back_v3 | goBack → goBackV3 |
| Laukaise chat-koukku | POST /v2/flows/sessions/{id}/hook | POST /v3/flows/sessions/hook | fire_chat_hook → fire_chat_hook_v3 | fireChatHook → fireChatHookV3 |
| Jatka odottavaa koukkua | POST /v2/flows/sessions/{id}/resume-hook | POST /v3/flows/sessions/resume-hook | resume_hook → resume_hook_v3 | resumeHook → resumeHookV3 |
| Aseta flown muuttujat | PATCH /v2/flows/sessions/{id}/variables | PATCH /v3/flows/sessions/variables | update_session_variables → update_session_variables_v3 | updateSessionVariables → updateSessionVariablesV3 |
| Listaa liitteet | GET /v2/flows/sessions/{id}/attachments | GET /v3/flows/sessions/attachments | get_attachments → get_attachments_v3 | getAttachments → getAttachmentsV3 |
| Lataa liite | POST /v2/flows/sessions/{id}/attachments | POST /v3/flows/sessions/attachments | upload_attachments → upload_attachments_v3 | uploadAttachments → uploadAttachmentsV3 |
| Poista liite | DELETE /v2/flows/sessions/{id}/attachments/{file_id} | DELETE /v3/flows/sessions/attachments/{file_id} | delete_attachment → delete_attachment_v3 | deleteAttachment → deleteAttachmentV3 |
| Viestin palaute | POST /v2/flows/sessions/{id}/feedback | POST /v3/flows/sessions/feedback | create_message_feedback → create_message_feedback_v3 | createMessageFeedback → createMessageFeedbackV3 |
| Lue artefakti | GET /v2/flows/sessions/{id}/artefacts/{artefact_id} | GET /v3/flows/sessions/artefacts/{artefact_id} | get_artefact_content → get_artefact_content_v3 | getArtefactContent → getArtefactContentV3 |
| Haku kirjoittaessa (uusi, ei v2:ssa) | ei mitään | POST /v3/flows/sessions/search | invoke_search_v3 | invokeSearchV3 |
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
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 # 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:
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(); // 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.
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"Aiemmin istuntotunniste oli osa jokaista polkua, esimerkiksi /v2/flows/sessions/$SESSION_ID/invoke. v3-kutsu ilman otsaketta palauttaa 401.
Miten kysely toimii#
from_timestampon millisekunteja aikakauden alusta. Kysely palauttaa tapahtumat, joidencreated_at_timestampon tiukasti suurempi.- Aloita invoke-vastauksen
created_at-arvosta, joka on merkkijonona lähetettävä millisekuntiarvo, joten muunna se kokonaisluvuksi. Käytä arvoa0saadaksesi koko istunnon. Älä käytä create-vastauksencreated_at-arvoa, joka on päivämäärä ja kellonaika, ei millisekunteja. - Siirrä jokaisen kyselyn jälkeen
from_timestampuusimman tapahtumancreated_at_timestamp-arvoon miinus 1 ja ohita tapahtumat, joidenevent_idon jo nähty. Saman millisekunnin aikana luodut tapahtumat voivat saapua eri kyselyissä. FlowHuntin chat-widget kysyy samalla tavalla. - Jokaisella tapahtumalla on
event_type(ai,humantaisystem),action_type(message,loading,tool_call,failed,hook_waiting_for_inputja muita) sekämetadata. Vastauksen teksti onai-tyypinmessage-tapahtumienmetadata.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.
| 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) |
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äätepiste | Mitä tehdä |
|---|---|---|
AgentGridsApi.get_agent_grid_preview | GET /v2/agent_grids/{agent_grid_id}/preview | Poista kutsu. |
CustomModelsApi.get_available_models | GET /v2/custom-models/available | Poista kutsu. |
FineTuningsApi.create_image_ft, delete_image_ft, search_image_fts, update_image_ft | /v2/photo_ai/images/... | Poista kutsut. |
WorkspacesApi.update_workspace_auto_recharge | PUT /v2/workspaces/{workspace_id}/auto-recharge | Poista kutsu. |
FlowBatchApi.export_csv | GET /v2/flows/{flow_id}/batch/{batch_run_id}/export-csv | Kutsu 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.