Developer API

Översikt

FluidTalk handshake-API:t låter en extern bot driva en persona+motor i realtid. För varje inkommande meddelande (eller händelse) gör du ett litet HTTP-anrop; FluidTalk returnerar nästa svar, fotot att skicka och konversationstillståndet. Du behåller din egen logik — när du ska öppna en chatt, när du ska följa upp, var du ska leverera meddelanden — och FluidTalk bestämmer vad personan säger härnäst.

Alla endpoints finns under bas-URL:en https://api-talk.fluidvip.com och använder multipart/form-data så att du kan skicka text och en binär bild i en enda förfrågan. Om du helst slipper skriva HTTP-, autentiserings- och multipart-lagret för hand finns ett TypeScript och ett Python SDK som båda omsluter dessa endpoints.

Autentisering

Autentisera varje förfrågan med din hemliga nyckel i X-API-Key headern. En nyckel är avgränsad till en persona och en motor — den kombinationen talar om för FluidTalk vilken karaktär som ska spelas och vilken konversationslogik som ska köras. Du skapar och kopplar nycklar i instrumentpanelen (Wiring Lab); API-nycklar ger enbart konversationsåtkomst och kan inte ändra din strategi, personas eller fakturering.

X-API-Key: ft_sk_live_YOUR_KEY

POST /api/v1/bot/chat

Använd detta när ett lead skickar ett meddelande först (ett inkommande DM) eller för att fortsätta en pågående konversation. Det första inkommande meddelandet för ett nytt target öppnar vid motorns standardstartfas; återanvänd samma target för samma lead och motorn behåller sin fas och sitt tillstånd mellan varven.

Formulärfält:

• target (obligatoriskt) — leadets användarnamn. Återanvänd det för att fortsätta samma konversation.
• message (obligatoriskt) — leadets meddelandetext.
• own_username (valfritt) — ditt avsändarkonto, används för spårning och filtrering av dubbletter av leads.
• image_url (valfritt) — en URL till en bild som AI:n ska “se” för visuell kontext.
• file (valfritt) — en binär bild, som ett alternativ till image_url.

Svaret innehåller:

• reply — den fullständiga svarstexten.
• replies[] — svaret uppdelat i bubblor; skicka varje som ett eget meddelande.
• should_send_photo / photo_url — när should_send_photo är sant, hämta photo_url och skicka det som en bild.
• session_id — konversationsidentifieraren.
• ignored / ignore_reason — när ignored är sant, skicka ingenting (se Beteenden nedan).

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

Använd detta för att utlösa motordrivna beteenden snarare än att vidarebefordra ett inkommande meddelande. action fältet väljer beteendet:

• OUTREACH — starta en helt ny kall konversation (en AI-öppning). Bifoga en profilskärmbild via file låter motorn läsa visuella ledtrådar.
• FOLLOW_UP — skicka en kontextuell påminnelse när ett lead försvinner. Kräver en befintlig konversation för det target (annars 404).
• ENTRY_POINT — utlös en anpassad händelsedriven ingång. Ange entry_type (måste finnas i motorns konfiguration) och en valfri entry_context JSON-sträng.

Formulärfält:

• target (obligatoriskt) — leadets användarnamn.
• action (obligatoriskt) — OUTREACH | FOLLOW_UP | ENTRY_POINT.
• own_username (valfritt) — ditt avsändarkonto.
• image_url (valfritt) — bild-URL för visuell kontext.
• entry_type (ENTRY_POINT) — den konfigurerade ingangsidentifieraren.
• entry_context (ENTRY_POINT, valfritt) — en JSON-sträng med kontext för händelsen.
• file (valfritt) — en binär bild.

Svaret innehåller:

• session_id — konversationsidentifieraren.
• message — meddelandet att skicka (kan vara tomt när en aktiv chatt fortsatte för en öppning).
• ignored / ignore_reason — när åtgärden avfärdades (se Beteenden nedan).
• continued / continued_reason — när en befintlig konversation fortsatte istället för att öppnas på nytt.

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

Ladda upp en bild och få tillbaka en värdbaserad URL som du kan återanvända som image_url i senare chat eller action anrop. Denna endpoint är tillgänglig för enbart API-nyckelautentisering (en instrumentpanelssession som försöker det får 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."
}

Beteenden

• ignored — förfrågan vidtogs avsiktligt inte. Den vanliga orsaken är lead_claimed_by_other_account: samma lead hanteras redan av ett annat avsändarkonto, så FluidTalk avfärdar dubbletten. När ignored är sant, skicka ingenting till leadet.
• continued — på action anrop fortsatte en befintlig konversation istället för att en ny öppnades (till exempel continued_reason: "conversation_already_active"). För en öppning kan meddelandet vara tomt — byt till chat endpoint för att hålla konversationen igång.

Felkoder

• 400 — nyckeln är inte avgränsad till en persona, eller sessionen är redan KLAR.
• 401 — saknas eller ogiltigt X-API-Key.
• 402 — ingen aktiv betald plan, eller slut på krediter för att starta en ny konversation.
• 403 — upload försök utan API-nyckelautentisering.
• 404 — persona hittades inte, eller en uppföljning utan befintlig konversation.
• 429 — hastighetsbegränsad. Respektera Retry-After svarshuvudet och backa.

Hastighetsgränser

Handshake-rutterna begränsas per API-nyckel och per IP på ett glidande per-minut-fönster så att en avvikande loop eller en läckt nyckel inte kan bränna obegränsade utgifter. Att överskrida endera gränsen returnerar 429 med en Retry-After header (i sekunder) — vänta så länge innan du försöker igen. Uppföljningar har dessutom sin egen nedkylningstid/gräns. Bygg in backoff i din integration snarare än att loopa tätt på 429.

SDK

Officiella klienter omsluter alla tre endpoints, X-API-Key headern och multipart-uppladdningar, och exponerar ignored / continued plus typade fel:

• 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ästa steg

Generera och avgränsa en API-nyckel, peka sedan din bot mot handskakningen — se Gå live. För hur konversationer mäts och vad en betald plan låser upp, se Fakturering.