Developer API

Overzicht

De FluidTalk-handshake API laat een externe bot een persona+engine in realtime aansturen. Voor elk inkomend bericht (of evenement) doe je een kleine HTTP-aanroep; FluidTalk geeft het volgende antwoord terug, de foto om te versturen, en de gespreksstand. Je houdt je eigen logica — wanneer een chat te openen, wanneer een follow-up te sturen, waar berichten af te leveren — en FluidTalk bepaalt wat de persona als volgende zegt.

Alle endpoints bevinden zich onder de basis-URL https://api-talk.fluidvip.com en gebruiken multipart/form-data zodat je tekst en een binaire afbeelding in één verzoek kunt sturen. Als je de HTTP, auth en multipart laag liever niet zelf implementeert, wikkelen een TypeScript en een Python SDK beide deze endpoints in.

Authenticatie

Authenticeer elk verzoek met je geheime sleutel in de X-API-Key header. Een sleutel is gekoppeld aan één persona en één engine — dat koppel vertelt FluidTalk welk karakter te spelen en welke gesprekslogica uit te voeren. Je maakt en koppelt sleutels in het dashboard (Wiring Lab); API-sleutels verlenen alleen gespreks toegang en kunnen je strategie, persona's of facturering niet wijzigen.

X-API-Key: ft_sk_live_YOUR_KEY

POST /api/v1/bot/chat

Gebruik dit wanneer een lead als eerste een bericht stuurt (een inkomend DM) of om een lopend gesprek voort te zetten. Het eerste inkomende bericht voor een nieuwe target opent bij de standaardstartfase van je engine; hergebruik dezelfde target voor dezelfde lead en de engine behoudt zijn fase en status over beurten heen.

Formuliervelden:

• target (verplicht) — het handle van de lead. Hergebruik het om hetzelfde gesprek voort te zetten.
• message (verplicht) — de berichttekst van de lead.
• own_username (optioneel) — je verzendaccount, gebruikt voor tracking en filtering op dubbele leads.
• image_url (optioneel) — een URL naar een afbeelding die de AI moet "zien" voor visuele context.
• file (optioneel) — een binaire afbeelding, als alternatief voor image_url.

Het antwoord bevat:

• reply — de volledige antwoordtekst.
• replies[] — het antwoord opgesplitst in berichten; stuur elk als een afzonderlijk bericht.
• should_send_photo / photo_url — wanneer should_send_photo waar is, haal photo_url op en stuur het als afbeelding.
• session_id — de gespreksidentificator.
• ignored / ignore_reason — wanneer ignored waar is, stuur niets (zie Gedragingen hieronder).

curl -X POST https://api-talk.fluidvip.com/api/v1/bot/chat \
  -H "X-API-Key: ft_sk_live_YOUR_KEY" \
  -F "target=@john_doe" \
  -F "own_username=@my_bot_account" \
  -F "message=wow you look great today!" \
  -F "file=@/path/to/screenshot.jpg"

{
  "reply": "Thank you so much! I was really feeling the outfit",
  "replies": ["Thank you so much!", "I was really feeling the outfit"],
  "should_send_photo": false,
  "photo_url": null,
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "ignored": false,
  "ignore_reason": null
}

POST /api/v1/bot/action

Gebruik dit om engine-gestuurde gedragingen te triggeren in plaats van een inkomend bericht door te geven. Het action veld selecteert het gedrag:

• OUTREACH — start een gloednieuw koud gesprek (een AI-opener). Een profielschermafbeelding bijvoegen via file laat de engine visuele signalen lezen.
• FOLLOW_UP — stuur een contextuele herinnering wanneer een lead niet reageert. Vereist een bestaand gesprek voor dat target (anders 404).
• ENTRY_POINT — activeer een aangepaste event-gestuurde ingang. Geef entry_type (moet bestaan in de engineconfiguratie) en een optionele entry_context JSON-tekenreeks door.

Formuliervelden:

• target (verplicht) — het handle van de lead.
• action (verplicht) — OUTREACH | FOLLOW_UP | ENTRY_POINT.
• own_username (optioneel) — je verzendaccount.
• image_url (optioneel) — afbeeldings-URL voor visuele context.
• entry_type (ENTRY_POINT) — de geconfigureerde ingangsidentificator.
• entry_context (ENTRY_POINT, optioneel) — een JSON-tekenreeks met context voor het evenement.
• file (optioneel) — een binaire afbeelding.

