Developer API

The Characters API

FluidTalk generates a character's messages and tracks the relationship with each lead — it never posts anything itself. Your connector reads the DM on the platform, calls the API, and delivers the reply. How you connect to the platform stays entirely your concern.

This page is a summary. The complete, versioned reference — every endpoint, field, and error code, plus both SDKs — lives in the Characters API documentation. The API covers:

• POST /chat — the lead sent a DM; get the character's reply as an ordered list of chat bubbles
• POST /triggers — open or steer a conversation from a platform event (story reaction, new follower, or your own custom event)
• POST /events — report a purchase, refund, or chargeback so the lead's lifecycle flips
• GET /followups — pull the character's proactive re-engagement messages for leads who went quiet
• POST /comments — generate a public comment on a post, and threaded replies underneath it
• POST /inbound-media — upload the bytes of a photo the lead sent and get a permanent URL to attach to the next turn

Authentication

Every request carries a per-character connector token in the X-Connector-Token header. The token is the character: there is no account-level key and no character id to pass. You name the platform in the body, and the same token works across every platform that character runs on. Copy it from the character's platform settings in the dashboard — it is shown once, so treat it like a password.

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 reply comes back as an ordered list of bubbles with human-like delays. Send them one at a time, honouring each delay, rather than concatenating them into a single message:

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

SDKs

Both official SDKs make the call, unwrap the response envelope, and raise typed errors for you. They ship under the same name on npm and 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);
}

Next steps

Start with the quickstart in the full API documentation. To get a character live on a platform, see Going live. For metered usage, the wallet, and handling a 402, see Billing.