Public comments & threaded replies

A FluidTalk character doesn't only run DMs — it can also speak in public, commenting on a post and then holding a threaded back-and-forth underneath that comment. This guide shows the two comment operations: writing a top-level comment on a post (POST /comments), and replying to the replies that land under it (POST /comments/reply), to the original poster or to other commenters, as many times as the thread keeps going.

As everywhere in the Characters API, you own the platform I/O: the API generates the character's comment text and tracks the relationship; your connector posts it. The API never posts anything itself.

All calls go to the production base URL https://api-talk.fluidvip.com/api/v1/characters and authenticate with your per-character connector token in the X-Connector-Token header (see authentication.md). The token is the character — there is no character_id; you name the platform in each request body, and the same token works for every platform that character runs on.

For the Person model behind cross-surface awareness (the same lead who DMs and comments is one persona), see concepts.md. For the exact field-by-field request/response shapes, see reference/comments.md and reference/comment-reply.md. Every response is wrapped in the standard { "data": …, "request_id": "req_…" } envelope and carries an X-Request-Id header — the shapes below show the inner data.

---

How a comment thread works

post                       a platform post (post_ref + caption/images/author)
└── character's comment     POST /comments  → the text you post under the post
    ├── reply (the OP)      POST /comments/reply → the character replies back
    └── reply (someone else) POST /comments/reply → the character replies, thread-aware

• A comment is a single top-level comment the character writes for a post. You identify the post by post_ref (the platform's unique id or URL) and pass what context you have about it.
• A thread is the character's comment plus the replies under it. Each incoming reply is a separate POST /comments/reply call. The character can reply more than once per thread, and to different commenters in the same thread — it stays consistent across the whole thread, and across other threads and DMs via the shared Person.

Generating a comment or a reply is a metered turn — see Billing. If the character owner's wallet can't cover it you get 402 before any model call, so you are never charged for a comment you didn't get.

---

Comment on a post

POST /comments generates a top-level comment for a post. Post the returned comment text yourself.

Name	Type	Required	Description
platform	string	Yes	The platform the post is on (e.g. "instagram"). Selects the character's bound comments workflow.
post_ref	string	Yes	The platform's unique id or URL for the post. Identifies the comment thread on later replies.
post	object	No	Context about the post the character is reacting to — see below.

The post object:

Name	Type	Required	Description
post.caption	string	No	The post's caption text.
post.image_urls	string[]	No	Image URLs on the post; described via vision so the comment can react to what's actually shown.
post.author_handle	string	No	The @username of whoever published the post — used for cross-surface recognition.

curl -X POST https://api-talk.fluidvip.com/api/v1/characters/comments \
  -H "X-Connector-Token: ftc_live_..." \
  -H "Content-Type: application/json" \
  -d '{
        "platform": "instagram",
        "post_ref": "https://instagram.com/p/Cxy12Ab34Cd/",
        "post": {
          "caption": "golden hour on the rooftop ✨",
          "image_urls": ["https://cdn.example.com/post-1.jpg"],
          "author_handle": "mark"
        }
      }'

from fluidtalk import FluidTalk

ft = FluidTalk(token="ftc_live_8f3c...")

result = ft.comment(
    platform="instagram",
    post_ref="https://instagram.com/p/Cxy12Ab34Cd/",
    caption="golden hour on the rooftop ✨",
    image_urls=["https://cdn.example.com/post-1.jpg"],
    author_handle="mark",
)
print(result.comment)          # post this text on the platform
print(result.recognized_lead)  # True if the author is already a known Person

import { FluidTalk } from "fluidtalk";

const ft = new FluidTalk({ token: "ftc_live_8f3c..." });

const result = await ft.comment({
  platform: "instagram",
  postRef: "https://instagram.com/p/Cxy12Ab34Cd/",
  caption: "golden hour on the rooftop ✨",
  imageUrls: ["https://cdn.example.com/post-1.jpg"],
  authorHandle: "mark",
});
console.log(result.comment);         // post this text on the platform
console.log(result.recognizedLead);  // true if the author is already a known Person

The SDKs take the post fields flat (caption, image_urls/imageUrls, author_handle/authorHandle) and assemble the nested post object for you. Over raw HTTP, send them nested under post as shown in the curl example.

The response:

{
  "data": {
    "ok": true,
    "comment": "obsessed with this fit 😍 where'd you get the jacket?",
    "recognized_lead": true,
    "aware": { "...": "cross-surface awareness summary" },
    "thread_id": "cth_7b21…"
  },
  "request_id": "req_2c9f…"
}

• comment is the text to post. recognized_lead is true when the post's author is a Person the character already knows. aware is a compact summary of what the character knows about them across surfaces (see below). thread_id is present once a thread exists, so you can correlate the replies that follow.

---

Reply in a thread

POST /comments/reply generates the character's reply to a reply under its comment. It can fire multiple times in one thread — to the original poster or to other commenters who join in.

