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はキャラクターのメッセージを生成し、各リードとの関係を追跡します。自分では何も投稿しません。あなたのコネクターがプラットフォーム上のDMを読み、APIを呼び出し、返信を届けます。プラットフォームへの接続方法は完全にあなたの裁量です。

このページは概要です。すべてのエンドポイント、フィールド、エラーコードに加えて両方のSDKを含む、完全でバージョン管理されたリファレンスは Characters APIドキュメントにあります。APIがカバーする範囲:

  • POST /chat — リードからDMが届いたとき、キャラクターの返信を順序付きのチャットバブルのリストとして取得します
  • 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"
  }'

返信は、人間らしい遅延が付いた順序付きバブルのリストで返ります。1つのメッセージに連結せず、各遅延を守って1つずつ送信してください:

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