A API de Characters

A FluidTalk gera as mensagens de um personagem e acompanha o relacionamento com cada lead; ela nunca publica nada sozinha. Seu conector lê a DM na plataforma, chama a API e entrega a resposta. Como você se conecta à plataforma continua sendo problema seu.

Esta página é um resumo. A referência completa e versionada, com cada endpoint, campo e código de erro, além dos dois SDKs, está na documentação da API de Characters. A API cobre:

POST /chat — o lead enviou uma DM; obtenha a resposta do personagem como uma lista ordenada de balões de chat
POST /triggers — abra ou redirecione uma conversa a partir de um evento da plataforma (reação a story, novo seguidor ou seu próprio evento personalizado)
POST /events — informe uma compra, reembolso ou chargeback para que o ciclo de vida do lead mude
GET /followups — puxe as mensagens proativas de reengajamento do personagem para leads que ficaram quietos
POST /comments — gere um comentário público em um post e respostas encadeadas abaixo dele
POST /inbound-media — envie os bytes de uma foto que o lead mandou e receba uma URL permanente para anexar no próximo turno

Autenticação

Toda requisição leva um token de conector próprio do personagem no cabeçalho X-Connector-Token. O token é o personagem: não existe chave de conta nem id de personagem para passar. Você indica a plataforma no corpo, e o mesmo token vale para todas as plataformas em que aquele personagem roda. Copie das configurações de plataforma do personagem no painel; ele aparece uma única vez, então trate como senha.

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

A resposta volta como uma lista ordenada de balões com atrasos naturais. Envie um de cada vez, respeitando cada atraso, em vez de juntar tudo em uma única mensagem:

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

A antiga API de handshake foi aposentada

Se você integrou com uma versão anterior da FluidTalk, talvez ainda tenha código usando X-API-Key / ft_sk_live_... autenticação contra /api/v1/bot/chat, /api/v1/bot/action e /api/v1/bot/upload. Esses endpoints não existem mais e agora retornam 404. Migre para a API de Characters acima: tokens de conector, corpos de requisição JSON e respostas em balões.

SDKs

Os dois SDKs oficiais fazem a chamada, desempacotam o envelope da resposta e levantam erros tipados para você. Eles são publicados com o mesmo nome no npm e no 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);
}

Próximos passos

Comece pelo guia rápido na documentação completa da API. Para colocar um personagem no ar em uma plataforma, veja Entrar no ar. Para uso medido, a carteira e como tratar um 402, veja Faturamento.