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

답장은 사람다운 지연이 붙은 순서 있는 말풍선 목록으로 돌아옵니다. 하나의 메시지로 합치지 말고, 각 지연을 지키며 하나씩 보내세요:

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