Introduction to the FluidTalk Characters API

FluidTalk Characters are AI personas that run DM funnels and public comments across platforms — Instagram, Twitter/X, Reddit, Fanvue, TikTok, anywhere you can read and send messages. The Characters API lets your own bot or connector drive a character: push it the DMs a lead sends, get the character's reply, fire conversation triggers (a story reaction, a new follower, a custom event), generate public comments and threaded replies, and pull proactive follow-ups for leads who went quiet.

This page introduces the API and its mental model. When you're ready to make your first call, jump to the quickstart.

The connector model

The split is simple, and it's the most important thing to understand:

• You own the platform I/O. Reading the inbox, sending the DM, posting the comment, watching for a new follower — that's your connector's job. How you connect to the platform is your concern.
• The API generates the messages and tracks the relationship. You hand it an inbound DM (or a trigger, or a post to comment on); it returns the character's words and remembers everything as one consistent, cross-surface-aware persona.
• The API never posts anything. Every endpoint returns text for you to send. FluidTalk does not touch any platform on your behalf.

So a turn always looks like: your connector receives a DM → you call the API → the API returns bubbles → your connector sends them.

What you can do with a connector token

A per-character connector token gives your service everything it needs to run one character end-to-end:

• Chat — pass an inbound DM and get the character's reply as a list of human-like chat bubbles. See POST /chat.
• Fire triggers — turn a platform event (story reaction, new follower, custom entry point) into an opener that starts a cold conversation, or into the next stimulus in a live one. See POST /triggers.
• Generate comments — produce a top-level public comment for a post, threaded replies to people who reply, and replies that join a conversation between other people under a post the character never commented on. See POST /comments and POST /comments/engage.
• Pull follow-ups — drain the character's queue of proactive "hey stranger" rekindles for dormant leads, send each, then ack it. See GET /followups.
• Report money events — tell the API a purchase, refund, or chargeback happened so it can authoritatively flip the lead's lifecycle. See POST /events.

You can also run several accounts on one platform under the same character and have FluidTalk make sure only one of them ever replies to a given lead — see Multi-account dedup.

The mental model

A few resources, in a fixed relationship. Read this top-to-bottom and the rest of the docs will click into place.

1. Character — the AI persona. Your connector token authenticates as exactly one character. Its per-platform workflows (rapport, moves, comments, entry points) are bound in the dashboard. There is no account-level key and no character_id field — the token is the character.
2. Platform + handle — a lead is identified by the pair (platform, handle) (e.g. instagram + mark). You name the platform in every request body; the same token works across all platforms the character runs on. Re-using the same (platform, handle) resumes that lead's conversation.
3. Session — one conversation thread. It's auto-created or auto-resumed per (character, platform, handle), so you rarely pass session_id. See Sessions.
4. Person (cross-surface awareness) — the headline feature. The same lead who DMs the character and comments on its posts is one Person. The character stays in-character and remembers across surfaces (DM ↔ comments) and across multiple posts and threads. The recognized_lead and aware fields on comment responses reflect this. See The Person.
5. Bubbles — a reply is a list of short messages with human-like delays, not one blob. Send them in order, honoring delay_ms. See Bubbles.
6. Triggers / entry points — the configured places a conversation can start (outreach, story reaction, new follower, custom). You define them in the dashboard and fire them by event_id via /triggers.
7. Follow-ups — proactive re-engagement messages the character queues for dormant leads. It's a pull-queue: you pull pending rows, deliver them on the platform, then ack. See Follow-ups.
8. Connector token — the credential your service authenticates with. A token looks like ftc_.... You get it from the character's API tab in the FluidTalk dashboard; it stays visible to the account owner there any time (a token created before keys became viewable appears after its next use), so store it as a secret. Tokens are not created via the API. See Authentication.

Character  (your token = one persona, configured in the dashboard)
└── Platform + handle  →  Session (one conversation, auto-resumed)
    ├── Chat turn   → bubbles[]   (send them in order, with delays)
    ├── Trigger     → opener (cold) or next-turn stimulus (warm)
    ├── Comment     → public comment + threaded replies, or join
    │                 someone else's thread under any post
    └── Follow-up   → queued rekindle (pull → deliver → ack)
                          ▲
                     Person — the same lead across DMs + comments is
                     ONE memory; the character stays consistent everywhere

