API Characters

FluidTalk generuje wiadomości postaci i śledzi relację z każdym leadem; sam nigdy niczego nie publikuje. Twój konektor czyta DM na platformie, wywołuje API i dostarcza odpowiedź. To, jak łączysz się z platformą, pozostaje wyłącznie Twoją sprawą.

Ta strona to streszczenie. Pełna, wersjonowana dokumentacja z każdym endpointem, polem i kodem błędu oraz obydwoma SDK znajduje się w dokumentacji API Characters. API obejmuje:

POST /chat — lead wysłał DM; pobierz odpowiedź postaci jako uporządkowaną listę dymków czatu
POST /triggers — otwórz lub pokieruj rozmowę na podstawie zdarzenia platformy (reakcja na relację, nowy obserwujący albo Twoje własne zdarzenie)
POST /events — zgłoś zakup, zwrot lub obciążenie zwrotne, żeby cykl życia leada się przełączył
GET /followups — pobierz proaktywne wiadomości odzyskujące dla leadów, którzy zamilkli
POST /comments — wygeneruj publiczny komentarz pod postem i zagnieżdżone odpowiedzi pod nim
POST /inbound-media — prześlij bajty zdjęcia wysłanego przez leada i otrzymaj trwały URL do dołączenia w następnej turze

Uwierzytelnianie

Każde żądanie niesie token konektora przypisany do postaci w nagłówku X-Connector-Token. Token JEST postacią: nie ma klucza na poziomie konta ani identyfikatora postaci do przekazania. Platformę wskazujesz w treści żądania, a ten sam token działa na każdej platformie, na której ta postać pracuje. Skopiuj go z ustawień platform danej postaci w panelu; pokazuje się tylko raz, więc traktuj go jak hasło.

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

Odpowiedź wraca jako uporządkowana lista dymków z ludzkimi opóźnieniami. Wysyłaj je pojedynczo, zachowując każde opóźnienie, zamiast sklejać w jedną wiadomość:

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

Stare API handshake zostało wycofane

Jeśli integrowałeś się ze starszą wersją FluidTalk, możesz mieć jeszcze kod używający X-API-Key / ft_sk_live_... uwierzytelniania wobec /api/v1/bot/chat, /api/v1/bot/action i /api/v1/bot/upload. Te endpointy już nie istnieją i zwracają teraz 404. Przejdź na API Characters powyżej: tokeny konektora, treści żądań w JSON i odpowiedzi w dymkach.

SDK

Oba oficjalne SDK wykonują wywołanie, rozpakowują kopertę odpowiedzi i zgłaszają typowane błędy za Ciebie. Są publikowane pod tą samą nazwą w npm i 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);
}

Następne kroki

Zacznij od szybkiego startu w pełnej dokumentacji API. Aby uruchomić postać na platformie, zobacz Wdrożenie. W sprawie rozliczeń za zużycie, portfela i obsługi 402 zobacz Płatności.