Developer API

Übersicht

Die FluidTalk-Handshake-API ermöglicht es einem externen Bot, eine Persona und Engine in Echtzeit zu steuern. Für jede eingehende Nachricht (oder jedes Ereignis) sendest du einen kleinen HTTP-Aufruf; FluidTalk gibt die nächste Antwort, das zu sendende Foto und den Gesprächsstatus zurück. Du behältst deine eigene Logik — wann du einen Chat öffnest, wann du nachfasst, wo du Nachrichten zustellst — und FluidTalk entscheidet, was die Persona als Nächstes sagt.

Alle Endpunkte befinden sich unter der Basis-URL https://api-talk.fluidvip.com und verwenden multipart/form-data damit du Text und ein Binärbild in einer einzigen Anfrage senden kannst. Wenn du die HTTP-, Auth- und Multipart-Ebene nicht selbst aufbauen möchtest, stehen ein TypeScript und ein Python SDK zur Verfügung, die diese Endpunkte kapseln.

Authentifizierung

Authentifiziere jede Anfrage mit deinem Secret-Key im X-API-Key Header. Ein Key ist an eine bestimmte Persona und eine bestimmte Engine gebunden — dieses Paar teilt FluidTalk mit, welchen Charakter es spielen und welche Gesprächslogik es ausführen soll. Keys werden im Dashboard (Wiring Lab) erstellt und verknüpft; API-Keys gewähren nur Gesprächszugang und können deine Strategie, Personas oder Abrechnung nicht ändern.

X-API-Key: ft_sk_live_YOUR_KEY

POST /api/v1/bot/chat

Nutze diesen Endpunkt, wenn ein Lead zuerst schreibt (eingehende DM) oder um ein laufendes Gespräch fortzusetzen. Die erste eingehende Nachricht für ein neues target startet in der Standard-Einstiegsphase deiner Engine; verwende dasselbe target für denselben Lead, und die Engine behält Phase und Status über alle Gesprächsrunden hinweg.

Formularfelder:

• target (erforderlich) — der Handle des Leads. Wiederverwendung setzt das gleiche Gespräch fort.
• message (erforderlich) — der Nachrichtentext des Leads.
• own_username (optional) — dein sendender Account, für Tracking und Duplikat-Lead-Filterung.
• image_url (optional) — eine URL zu einem Bild, das die KI für visuellen Kontext „sehen" soll.
• file (optional) — ein Binärbild, als Alternative zu image_url.

Die Antwort enthält:

• reply — den vollständigen Antworttext.
• replies[] — die Antwort in Sprechblasen aufgeteilt; sende jede als eigene Nachricht.
• should_send_photo / photo_url — wenn should_send_photo true ist, lade photo_url und sende es als Bild.
• session_id — die Gesprächs-ID.
• ignored / ignore_reason — wenn ignored true ist, sende nichts (siehe Verhalten unten).

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

Nutze diesen Endpunkt, um engine-gesteuerte Verhalten auszulösen, anstatt eine eingehende Nachricht weiterzuleiten. Das action Feld wählt das Verhalten aus:

• OUTREACH — startet ein brandneues Kaltgespräch (ein KI-Eröffner). Das Anhängen eines Profil-Screenshots via file ermöglicht der Engine, visuelle Hinweise zu lesen.
• FOLLOW_UP — sendet einen kontextuellen Nachfass, wenn ein Lead schweigt. Erfordert ein bestehendes Gespräch für dieses target (sonst 404).
• ENTRY_POINT — feuert einen benutzerdefinierten, event-gesteuerten Einstieg. Übergib entry_type (muss in der Engine-Konfiguration vorhanden sein) und einen optionalen entry_context JSON-String.

Formularfelder:

• target (erforderlich) — der Handle des Leads.
• action (erforderlich) — OUTREACH | FOLLOW_UP | ENTRY_POINT.
• own_username (optional) — dein sendender Account.
• image_url (optional) — Bild-URL für visuellen Kontext.
• entry_type (ENTRY_POINT) — der konfigurierte Einstiegsbezeichner.
• entry_context (ENTRY_POINT, optional) — ein JSON-String mit Kontext für das Ereignis.
• file (optional) — ein Binärbild.

Die Antwort enthält:

• session_id — die Gesprächs-ID.
• message — die zu sendende Nachricht (kann leer sein, wenn ein aktiver Chat für einen Eröffner fortgesetzt wurde).
• ignored / ignore_reason — wenn die Aktion verworfen wurde (siehe Verhalten unten).
• continued / continued_reason — wenn ein bestehendes Gespräch fortgesetzt statt neu geöffnet wurde.

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

Lade ein Bild hoch und erhalte eine gehostete URL zurück, die du als image_url in späteren chat oder action Aufrufen wiederverwenden kannst. Dieser Endpunkt ist nur für API-Key-Authentifizierung verfügbar (ein Dashboard-Session-Versuch gibt 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."
}

Verhalten

• ignored — die Anfrage wurde absichtlich nicht bearbeitet. Der häufigste Grund ist lead_claimed_by_other_account: derselbe Lead wird bereits von einem anderen sendenden Account verarbeitet, sodass FluidTalk das Duplikat verwirft. Wenn ignored true ist, sende dem Lead nichts.
• continued — bei action Aufrufen wurde ein bestehendes Gespräch fortgesetzt, anstatt ein neues zu öffnen (zum Beispiel continued_reason: "conversation_already_active"). Bei einem Eröffner kann die Nachricht leer sein — wechsle zum chat Endpunkt, um das Gespräch fortzuführen.

Fehlercodes

• 400 — der Key ist keiner Persona zugeordnet, oder die Session ist bereits DONE.
• 401 — fehlender oder ungültiger X-API-Key.
• 402 — kein aktiver bezahlter Plan oder zu wenig Credits für ein neues Gespräch.
• 403 — upload versuchter Zugriff ohne API-Key-Authentifizierung.
• 404 — Persona nicht gefunden, oder ein Nachfass ohne bestehendes Gespräch.
• 429 — Rate-Limit überschritten. Respektiere den Retry-After Response-Header und warte entsprechend.

Rate-Limits

Die Handshake-Routen werden pro API-Key und pro IP in einem gleitenden Fenster pro Minute gedrosselt, damit eine außer Kontrolle geratene Schleife oder ein geleakter Key keine unbegrenzte Ausgabe verursachen kann. Das Überschreiten einer der Grenzen gibt 429 zurück, mit einem Retry-After Header (in Sekunden) — warte so lange, bevor du es erneut versuchst. Nachfass-Aufrufe haben zusätzlich ihre eigene Abkühlzeit/Limit. Baue Backoff in deine Integration ein, anstatt in einer engen Schleife auf 429.

SDKs

Offizielle Clients kapseln alle drei Endpunkte, den X-API-Key Header und Multipart-Uploads und stellen ignored / continued sowie typisierte Fehler bereit:

• 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);

Nächste Schritte

Erstelle und ordne einen API-Key zu, dann richte deinen Bot auf den Handshake — siehe Live gehen. Wie Gespräche gemessen werden und was ein bezahlter Plan freischaltet, erfährst du unter Abrechnung.