Developer API

Visão geral

A API de handshake do FluidTalk permite que um bot externo controle um persona+engine em tempo real. Para cada mensagem recebida (ou evento) você faz uma pequena chamada HTTP; o FluidTalk retorna a próxima resposta, a foto a enviar e o estado da conversa. Você mantém sua própria lógica — quando abrir um chat, quando fazer o follow-up, onde entregar as mensagens — e o FluidTalk decide o que o persona diz em seguida.

Todos os endpoints ficam sob a URL base https://api-talk.fluidvip.com e usam multipart/form-data para que você possa enviar texto e uma imagem binária em uma única requisição. Se preferir não lidar manualmente com HTTP, auth e multipart, um SDK em TypeScript e um em Python encapsulam esses endpoints.

Autenticação

Autentique cada requisição com sua chave secreta no header X-API-Key . Uma chave é vinculada a um único persona e um único engine — esse par é o que diz ao FluidTalk qual personagem interpretar e qual lógica de conversa executar. Você cria e vincula chaves no dashboard (Wiring Lab); as chaves API concedem acesso apenas a conversas e não podem alterar sua estratégia, personas ou cobrança.

X-API-Key: ft_sk_live_YOUR_KEY

POST /api/v1/bot/chat

Use isso quando um lead envia a primeira mensagem (um DM recebido) ou para continuar uma conversa em andamento. O primeiro recebimento de um novo target abre na fase de início padrão do seu engine; reutilize o mesmo target para o mesmo lead e o engine mantém sua fase e estado entre os turnos.

Campos do formulário:

• target (obrigatório) — o identificador do lead. Reutilize para continuar a mesma conversa.
• message (obrigatório) — o texto da mensagem do lead.
• own_username (opcional) — sua conta de envio, usada para rastreamento e filtragem de leads duplicados.
• image_url (opcional) — uma URL de imagem que o AI deve "ver" para contexto visual.
• file (opcional) — uma imagem binária, como alternativa ao image_url.

A resposta inclui:

• reply — o texto completo da resposta.
• replies[] — a resposta dividida em bolhas; envie cada uma como sua própria mensagem.
• should_send_photo / photo_url — quando should_send_photo for verdadeiro, busque photo_url e envie como imagem.
• session_id — o identificador da conversa.
• ignored / ignore_reason — quando ignored for verdadeiro, não envie nada (veja Comportamentos abaixo).

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

Use isso para acionar comportamentos orientados pelo engine em vez de retransmitir uma mensagem recebida. O campo action seleciona o comportamento:

• OUTREACH — inicia uma conversa fria completamente nova (um opener do AI). Anexar uma captura de tela do perfil via file permite que o engine leia pistas visuais.
• FOLLOW_UP — envia um lembrete contextual quando um lead some. Requer uma conversa existente para aquele target (caso contrário, 404).
• ENTRY_POINT — aciona uma entrada orientada por evento personalizado. Passe entry_type (deve existir na configuração do engine) e um entry_context JSON opcional de contexto.

Campos do formulário:

• target (obrigatório) — o identificador do lead.
• action (obrigatório) — OUTREACH | FOLLOW_UP | ENTRY_POINT.
• own_username (opcional) — sua conta de envio.
• image_url (opcional) — URL de imagem para contexto visual.
• entry_type (ENTRY_POINT) — o identificador de entrada configurado.
• entry_context (ENTRY_POINT, opcional) — uma string JSON de contexto para o evento.
• file (opcional) — uma imagem binária.

A resposta inclui:

• session_id — o identificador da conversa.
• message — a mensagem a enviar (pode estar vazia quando uma conversa ativa foi continuada para um opener).
• ignored / ignore_reason — quando a ação foi descartada (veja Comportamentos abaixo).
• continued / continued_reason — quando uma conversa existente foi continuada em vez de uma nova ser aberta.

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

Faça upload de uma imagem e receba de volta uma URL hospedada que você pode reutilizar como image_url em chamadas chat ou action posteriores. Este endpoint está disponível apenas para autenticação por chave API (uma sessão do dashboard que tentar usá-lo recebe 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."
}

Comportamentos

• ignored — a requisição foi deliberadamente ignorada. O motivo mais comum é lead_claimed_by_other_account: o mesmo lead já está sendo atendido por outra conta de envio, então o FluidTalk descarta o duplicado. Quando ignored for verdadeiro, não envie nada ao lead.
• continued — em chamadas action uma conversa existente foi continuada em vez de uma nova ser aberta (por exemplo, continued_reason: "conversation_already_active"). Para um opener, a mensagem pode estar vazia — mude para o endpoint chat para continuar a conversa.

Códigos de erro

• 400 — a chave não está vinculada a um persona, ou a sessão já está CONCLUÍDA.
• 401 — header X-API-Key.
• 402 — nenhum plano pago ativo, ou sem créditos para iniciar uma nova conversa.
• 403 — upload tentativa sem autenticação por chave API.
• 404 — persona não encontrado, ou um follow-up sem conversa existente.
• 429 — limite de taxa excedido. Respeite o header Retry-After e aguarde.

Limites de taxa

As rotas de handshake são limitadas por chave API e por IP em uma janela deslizante por minuto, para que um loop fora de controle ou uma chave vazada não gere gastos ilimitados. Exceder qualquer um dos limites retorna 429 com um header Retry-After (em segundos) — aguarde esse tempo antes de tentar novamente. Follow-ups também têm seu próprio cooldown/limite. Construa backoff na sua integração em vez de fazer loop contínuo em 429.

SDKs

Os clientes oficiais encapsulam os três endpoints, o header X-API-Key e uploads multipart, e expõem ignored / continued além de erros 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 passos

Gere e vincule uma chave API, depois aponte seu bot para o handshake — veja Colocar em produção. Para entender como as conversas são medidas e o que um plano pago desbloqueia, veja Cobrança.