BlueTalk API 개요
이 문서는 BlueTalk가 어떤 구조로 동작하는지,
그리고 어떤 API(REST / WebSocket)를 제공하는지에 대한 전체 개요입니다.
자세한 인증 구조와 에러 포맷은 각각
인증 구조,
에러 코드 문서를 참고하세요.
BlueTalk는 크게 다음 세 영역으로 나뉩니다.
-
① JavaScript 위젯 (JS SDK)
사이트에 삽입하는bluetalk.js가 채팅 UI/UX, WebSocket 연결, 이벤트 처리 등을 담당합니다. -
② BlueTalk 서버 (Node.js)
사이트 정보, 사용자 정보, 채팅 메시지, DM, 파일 첨부, 제재(밴) 정보를 관리하는 중앙 서버입니다. -
③ 귀하의 웹 서비스
그누보드/아미나, PHP, Node, Python 등의 웹 애플리케이션입니다. 이곳에서 회원 인증, 로그인 상태, 닉네임, user_key 생성 등을 담당합니다.
실제 연동 시에는 귀하의 웹 서비스에서
site_key / user_id / nickname / user_key 정보를 만들어 HTML에 넣어주고,
JS SDK(BlueTalk)가 그 값을 사용해 BlueTalk 서버와 WebSocket으로 통신하게 됩니다.
BlueTalk 위젯이 동작하는 기본 흐름은 다음과 같습니다.
[1] 사용자 브라우저: 귀하의 웹 페이지 접속
- HTML에 <script src="https://bluetalk.kr/talk/bluetalk.js"> 포함
- <div id="bluetalk"></div> 등 위젯을 삽입할 DOM 준비
[2] 귀하의 웹 서버(PHP/Node/Python 등)
- 로그인 여부/회원 정보 확인
- site_key / user_id / nickname / user_key 생성
- JS에서 쓸 수 있도록 window.SITE_KEY, window.GLOBAL_USER_ID 등으로 내려줌
[3] 브라우저: JS SDK 초기화
- new BlueTalk({ mode: 'global', targetId: 'bluetalk' }) 생성
- 내부에서 window.* 값을 읽어 WebSocket 연결 준비
[4] BlueTalk 서버: 도메인 & site_key 매칭
- Origin/Referer, auth.site(=site_key)로 sites 테이블 조회
- 등록되지 않은 도메인/키 조합이면 연결 거부
[5] BlueTalk 서버: user_key 검증
- 필요 시 auth_url(옵션)로 귀하의 서버에 재검증 요청
- user_key가 서버에서 생성된 서명/토큰인지 확인
[6] WebSocket 연결 수립 (예: wss://server.bluetalk.kr)
- global/channel 입장, 메시지 수신, DM, presence, 제재 이벤트 처리
- user_key는 반드시 귀하의 서버에서 생성해야 합니다. (JS에서 임의 생성 금지)
- site_key는 도메인과 1:1 또는 1:N 매칭되며, 등록되지 않은 조합은 거부됩니다.
- 연결 완료 후에는 WebSocket 채널을 통해 채팅 메시지, DM, 제재 사항 등이 실시간으로 오갑니다.
더 자세한 인증 설계는 인증 구조 문서를 참고하세요.
BlueTalk는 다음과 같이 WebSocket과 REST(HTTP)를 나누어 사용합니다.
1) WebSocket (실시간)
- 실시간 채팅 메시지 송수신 (global / channel)
- 1:1 DM 메시지 송수신
- 입장/퇴장 정보(Presence)
- 운영자 제재 이벤트 (채팅금지, 채널생성금지 등)
- 기타 실시간 알림
2) REST (HTTP)
- 이미지/파일 업로드 (
POST /upload/chat-file) - 업로드된 파일 다운로드/표시 (
GET /chat-file/:id) - 헬스 체크 (
GET /health) - 추후 확장용 비실시간 API
채팅 내용 자체는 WebSocket으로 주고받고, 이미지/파일 같은 큰 데이터를 보낼 때만 REST 업로드 API를 사용합니다.
1) 파일 업로드: POST /upload/chat-file
채팅에서 이미지를 보내거나 파일을 첨부할 때 사용하는 엔드포인트입니다.
form-data 방식으로 요청하며, 필드 구조는 다음과 같습니다.
POST /upload/chat-file
Content-Type: multipart/form-data
- file : 업로드할 파일 (필수)
- site_key : 사이트 식별키 (필수)
- channel_key : 채널 식별값 (예: "global", "room_123" 등)
- user_id : 사용자 아이디 또는 PK
- user_key : 서버에서 생성한 서명/토큰
성공 응답 예시:
{
"ok": true,
"file": {
"id": 123,
"type": "image", // 'image' 또는 'file'
"name": "test.png",
"size": 102400,
"mime": "image/png"
}
}
실패 응답 예시:
{ "ok": false, "reason": "FILE_REQUIRED" }
{ "ok": false, "reason": "UNAUTHORIZED" }
{ "ok": false, "reason": "INTERNAL_ERROR" }
업로드가 성공하면 file.id를 이용해 채팅 메시지에 첨부할 수 있으며,
WebSocket 메시지에 첨부 정보가 함께 전송됩니다.
2) 파일 다운로드/표시: GET /chat-file/:id
업로드된 파일을 브라우저에 표시하거나 다운로드 받을 때 사용하는 엔드포인트입니다.
GET /chat-file/123 - :id 에 업로드된 파일의 id를 전달합니다. - 서버는 DB에 저장된 BLOB을 읽어 적절한 Content-Type과 함께 전송합니다. 예) <img src="https://server.bluetalk.kr/chat-file/123" alt="첨부이미지">
서버 내부 구현(파일을 DB에 저장하는지, 디스크에 저장하는지 등)은 변경될 수 있지만,
클라이언트 입장에서는 /chat-file/:id URL만 알고 있으면 됩니다.
WebSocket(예: wss://server.bluetalk.kr) 연결이 수립되면
다음과 같은 이벤트를 주고받게 됩니다.
- connection / disconnect : 소켓 연결/해제
- auth / join : 사이트/채널 인증 및 입장
- global:message / channel:message : 일반 채팅 메시지 송수신
- dm:message : 1:1 DM 메시지 송수신
- presence:update : 채널 접속자 리스트 갱신
- ban:update : 채팅금지/채널생성금지 등 제재 상태 변경
- system:notice : 시스템 알림/공지
자세한 이벤트 목록과 페이로드 구조는 WebSocket 이벤트 문서에서 다룹니다.
BlueTalk의 HTTP/REST 응답과 WebSocket 응답은 가능한 한 공통된 포맷을 따릅니다.
// 성공
{
"ok": true,
"data": { ... } // 또는 "file": { ... }, "result": { ... } 등
}
// 실패
{
"ok": false,
"error": {
"code": "ERROR_CODE",
"message": "사람이 읽을 수 있는 에러 메시지"
}
}
- ok :
true면 성공,false면 실패입니다. - code : 프로그램에서 분기 처리/로깅에 사용하는 에러 코드입니다.
- message : 사용자 또는 운영자가 읽을 수 있는 설명입니다.
구체적인 에러 코드 목록과 의미는 에러 코드 문서를 참고하세요.
실제 페이지에서는 bluetalk.js를 읽어온 뒤,
new BlueTalk(...) 형태로 초기화합니다.
<!-- 1) JS SDK 로드 -->
<script src="https://bluetalk.kr/talk/bluetalk.js"></script>
<!-- 2) 위젯 마운트 영역 -->
<div id="bluetalk"></div>
<!-- 3) 서버에서 내려준 값 바인딩 -->
<script>
window.SITE_KEY = "발급받은_site_key";
window.GLOBAL_USER_ID = "user123";
window.GLOBAL_USER_KEY = "서버에서_생성한_user_key";
window.GLOBAL_NICKNAME = "홍길동";
// 필요 시: window.GLOBAL_AVATAR_URL, window.GLOBAL_ADMIN_KEY 등도 설정
const bt = new BlueTalk({
mode: 'global', // 또는 'channel', 'dm'
targetId: 'bluetalk'
});
bt.init();
</script>
- BlueTalk는 JS SDK + 중앙 서버 + 귀하의 웹 서비스 세 부분으로 구성됩니다.
- 인증의 핵심은
site_key / user_id / nickname / user_key네 가지 값입니다. - 실시간 통신은 WebSocket, 파일 첨부 등은 REST(HTTP)를 사용합니다.
- HTTP 및 WebSocket 응답 포맷은 가능하면
{ ok, data|error }패턴을 따릅니다. - 자세한 내용은 인증, 에러, WebSocket 이벤트, 퀵스타트 문서를 순서대로 읽으면 전체 그림을 쉽게 이해할 수 있습니다.
이 문서는 큰 흐름을 잡기 위한 개요이며,
실제 구현 단계에서는 각 세부 문서와 예제 코드를 함께 참고하시길 권장드립니다.