Het antwoord bevat:

• session_id — de gespreksidentificator.
• message — het te sturen bericht (kan leeg zijn wanneer een actief gesprek werd voortgezet voor een opener).
• ignored / ignore_reason — wanneer de actie werd genegeerd (zie Gedragingen hieronder).
• continued / continued_reason — wanneer een bestaand gesprek werd voortgezet in plaats van nieuw geopend.

curl -X POST https://api-talk.fluidvip.com/api/v1/bot/action \
  -H "X-API-Key: ft_sk_live_YOUR_KEY" \
  -F "target=@random_lead_99" \
  -F "action=ENTRY_POINT" \
  -F "own_username=@my_bot_account" \
  -F "entry_type=story_reaction" \
  -F "entry_context={\"reaction\": \"fire\"}"

{
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "message": "Hey! I saw your profile, looks interesting!",
  "ignored": false,
  "ignore_reason": null,
  "continued": false,
  "continued_reason": null
}

POST /api/v1/bot/upload

Upload een afbeelding en ontvang een gehoste URL die je opnieuw kunt gebruiken als image_url in latere chat of action aanroepen. Dit endpoint is beschikbaar voor uitsluitend API-sleutel-authenticatie (een dashboard-sessie die het probeert krijgt 403).

curl -X POST https://api-talk.fluidvip.com/api/v1/bot/upload \
  -H "X-API-Key: ft_sk_live_YOUR_KEY" \
  -F "file=@/path/to/screenshot.jpg"

{
  "url": "https://.../uploads/abc123.jpg",
  "message": "Context media uploaded successfully."
}

Gedragingen

• ignored — het verzoek werd bewust niet uitgevoerd. De gebruikelijke reden is lead_claimed_by_other_account: dezelfde lead wordt al afgehandeld door een ander verzendaccount, dus FluidTalk verwijdert de duplicaat. Wanneer ignored waar is, stuur niets naar de lead.
• continued — bij action aanroepen werd een bestaand gesprek voortgezet in plaats van een nieuw gesprek geopend (bijvoorbeeld continued_reason: "conversation_already_active"). Voor een opener kan het bericht leeg zijn — schakel over naar het chat endpoint om het gesprek gaande te houden.

Foutcodes

• 400 — de sleutel is niet aan een persona gekoppeld, of de sessie is al KLAAR.
• 401 — ontbrekende of ongeldige X-API-Key.
• 402 — geen actief betaald abonnement, of onvoldoende credits voor een nieuw gesprek.
• 403 — upload geprobeerd zonder API-sleutel-authenticatie.
• 404 — persona niet gevonden, of een follow-up zonder bestaand gesprek.
• 429 — snelheidslimiet overschreden. Respecteer de Retry-After antwoordheader en wacht even.

Snelheidslimieten

De handshake-routes zijn gethrotteld per API-sleutel en per IP op een sliding per-minuut venster zodat een ontspoorde lus of een gelekt sleutel geen onbeperkte kosten kan veroorzaken. Het overschrijden van een van beide limieten geeft 429 terug met een Retry-After header (in seconden) — wacht zo lang voordat je opnieuw probeert. Follow-ups hebben bovendien hun eigen cooldown/limiet. Bouw backoff in je integratie in in plaats van strak te loopen op 429.

SDK's

Officiële clients wikkelen alle drie de endpoints, de X-API-Key header en multipart-uploads in, en bieden ignored / continued plus getypeerde fouten:

• TypeScript — npm install @fluidtalk/sdk
• Python — pip install fluidtalk

import { FluidTalk } from "@fluidtalk/sdk";

const ft = new FluidTalk({ apiKey: process.env.FT_API_KEY!, ownUsername: "@my_account" });

const res = await ft.inboundChat({ target: "@john", message: "hey, saw your post!" });
for (const bubble of res.replies) await myChat.send("@john", bubble);
if (res.shouldSendPhoto && res.photoUrl) await myChat.sendImage("@john", res.photoUrl);

Volgende stappen

Genereer en koppel een API-sleutel, en wijs je bot daarna naar de handshake — zie Live gaan. Voor informatie over hoe gesprekken worden gemeten en wat een betaald abonnement ontsluit, zie Facturering.