Docs

Developer API

For integrators wiring FluidTalk into their own bots and channels — what the Characters API does, how you authenticate, and where the full reference lives.

API Characters

FluidTalk генерирует сообщения персонажа и отслеживает отношения с каждым лидом; сам он никогда ничего не публикует. Ваш коннектор читает личное сообщение на площадке, вызывает API и доставляет ответ. Как именно вы подключаетесь к площадке — целиком ваше дело.

Эта страница — краткий обзор. Полный версионированный справочник со всеми эндпоинтами, полями и кодами ошибок, а также обоими SDK, находится в документации API Characters. API покрывает:

  • POST /chat — лид прислал сообщение; получите ответ персонажа в виде упорядоченного списка пузырей чата
  • POST /triggers — начните или направьте разговор по событию площадки (реакция на историю, новый подписчик или ваше собственное событие)
  • POST /events — сообщите о покупке, возврате или чарджбэке, чтобы жизненный цикл лида переключился
  • GET /followups — получите проактивные сообщения персонажа для лидов, которые замолчали
  • POST /comments — сгенерируйте публичный комментарий под постом и вложенные ответы под ним
  • POST /inbound-media — загрузите байты фото, присланного лидом, и получите постоянный URL для следующего хода

Аутентификация

Каждый запрос несёт токен коннектора, привязанный к персонажу, в заголовке X-Connector-Token. Токен И ЕСТЬ персонаж: нет ни ключа уровня аккаунта, ни идентификатора персонажа, который нужно передавать. Площадку вы указываете в теле запроса, и один и тот же токен работает на всех площадках, где этот персонаж запущен. Скопируйте его из настроек площадок персонажа в панели; он показывается один раз, так что относитесь к нему как к паролю.

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

Ответ возвращается упорядоченным списком пузырей с человеческими задержками. Отправляйте их по одному, выдерживая каждую задержку, а не склеивайте в одно сообщение:

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

Старое API handshake выведено из эксплуатации

Если вы интегрировались с более ранней версией FluidTalk, у вас может остаться код, использующий X-API-Key / ft_sk_live_... аутентификацию против /api/v1/bot/chat, /api/v1/bot/action и /api/v1/bot/upload. Этих эндпоинтов больше нет, теперь они возвращают 404. Переходите на API Characters выше: токены коннектора, тела запросов в JSON и ответы пузырями.

SDK

Оба официальных SDK выполняют вызов, распаковывают конверт ответа и бросают типизированные ошибки за вас. Они публикуются под одним и тем же именем в npm и 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);
}

Дальнейшие шаги

Начните с быстрого старта в полной документации API. Чтобы запустить персонажа на площадке, смотрите Запуск. По тарификации за использование, кошельку и обработке 402 смотрите Оплата.

Developer API: FluidTalk | FluidTalk