Name	Type	Required	Description
platform	string	Yes	The platform the thread is on.
post_ref	string	Yes	The post whose thread this reply belongs to.
replier_handle	string	Yes	The @username of whoever replied.
reply_text	string	No	What they said — the text the character is responding to.
parent_comment_ref	string	No	The platform ref of the comment being replied to, to thread the reply correctly.
post	object	No	Post context (same shape as above), if the thread is new to the character.

curl -X POST https://api-talk.fluidvip.com/api/v1/characters/comments/reply \
  -H "X-Connector-Token: ftc_live_..." \
  -H "Content-Type: application/json" \
  -d '{
        "platform": "instagram",
        "post_ref": "https://instagram.com/p/Cxy12Ab34Cd/",
        "replier_handle": "mark",
        "reply_text": "you look unreal here 😍",
        "parent_comment_ref": "ig_comment_17985…"
      }'

result = ft.comment_reply(
    platform="instagram",
    post_ref="https://instagram.com/p/Cxy12Ab34Cd/",
    replier_handle="mark",
    reply_text="you look unreal here 😍",
    parent_comment_ref="ig_comment_17985…",
)

if result.reply is not None:        # None when the character chooses to skip
    print(result.decision, result.reply)

const result = await ft.commentReply({
  platform: "instagram",
  postRef: "https://instagram.com/p/Cxy12Ab34Cd/",
  replierHandle: "mark",
  replyText: "you look unreal here 😍",
  parentCommentRef: "ig_comment_17985…",
});

if (result.reply !== null) {        // null when the character chooses to skip
  console.log(result.decision, result.reply);
}

The response carries the character's decision and, when it decides to speak, the reply text:

{
  "data": {
    "ok": true,
    "decision": "drive_to_dm",
    "reply": "aw you're sweet 🙈 come dm me, way easier to chat there",
    "reason": "warm replier, time to move to DMs",
    "aware": { "...": "cross-surface awareness summary" }
  },
  "request_id": "req_4f10…"
}

The decision tells you what to do:

decision	Meaning
engage	Reply in-thread. reply holds the text to post under the thread.
drive_to_dm	Reply, but nudge the conversation toward DMs. Post reply, then continue in DMs via POST /chat.
skip	The character chose not to reply. reply is null — post nothing.

When reply is null (a skip), do not post anything. The optional reason is a short human-readable note about why the character decided the way it did; aware is the same cross-surface summary returned by POST /comments.

---

Cross-surface awareness

This is the headline of the Characters API: one coherent persona everywhere. A lead is identified by (platform, handle), and the same lead who comments on a post and who slides into the DMs resolves to a single Person. The character remembers across surfaces — DMs ↔ comments — and across multiple posts and threads.

• recognized_lead (on POST /comments) is true when the post's author_handle is already a known Person.
• aware (on both endpoints) is a compact summary of what the character already knows about that Person — earlier DMs, prior comments, other threads — so a public reply lands consistently with whatever was said in private, and vice-versa.

You don't wire any of this up. As long as you pass the real author_handle / replier_handle, awareness is resolved for you. For the full model, see Core concepts.

---

Driving a comment into a DM

When a thread is warming up, POST /comments/reply may return decision: "drive_to_dm". Post the reply text as usual — it gently steers the replier toward the DMs. When that person then messages the character, feed the inbound DM to POST /chat with the same (platform, handle). Because it's the same Person, the character picks the conversation up with full context from the public thread — no handoff state to manage on your side.

---

When comments aren't configured

Comments are an opt-in surface per character and per platform. If the character you addressed doesn't have comments enabled for that platform, both endpoints return a normal 200 success envelope whose data is a no-op marker rather than a comment:

{
  "data": { "ok": true, "ignored": "comments not configured" },
  "request_id": "req_5a08…"
}

This is not an error — there is no comment / reply field, so simply post nothing. It lets you call the comment endpoints unconditionally from your connector and let the dashboard decide whether the character speaks publicly on that platform.

---

Errors you may hit here

Status	error.code	Meaning in this context
400	invalid_request	Malformed body — e.g. missing post_ref or replier_handle, or invalid JSON.
401	invalid_token	Missing, invalid, or revoked connector token.
402	payment_required	The character owner's wallet can't cover the generation. Returned before any model call — top up in the dashboard and retry.
403	forbidden	The token isn't allowed to act on this platform/surface.
404	not_found	The thread or referenced comment isn't yours, or doesn't exist.
422	validation_error	A field failed validation (e.g. image_urls not a list of strings).
429	rate_limited	Too many requests — honor the Retry-After header.
500	internal_error	Something broke on our side; retry with backoff.

Note that comments not configured is a 200 no-op (above), not a 404. The SDKs raise typed errors — PaymentRequiredError for 402, NotFoundError for 404, ValidationError for 422, and so on. See errors.md for the full error model and rate-limits.md for per-token limits.

---

Related

• Conversations & DMs — drive the character's DM funnel with POST /chat; the other side of a drive_to_dm.
• Core concepts — the Person, sessions, and cross-surface awareness.
• Billing — comments and replies are metered turns; how 402 works.
• Authentication — your per-character connector token.
• Reference: comments · comment-reply
• Errors · Rate limits