Docs

Developer API

For integrators wiring FluidTalk into their own bots and channels — what the Characters API does, how you authenticate, and where the full reference lives.

Characters API

FluidTalk 生成角色的消息并追踪与每条线索的关系，它自己从不发布任何内容。你的连接器在平台上读取私信、调用 API，再把回复送出去。你怎么连接平台，完全由你决定。

本页只是概要。包含每个端点、字段、错误码以及两个 SDK 的完整版本化参考，见 Characters API 文档。API 覆盖：

  • POST /chat — 线索发来私信时，获取角色的回复，形式是一组有序的聊天气泡
  • POST /triggers — 由平台事件（快拍互动、新粉丝，或你自定义的事件）开启或引导一段对话
  • POST /events — 上报购买、退款或拒付，让线索的生命周期状态切换
  • GET /followups — 拉取角色针对已冷场线索的主动唤回消息
  • POST /comments — 生成帖子下的公开评论，以及其下的嵌套回复
  • POST /inbound-media — 上传线索发来的照片字节，得到一个可附加到下一轮的永久 URL

身份验证

每个请求都在以下请求头中携带该角色专属的连接器令牌： X-Connector-Token。令牌就是角色本身：没有账户级密钥，也不需要额外传角色 ID。平台在请求体里指明，同一个令牌在该角色运行的所有平台上通用。请到仪表盘中该角色的平台设置里复制；它只显示一次，请当成密码对待。

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

回复会以一组带拟人延迟的有序气泡返回。请按每个延迟逐条发送，而不要拼成一条消息：

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

旧的 handshake API 已下线

如果你曾对接过更早版本的 FluidTalk，可能还有代码在用 X-API-Key / ft_sk_live_... 针对以下路径的认证： /api/v1/bot/chat, /api/v1/bot/action 和 /api/v1/bot/upload。这些端点已不存在，现在一律返回 404。请迁移到上面的 Characters API：连接器令牌、JSON 请求体、气泡式回复。

SDK

两个官方 SDK 都会替你发起调用、拆掉响应外层封装，并抛出带类型的错误。它们在 npm 和 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);
}

下一步

先从快速上手开始： 完整 API 文档. 要让角色在某个平台上真正跑起来，参见 上线. 关于按量计费、钱包以及 402 的处理，参见 账单.

Developer API: FluidTalk | FluidTalk