La API de Characters

FluidTalk genera los mensajes de un personaje y hace seguimiento de la relación con cada lead; nunca publica nada por su cuenta. Tu conector lee el DM en la plataforma, llama a la API y entrega la respuesta. Cómo te conectes a la plataforma sigue siendo asunto tuyo.

Esta página es un resumen. La referencia completa y versionada, con cada endpoint, campo y código de error, además de ambos SDKs, está en la documentación de la API de Characters. La API cubre:

POST /chat — el lead ha enviado un DM; obtén la respuesta del personaje como una lista ordenada de burbujas de chat
POST /triggers — abre o reconduce una conversación a partir de un evento de la plataforma (reacción a una historia, nuevo seguidor o tu propio evento personalizado)
POST /events — informa de una compra, reembolso o contracargo para que cambie el ciclo de vida del lead
GET /followups — recupera los mensajes proactivos de reenganche del personaje para los leads que se han quedado callados
POST /comments — genera un comentario público en una publicación, y respuestas anidadas debajo
POST /inbound-media — sube los bytes de una foto que envió el lead y obtén una URL permanente para adjuntarla en el siguiente turno

Autenticación

Cada petición lleva un token de conector propio del personaje en la cabecera X-Connector-Token. El token es el personaje: no hay clave a nivel de cuenta ni id de personaje que pasar. Indicas la plataforma en el cuerpo, y el mismo token sirve para todas las plataformas en las que corre ese personaje. Cópialo desde los ajustes de plataforma del personaje en el panel; se muestra una sola vez, así que trátalo como una contraseña.

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 respuesta llega como una lista ordenada de burbujas con retardos naturales. Envíalas de una en una, respetando cada retardo, en lugar de concatenarlas en un único mensaje:

{
  "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 antigua API de handshake está retirada

Si integraste una versión anterior de FluidTalk, puede que todavía tengas código que use X-API-Key / ft_sk_live_... autenticación contra /api/v1/bot/chat, /api/v1/bot/action y /api/v1/bot/upload. Esos endpoints ya no existen y ahora devuelven 404. Pásate a la API de Characters de arriba: tokens de conector, cuerpos de petición JSON y respuestas en burbujas.

SDKs

Ambos SDKs oficiales hacen la llamada, desenvuelven el sobre de la respuesta y lanzan errores tipados por ti. Se publican con el mismo nombre en npm y 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);
}

Siguientes pasos

Empieza por la guía rápida de la documentación completa de la API. Para poner un personaje en producción en una plataforma, consulta Puesta en marcha. Para el uso medido, el monedero y cómo gestionar un 402, consulta Facturación.