L'API Characters

FluidTalk génère les messages d'un personnage et suit la relation avec chaque lead ; il ne publie jamais rien lui-même. Votre connecteur lit le DM sur la plateforme, appelle l'API et délivre la réponse. La façon dont vous vous connectez à la plateforme reste entièrement votre affaire.

Cette page est un résumé. La référence complète et versionnée, avec chaque endpoint, champ et code d'erreur ainsi que les deux SDK, se trouve dans la documentation de l'API Characters. L'API couvre :

POST /chat — le lead a envoyé un DM ; récupérez la réponse du personnage sous forme de liste ordonnée de bulles de chat
POST /triggers — ouvrez ou réorientez une conversation à partir d'un événement de la plateforme (réaction à une story, nouvel abonné, ou votre propre événement personnalisé)
POST /events — signalez un achat, un remboursement ou un impayé pour que le cycle de vie du lead bascule
GET /followups — récupérez les messages de relance proactifs du personnage pour les leads devenus silencieux
POST /comments — générez un commentaire public sous une publication, et des réponses imbriquées en dessous
POST /inbound-media — envoyez les octets d'une photo reçue du lead et obtenez une URL permanente à joindre au tour suivant

Authentification

Chaque requête porte un token de connecteur propre au personnage dans l'en-tête X-Connector-Token. Le token EST le personnage : il n'y a ni clé au niveau du compte ni identifiant de personnage à transmettre. Vous nommez la plateforme dans le corps, et le même token fonctionne sur toutes les plateformes où ce personnage tourne. Copiez-le depuis les paramètres de plateforme du personnage dans le tableau de bord ; il n'est affiché qu'une fois, traitez-le comme un mot de passe.

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"
  }'

Une réponse revient sous forme de liste ordonnée de bulles avec des délais réalistes. Envoyez-les une par une en respectant chaque délai, plutôt que de les concaténer en un seul message :

{
  "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..."
}

L'ancienne API de handshake est retirée

Si vous avez intégré une version antérieure de FluidTalk, vous avez peut-être encore du code utilisant X-API-Key / ft_sk_live_... l'authentification contre /api/v1/bot/chat, /api/v1/bot/action et /api/v1/bot/upload. Ces endpoints n'existent plus et renvoient désormais 404. Passez à l'API Characters ci-dessus : tokens de connecteur, corps de requête JSON et réponses en bulles.

SDK

Les deux SDK officiels effectuent l'appel, déballent l'enveloppe de la réponse et lèvent des erreurs typées pour vous. Ils sont publiés sous le même nom sur npm et 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);
}

Étapes suivantes

Commencez par le démarrage rapide dans la documentation complète de l'API. Pour mettre un personnage en production sur une plateforme, voir Mise en production. Pour l'usage mesuré, le portefeuille et la gestion d'un 402, voir Facturation.