Die Characters-API

FluidTalk erzeugt die Nachrichten eines Charakters und verfolgt die Beziehung zu jedem Lead; es postet nie selbst etwas. Dein Connector liest die DM auf der Plattform, ruft die API auf und stellt die Antwort zu. Wie du dich mit der Plattform verbindest, bleibt vollständig deine Sache.

Diese Seite ist eine Zusammenfassung. Die vollständige, versionierte Referenz mit jedem Endpoint, Feld und Fehlercode sowie beiden SDKs steht in der Characters-API-Dokumentation. Die API deckt ab:

POST /chat — der Lead hat eine DM geschickt; hol die Antwort des Charakters als geordnete Liste von Chat-Bubbles
POST /triggers — eröffne oder lenke ein Gespräch aus einem Plattform-Event heraus (Story-Reaktion, neuer Follower oder dein eigenes Custom-Event)
POST /events — melde einen Kauf, eine Rückerstattung oder ein Chargeback, damit der Lifecycle des Leads umspringt
GET /followups — hol die proaktiven Reaktivierungsnachrichten des Charakters für Leads, die verstummt sind
POST /comments — erzeuge einen öffentlichen Kommentar unter einem Post und verschachtelte Antworten darunter
POST /inbound-media — lade die Bytes eines Fotos hoch, das der Lead geschickt hat, und erhalte eine dauerhafte URL für den nächsten Zug

Authentifizierung

Jede Anfrage trägt einen charakterspezifischen Connector-Token im Header X-Connector-Token. Der Token IST der Charakter: es gibt keinen Schlüssel auf Kontoebene und keine Charakter-ID zu übergeben. Die Plattform nennst du im Body, und derselbe Token funktioniert auf jeder Plattform, auf der dieser Charakter läuft. Kopiere ihn aus den Plattform-Einstellungen des Charakters im Dashboard; er wird nur einmal angezeigt, behandle ihn also wie ein Passwort.

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

Eine Antwort kommt als geordnete Liste von Bubbles mit menschlich wirkenden Verzögerungen zurück. Schick sie einzeln und halte jede Verzögerung ein, statt sie zu einer einzigen Nachricht zusammenzufassen:

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

Die alte Handshake-API ist abgeschaltet

Wenn du gegen eine frühere Version von FluidTalk integriert hast, hast du vielleicht noch Code, der X-API-Key / ft_sk_live_... Authentifizierung gegen /api/v1/bot/chat, /api/v1/bot/action und /api/v1/bot/upload nutzt. Diese Endpoints existieren nicht mehr und liefern jetzt 404. Wechsle auf die Characters-API oben: Connector-Tokens, JSON-Request-Bodies und Bubble-Antworten.

SDKs

Beide offiziellen SDKs führen den Aufruf aus, packen den Response-Envelope aus und werfen typisierte Fehler für dich. Sie erscheinen unter demselben Namen auf npm und 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);
}

Nächste Schritte

Fang mit dem Quickstart in der vollständigen API-Dokumentation. Um einen Charakter auf einer Plattform live zu bekommen, siehe Live gehen. Für verbrauchsabhängige Nutzung, das Guthaben und den Umgang mit einem 402 siehe Abrechnung.