개발자 문서

API 문서

VibeBot API는 OpenAI Chat Completions와 와이어 호환입니다. 기존 OpenAI SDK에서 baseURL만 바꾸고 model 자리에 챗봇 ID를 넣으면 그대로 동작합니다.

붙이는 법

쓰는 스택을 고르세요.

index.html — </body> 바로 위에

<script src="https://vibebot.store/w.js" data-id="agt_9f2c"></script>

붙여넣고 새로고침하면 오른쪽 아래에 챗 버튼이 생깁니다. 끝.

엔드포인트

베이스 URL: https://vibebot.store/v1

POST /v1/chat/completions

curl https://vibebot.store/v1/chat/completions \
  -H "content-type: application/json" \
  -H "authorization: Bearer vb_sk_..." \
  -d '{
    "model": "agt_9f2c",
    "messages": [{"role": "user", "content": "환불 되나요?"}],
    "stream": false
  }'

응답 — OpenAI 호환 + vibebot 확장

{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "model": "agt_9f2c",
  "choices": [{
    "index": 0,
    "message": { "role": "assistant", "content": "배송 후 7일 이내면 가능합니다." },
    "finish_reason": "stop"
  }],
  "usage": { "prompt_tokens": 812, "completion_tokens": 24, "total_tokens": 836 },

  "vibebot": {
    "sources": [{ "id": "chk_1", "title": "환불 정책", "url": "...", "score": 8.3 }],
    "confidence": 0.91,
    "escalate": false
  }
}

vibebot 확장 필드는 OpenAI 클라이언트를 통과해도 살아남습니다. escalate가 true면 확신도가 낮다는 뜻이니 사람에게 넘기세요.

스트리밍

stream: true를 주면 OpenAI 스타일 SSE로 옵니다. 마지막 청크에만 vibebot 필드가 실리고, data: [DONE]으로 끝납니다.

인증

• 서버에서 호출 — Authorization: Bearer vb_sk_... (설정에서 발급)
• 브라우저 위젯 — 키 불필요. 챗봇 ID만 있으면 되고, 대시보드에서 허용 도메인을 지정합니다.

에러

HTTP	code	언제
`400`	`invalid_request_error`	요청 형식이 잘못됨 (model 누락, messages 비어 있음 등)
`401`	`origin_not_allowed`	허용 목록에 없는 도메인에서 위젯 호출
`402`	`quota_exceeded`	이번 달 메시지 한도 소진 — 업그레이드 필요
`404`	`agent_not_found`	존재하지 않는 챗봇 ID
`429`	`rate_limit_exceeded`	분당 요청 초과 — Retry-After 헤더 참고
`500`	`upstream_error`	모델 호출 실패

헤드리스 모드

위젯 UI 대신 훅만 쓰고 화면은 직접 만들 수 있습니다.

useVibeBot()

import { useVibeBot } from '@vibebot/react'

function MyChat() {
  const { messages, send, isLoading, sources } = useVibeBot({
    agentId: 'agt_9f2c',
  })

  return (
    <div>
      {messages.map((m, i) => <p key={i}>{m.content}</p>)}
      <button onClick={() => send('안녕')}>보내기</button>
    </div>
  )
}