Developer API

Descripción general

La API de handshake de FluidTalk permite que un bot externo maneje una persona+motor en tiempo real. Por cada mensaje entrante (o evento) haces una pequeña llamada HTTP; FluidTalk devuelve la siguiente respuesta, la foto a enviar y el estado de la conversación. Tú mantienes tu propia lógica — cuándo abrir un chat, cuándo hacer seguimiento, dónde entregar los mensajes — y FluidTalk decide qué dice la persona a continuación.

Todos los endpoints están bajo la URL base https://api-talk.fluidvip.com y utilizan multipart/form-data para que puedas enviar texto e imagen binaria en una sola solicitud. Si prefieres no gestionar manualmente la capa HTTP, auth y multipart, hay un SDK de TypeScript y uno de Python que envuelven estos endpoints.

Autenticación

Autentica cada solicitud con tu clave secreta en el encabezado X-API-Key . Una clave está vinculada a una sola persona y a un solo motor — esa combinación es lo que le indica a FluidTalk qué personaje interpretar y qué lógica de conversación ejecutar. Creas y vinculas las claves en el panel (Wiring Lab); las claves API otorgan solo acceso a conversaciones y no pueden cambiar tu estrategia, personas ni facturación.

X-API-Key: ft_sk_live_YOUR_KEY

POST /api/v1/bot/chat

Úsalo cuando un lead escribe primero (un DM entrante) o para continuar una conversación en curso. El primer mensaje entrante de un nuevo target abre en la fase de inicio predeterminada de tu motor; reutiliza el mismo target para el mismo lead y el motor mantiene su fase y estado entre turnos.

Campos del formulario:

• target (requerido) — el identificador del lead. Reutílizalo para continuar la misma conversación.
• message (requerido) — el texto del mensaje del lead.
• own_username (opcional) — tu cuenta de envío, utilizada para seguimiento y filtrado de leads duplicados.
• image_url (opcional) — una URL a una imagen que la IA debe «ver» para contexto visual.
• file (opcional) — una imagen binaria, como alternativa a image_url.

La respuesta incluye:

• reply — el texto completo de la respuesta.
• replies[] — la respuesta dividida en burbujas; envía cada una como su propio mensaje.
• should_send_photo / photo_url — cuando should_send_photo es verdadero, obtén photo_url y envíalo como imagen.
• session_id — el identificador de la conversación.
• ignored / ignore_reason — cuando ignored es verdadero, no envíes nada (ver Comportamientos más abajo).

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

Úsalo para activar comportamientos impulsados por el motor en lugar de reenviar un mensaje entrante. El campo action selecciona el comportamiento:

• OUTREACH — inicia una conversación fría completamente nueva (un opener de IA). Adjuntar una captura de pantalla del perfil mediante file permite que el motor lea señales visuales.
• FOLLOW_UP — envía un recordatorio contextual cuando un lead desaparece. Requiere una conversación existente para ese target (de lo contrario, 404).
• ENTRY_POINT — activa una entrada impulsada por evento personalizado. Pasa entry_type (debe existir en la configuración del motor) y un entry_context JSON string opcional.

Campos del formulario:

• target (requerido) — el identificador del lead.
• action (requerido) — OUTREACH | FOLLOW_UP | ENTRY_POINT.
• own_username (opcional) — tu cuenta de envío.
• image_url (opcional) — URL de imagen para contexto visual.
• entry_type (ENTRY_POINT) — el identificador de entrada configurado.
• entry_context (ENTRY_POINT, opcional) — un JSON string de contexto para el evento.
• file (opcional) — una imagen binaria.

La respuesta incluye:

• session_id — el identificador de la conversación.
• message — el mensaje a enviar (puede estar vacío cuando se continuó un chat activo para un opener).
• ignored / ignore_reason — cuando la acción fue descartada (ver Comportamientos más abajo).
• continued / continued_reason — cuando se continuó una conversación existente en lugar de abrirse una nueva.

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

Sube una imagen y obtén de vuelta una URL alojada que puedes reutilizar como image_url en llamadas chat o action posteriores. Este endpoint está disponible solo para autenticación con clave API (una sesión del panel que lo intente obtiene 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."
}

Comportamientos

• ignored — la solicitud fue deliberadamente ignorada. El motivo más común es lead_claimed_by_other_account: el mismo lead ya está siendo atendido por otra cuenta de envío, por lo que FluidTalk descarta el duplicado. Cuando ignored es verdadero, no le envíes nada al lead.
• continued — en llamadas action , se continuó una conversación existente en lugar de abrir una nueva (por ejemplo, continued_reason: "conversation_already_active"). Para un opener el mensaje puede estar vacío — cambia al endpoint chat para seguir la conversación.

Códigos de error

• 400 — la clave no está vinculada a una persona, o la sesión ya está TERMINADA.
• 401 — falta o es inválido X-API-Key.
• 402 — sin plan de pago activo, o sin créditos para iniciar una nueva conversación.
• 403 — upload intentado sin autenticación de clave API.
• 404 — persona no encontrada, o un seguimiento sin conversación existente.
• 429 — límite de tasa excedido. Respeta el encabezado Retry-After y espera antes de reintentar.

Límites de tasa

Las rutas de handshake están limitadas por clave API y por IP en una ventana deslizante por minuto, para que un bucle descontrolado o una clave filtrada no genere un gasto ilimitado. Superar cualquiera de los límites devuelve 429 con un encabezado Retry-After (en segundos) — espera ese tiempo antes de reintentar. Los seguimientos tienen además su propio límite de frecuencia. Implementa backoff en tu integración en lugar de hacer bucles ajustados sobre 429.

SDKs

Los clientes oficiales envuelven los tres endpoints, el encabezado X-API-Key , y las subidas multipart, y exponen ignored / continued además de errores tipados:

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

Próximos pasos

Genera y vincula una clave API, luego apunta tu bot al handshake — ver Ir en vivo. Para entender cómo se miden las conversaciones y qué desbloquea un plan de pago, ver Facturación.