BlueTalk REST API 엔드포인트 > BlueTalk::블루톡 무료 실시간 채팅 위젯 · 1:1 DM · 웹 채팅 연동

REST API를 사용할 때의 공통 규칙입니다.

• Base URL : 예시) https://api.bluetalk.kr (실제 주소는 콘솔/문서에서 안내)
• 요청/응답 포맷 : 기본적으로 application/json
• 인증 : 필요에 따라 API 토큰/관리자 키 등이 추가될 수 있습니다.
• 응답 구조 : 성공/실패 여부를 ok 필드로 구분하는 형식을 권장합니다.

// 성공 예시
{
  "ok": true,
  "data": { ... }
}

// 실패 예시
{
  "ok": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "사람이 읽을 수 있는 에러 메시지"
  }
}

/auth/verify는 site_key · 도메인 · user_id · user_key 조합이 정상인지 서버에서 재검증할 때 사용하는 엔드포인트입니다.
WebSocket 연결 전에, 또는 특정 민감한 기능 사용 전에 호출할 수 있습니다.

요청

POST /auth/verify
Content-Type: application/json

{
  "site_key": "발급받은_사이트키",
  "domain": "https://www.example.com",
  "user_id": "testuser",
  "user_key": "서버에서_생성한_서명값"
}

성공 응답 예시

{
  "ok": true,
  "data": {
    "valid": true,
    "user_id": "testuser",
    "nickname": "테스트유저",
    "roles": ["member"],   // 예: member, manager, owner 등
    "expires_at": "2025-11-24T11:00:00Z"
  }
}

실패 응답 예시

{
  "ok": false,
  "error": {
    "code": "INVALID_USER_KEY",
    "message": "user_key validation failed"
  }
}

실제 서비스에서 이 엔드포인트를 필수로 호출할 필요는 없지만,
자체 서버에서 한 번 더 인증/로그를 관리하고 싶다면 적절히 활용할 수 있습니다.

채팅에서 사용할 이미지/파일을 업로드하는 엔드포인트입니다.
일반적으로는 JS SDK가 내부적으로 호출하지만, 필요하다면 직접 호출할 수도 있습니다.

요청

Content-Type: multipart/form-data 로 요청하며, 필드는 예시와 같습니다.

POST /files/upload
Content-Type: multipart/form-data

- file: (binary)
- site_key: 발급받은_사이트키
- user_id: testuser
- user_key: 서버에서_생성한_서명값
- channel_id: global

성공 응답 예시

{
  "ok": true,
  "data": {
    "file_id": "f_1234567890",
    "url": "https://cdn.bluetalk.kr/files/f_1234567890.png",
    "mime": "image/png",
    "size": 123456
  }
}

채팅 메시지에서는 url 또는 file_id를 사용해 이미지 미리보기/다운로드 링크를 구성하게 됩니다.
업로드 용량 제한, 허용 확장자, 보관 기간 등은 정책에 따라 달라질 수 있습니다.

BlueTalk 관리 콘솔에서 활용할 로그/통계 API는 단계적으로 추가될 예정입니다.
예를 들어 다음과 같은 엔드포인트가 포함될 수 있습니다.

• GET /stats/summary – 사이트별 일간 메시지 수, 동시접속 peak 등
• GET /stats/channels – 채널별 메시지 수/참여자 수
• GET /logs/errors – 최근 에러 로그/인증 실패 내역

실제 엔드포인트와 파라미터, 응답 구조는 기능 공개 시 별도 문서로 제공될 예정입니다.

REST API와 WebSocket 모두, 가능한 한 공통된 에러 구조를 사용합니다.

공통 에러 응답 예시

{
  "ok": false,
  "error": {
    "code": "INVALID_SITE_KEY",
    "message": "Unknown site_key"
  }
}

에러 코드, 의미, HTTP Status 매핑 등에 대한 자세한 내용은
에러 코드 · 응답 포맷 문서에서 확인할 수 있습니다.

일반적인 사용 시, 브라우저에서는 JS SDK(블루톡 위젯)만 사용해도 충분합니다.
REST API는 주로 다음과 같은 경우에 직접 사용할 수 있습니다.

• 서버 측에서 블루톡과의 연동 상태를 주기적으로 점검하고 싶을 때
• 별도의 관리자/통계 페이지에서 메시지/에러 기록을 집계하고 싶을 때
• 파일 업로드를 블루톡 API를 통해 직접 제어하고 싶을 때

JS에서 직접 REST API를 호출할 때는 CORS, 인증 토큰, Rate Limit 정책 등을 고려해야 합니다.
가능하다면 중간에 서버 프록시(백엔드)를 두고 호출하는 방식을 권장합니다.

REST API 구조를 확인했다면, 이제 에러 코드와 응답 포맷을 함께 보는 것이 좋습니다.

1. 에러 코드 · 응답 포맷
   공통 에러 구조, 주요 에러 코드, HTTP Status 매핑
2. API 개요 (복습용)
   전체 구조/흐름 다시 한 번 확인
3. 예제 · 자료실
   실제 언어별 연동 예제 코드 참고

API에 새로운 엔드포인트가 추가되거나 변경될 경우, 이 문서와 변경 로그를 통해 안내할 예정입니다.