Base URLs

What	URL
API base	https://api-talk.fluidvip.com/api/v1/characters
Dashboard (get your connector token)	https://talk.fluidvip.com

Every route lives under the /api/v1/characters prefix, so the full base for any call is:

https://api-talk.fluidvip.com/api/v1/characters

Unlike a storage backend, there is no file or media-serving domain here — the API only ever returns text (and the occasional image_url of a photo the character chose from its own vault). Delivering those messages on the platform is your connector's job.

Versioning. The /v1 in the path is a contract. The server can evolve without breaking your integration: new fields and endpoints may be added under /api/v1/characters, but existing behavior won't change underneath you. A future major version would ship as a new prefix while /api/v1 stays frozen. Pin /api/v1/characters in your client (both SDKs do this for you). See Versioning.

How authentication works (in one line)

Send your character's connector token in the X-Connector-Token header. The Python and TypeScript SDKs add the header for you.

curl https://api-talk.fluidvip.com/api/v1/characters/followups?platform=instagram \
  -H "X-Connector-Token: ftc_8f3c..."

The token is per-character, not per-account, and works across every platform that character runs on — you select the workflow by naming the platform in each request body. There are no scopes to manage and no separate API key: the token authenticates as the character and authorizes exactly the actions in these docs for that character's bound platforms. Full details are in Authentication.

The response envelope at a glance

Every endpoint returns the same envelope, so your client can unwrap it once.

On success (HTTP 2xx), the real payload is always under data, and an X-Request-Id header carries the same id as request_id for support and log correlation:

{
  "data": { "session_id": "...", "bubbles": [] },
  "request_id": "req_..."
}

On error (HTTP 4xx/5xx):

{
  "error": {
    "code": "invalid_token",
    "message": "...",
    "type": "client_error",
    "request_id": "req_..."
  }
}

code maps one-to-one to the HTTP status (401 → invalid_token, 402 → insufficient_tokens, 429 → rate_limited, and so on), and type is client_error for 4xx or server_error for 5xx. The SDKs unwrap data for you and raise a typed exception per code. The full table is in Errors.

The shapes shown throughout the reference are the inner data object. Mentally wrap each one in { "data": ..., "request_id": "req_..." }.

What running a character costs

Running a character costs money. FluidTalk meters the real dollar cost of each generated turn, opener, comment, and follow-up, and charges the character owner's wallet: the actual cost at your plan's rate (the bigger your plan, the cheaper every conversation — see the pricing page). Balances and charges are in tokens at 1 token = $1, so a turn costs a small decimal like 0.00127932 — you pay for exactly what was used. You top up the wallet in the dashboard.

Billing-bearing responses include a billing object so you can track usage precisely (values in tokens, 1 token = $1):

{ "tokens": 0.000277186, "tokens_used": 0.00021322, "balance_after": 9.99972281, "collected": true }

When billing is enabled and the wallet can't cover a turn, the API returns 402 insufficient_tokens before any model call — so you're never charged for a refused turn. Handle it by topping up the wallet and surfacing the shortfall to the operator. See Billing.

Requests are also rate limited; over a limit returns 429 rate_limited with a Retry-After header. See Rate limits.

A note on what the API does not do

The Characters API generates messages and tracks the relationship — it never posts. It does not read your platform inbox, send a DM, publish a comment, or follow anyone; your connector does all platform I/O. Account-level operations — creating characters, binding per-platform workflows, issuing or rotating connector tokens, and managing your subscription, wallet, or team — live in the dashboard, not the API.

Next steps

• Quickstart — install an SDK and run your first inbound-DM-to-reply in a few minutes.
• Authentication — get your connector token and send it correctly.
• Core concepts — a deeper tour of characters, sessions, the cross-surface Person, bubbles, triggers, and follow-ups.
• POST /chat — the first call you'll make: a lead's DM in, the character's bubbles out.
• API reference — every endpoint, parameter, and field.
• SDK references: Python · TypeScript.