Developer API

Panoramica

L'API handshake di FluidTalk permette a un bot esterno di guidare una persona+engine in tempo reale. Per ogni messaggio in entrata (o evento) effettui una semplice chiamata HTTP; FluidTalk restituisce la prossima risposta, la foto da inviare e lo stato della conversazione. Mantieni la tua logica — quando aprire una chat, quando fare follow-up, dove recapitare i messaggi — e FluidTalk decide cosa dice la persona.

Tutti gli endpoint si trovano sotto l'URL base https://api-talk.fluidvip.com e usano multipart/form-data così puoi inviare testo e un'immagine binaria in un'unica richiesta. Se preferisci non gestire manualmente lo strato HTTP, auth e multipart, un SDK TypeScript e uno Python wrappano entrambi questi endpoint.

Autenticazione

Autentica ogni richiesta con la tua chiave segreta nell'header X-API-Key . Una chiave è associata a una singola persona e un singolo engine — quella coppia dice a FluidTalk quale personaggio interpretare e quale logica conversazionale eseguire. Crei e colleghi le chiavi nella dashboard (Wiring Lab); le chiavi API concedono solo accesso alla conversazione e non possono modificare la tua strategia, le persona o la fatturazione.

X-API-Key: ft_sk_live_YOUR_KEY

POST /api/v1/bot/chat

Usa questo quando un lead scrive per primo (un DM in entrata) o per continuare una conversazione in corso. Il primo messaggio in entrata per un nuovo target apre nella fase di avvio predefinita dell'engine; riutilizza lo stesso target per lo stesso lead e l'engine mantiene la fase e lo stato tra i turni.

Campi del modulo:

• target (obbligatorio) — l'handle del lead. Riusalo per continuare la stessa conversazione.
• message (obbligatorio) — il testo del messaggio del lead.
• own_username (opzionale) — il tuo account mittente, usato per il tracciamento e il filtraggio dei lead duplicati.
• image_url (opzionale) — un URL a un'immagine che l'AI dovrebbe "vedere" per il contesto visivo.
• file (opzionale) — un'immagine binaria, come alternativa a image_url.

La risposta include:

• reply — il testo completo della risposta.
• replies[] — la risposta suddivisa in bolle; invia ciascuna come messaggio separato.
• should_send_photo / photo_url — quando should_send_photo è true, recupera photo_url e inviala come immagine.
• session_id — l'identificatore della conversazione.
• ignored / ignore_reason — quando ignored è true, non inviare nulla (vedi Comportamenti di seguito).

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

Usa questo per attivare comportamenti guidati dall'engine invece di trasmettere un messaggio in entrata. Il campo action seleziona il comportamento:

• OUTREACH — avvia una conversazione a freddo del tutto nuova (un opener AI). Allegare uno screenshot del profilo tramite file permette all'engine di leggere segnali visivi.
• FOLLOW_UP — invia un promemoria contestuale quando un lead sparisce. Richiede una conversazione esistente per quel target (altrimenti 404).
• ENTRY_POINT — attiva un evento personalizzato. Passa entry_type (deve esistere nella configurazione dell'engine) e un entry_context stringa JSON opzionale.

Campi del modulo:

• target (obbligatorio) — l'handle del lead.
• action (obbligatorio) — OUTREACH | FOLLOW_UP | ENTRY_POINT.
• own_username (opzionale) — il tuo account mittente.
• image_url (opzionale) — URL immagine per il contesto visivo.
• entry_type (ENTRY_POINT) — l'identificatore di entrata configurato.
• entry_context (ENTRY_POINT, opzionale) — una stringa JSON di contesto per l'evento.
• file (opzionale) — un'immagine binaria.

La risposta include:

• session_id — l'identificatore della conversazione.
• message — il messaggio da inviare (può essere vuoto quando una chat attiva è stata continuata per un opener).
• ignored / ignore_reason — quando l'azione è stata scartata (vedi Comportamenti di seguito).
• continued / continued_reason — quando una conversazione esistente è stata continuata invece di aprirne una nuova.

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

Carica un'immagine e ricevi un URL hosted riutilizzabile come image_url nelle successive chiamate chat o action . Questo endpoint è disponibile solo per autenticazione con chiave API (una sessione dashboard che tenta di usarlo riceve 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."
}

Comportamenti

• ignored — la richiesta è stata deliberatamente ignorata. Il motivo più comune è lead_claimed_by_other_account: lo stesso lead è già gestito da un altro account mittente, quindi FluidTalk scarta il duplicato. Quando ignored è true, non inviare nulla al lead.
• continued — nelle chiamate action , una conversazione esistente è stata continuata invece di aprirne una nuova (ad esempio continued_reason: "conversation_already_active"). Per un opener il messaggio potrebbe essere vuoto — passa all'endpoint chat per continuare la conversazione.

Codici di errore

• 400 — la chiave non è associata a una persona, oppure la sessione è già DONE.
• 401 — mancante o non valido X-API-Key.
• 402 — nessun piano attivo a pagamento, oppure crediti esauriti per avviare una nuova conversazione.
• 403 — upload tentativo senza autenticazione con chiave API.
• 404 — persona non trovata, oppure un follow-up senza conversazione esistente.
• 429 — rate limited. Rispetta l'header Retry-After e attendi prima di riprovare.

Limiti di frequenza

Le route handshake sono soggette a throttling per chiave API e per IP su una finestra scorrevole al minuto, così un loop incontrollato o una chiave trapelata non può generare spese illimitate. Superare uno dei due limiti restituisce 429 con un header Retry-After (in secondi) — attendi quel tempo prima di riprovare. I follow-up hanno inoltre il proprio cooldown/limite. Integra il backoff nella tua implementazione invece di ciclare strettamente su 429.

SDK

I client ufficiali wrappano tutti e tre gli endpoint, l'header X-API-Key e gli upload multipart, e restituiscono ignored / continued più errori tipizzati:

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

Passi successivi

Genera e associa una chiave API, poi punta il tuo bot sull'handshake — vedi Going live. Per come vengono misurate le conversazioni e cosa sblocca un piano a pagamento, vedi Fatturazione.