L'API Characters

FluidTalk genera i messaggi di un personaggio e tiene traccia della relazione con ogni lead; non pubblica mai nulla da sola. Il tuo connector legge il DM sulla piattaforma, chiama l'API e consegna la risposta. Come ti colleghi alla piattaforma resta interamente affar tuo.

Questa pagina è un riepilogo. Il riferimento completo e versionato, con ogni endpoint, campo e codice di errore più entrambi gli SDK, si trova nella documentazione dell'API Characters. L'API copre:

POST /chat — il lead ha mandato un DM; ottieni la risposta del personaggio come lista ordinata di bolle di chat
POST /triggers — apri o reindirizza una conversazione a partire da un evento della piattaforma (reazione a una storia, nuovo follower o un tuo evento personalizzato)
POST /events — segnala un acquisto, un rimborso o un chargeback così che il ciclo di vita del lead cambi
GET /followups — recupera i messaggi proattivi di riaggancio del personaggio per i lead rimasti in silenzio
POST /comments — genera un commento pubblico sotto un post e le risposte annidate sotto di esso
POST /inbound-media — carica i byte di una foto inviata dal lead e ottieni un URL permanente da allegare al turno successivo

Autenticazione

Ogni richiesta porta un token connector specifico del personaggio nell'header X-Connector-Token. Il token È il personaggio: non c'è una chiave a livello di account né un id di personaggio da passare. La piattaforma la indichi nel body, e lo stesso token vale su ogni piattaforma su cui quel personaggio gira. Copialo dalle impostazioni di piattaforma del personaggio nella dashboard; viene mostrato una sola volta, quindi trattalo come una password.

curl -X POST https://api-talk.fluidvip.com/api/v1/characters/chat \
  -H "X-Connector-Token: ftc_live_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "instagram",
    "handle": "mark",
    "message": "hey, saw your story"
  }'

La risposta torna come lista ordinata di bolle con ritardi simili a quelli umani. Inviale una alla volta, rispettando ogni ritardo, invece di concatenarle in un unico messaggio:

{
  "data": {
    "session_id": "ses_3f9a...",
    "bubbles": [
      { "text": "heyy you", "delay_ms": 1200, "image_url": null },
      { "text": "that story was just me being bored lol", "delay_ms": 2600, "image_url": null }
    ]
  },
  "request_id": "req_7c2e..."
}

La vecchia API handshake è dismessa

Se hai integrato una versione precedente di FluidTalk potresti avere ancora codice che usa X-API-Key / ft_sk_live_... autenticazione verso /api/v1/bot/chat, /api/v1/bot/action e /api/v1/bot/upload. Quegli endpoint non esistono più e ora restituiscono 404. Passa all'API Characters qui sopra: token connector, body di richiesta JSON e risposte a bolle.

SDK

Entrambi gli SDK ufficiali eseguono la chiamata, scartano l'envelope della risposta e sollevano errori tipizzati per te. Escono con lo stesso nome su npm e PyPI:

TypeScript: npm install fluidtalk
Python: pip install fluidtalk

import { FluidTalk } from "fluidtalk";

const ft = new FluidTalk({ token: process.env.FT_CONNECTOR_TOKEN! });

const reply = await ft.chat({ platform: "instagram", handle: "mark", message: "hey!" });
for (const bubble of reply.bubbles) {
  // wait bubble.delayMs, then send bubble.text (and bubble.imageUrl, if set)
  await sendDm("mark", bubble.text, bubble.imageUrl);
}

Prossimi passi

Parti dalla guida rapida nella documentazione completa dell'API. Per mettere un personaggio online su una piattaforma, vedi Andare live. Per l'uso a consumo, il portafoglio e la gestione di un 402, vedi Fatturazione.