블루톡 기능 안내 > BlueTalk::블루톡 무료 실시간 채팅 위젯 · 1:1 DM

기능 상세

1. 핵심 기능 요약

BlueTalk는 웹사이트에서 실시간 채팅 기능을 손쉽게 붙일 수 있도록 설계된 플랫폼입니다.

실시간 전체 채팅 (Global) – 사이트 전체 사용자가 함께 대화하는 공용 채팅방
채널/방 채팅 – 게시판·페이지·카테고리별로 채널을 나누어 대화
1:1 DM – 회원 간 쪽지처럼 사용하는 실시간 개인 대화
이미지/파일 첨부 – 이미지 미리보기, 일반 파일 다운로드 지원
운영자/관리자 제재 – 채팅금지, 채널생성 금지 등 관리 기능
게스트 모드 – 비회원도 입장/읽기/쓰기 허용 여부를 세밀하게 설정

모든 기능은 JavaScript 위젯(bluetalk.js)과 중앙 서버(Node.js), 그리고 귀하의 웹 서비스(PHP/Node/Python 등)의 연동으로 동작합니다.

2. 채팅 타입 및 레이아웃

채팅 타입

구분	설명
전체 채팅	사이트 공용 대화방입니다. 접속한 모든 사용자가 함께 대화할 수 있습니다. 기본적으로 `mode: 'global'`로 동작합니다.
채널 채팅	게시판/페이지/카테고리별로 채널을 나누어 대화할 수 있습니다. 예) `channel_id = 'stock'`, `'coin'`, `'notice'` 등.
1:1 DM	회원 간 실시간 개인 대화입니다. 쪽지처럼 사용할 수 있으며, 읽음/안읽음 표시, 목록/세션 관리 등을 지원합니다.

레이아웃 타입

구분	설명
전체 화면	전체 페이지를 채팅 UI로 사용하는 모드입니다. 데스크탑/모바일 모두 메신저처럼 꽉 차게 사용할 수 있습니다.
내장형(위젯)	게시판 본문, 사이드바, 푸터 등에 일부 영역만 채팅을 붙이는 형태입니다. 예) <div id="bluetalk">를 카드 또는 패널 안에 넣어 사용하는 방식.
플로팅	화면 오른쪽 하단 등에 작은 버튼이나 창으로 띄우는 형태입니다. CSS만으로도 쉽게 구현할 수 있으며, 예제는 /ex/layout_float.php 에서 확인할 수 있습니다.

실제 레이아웃 예제는 예제 · 자료실에서 HTML/CSS 소스를 함께 제공할 예정입니다.

3. 사용자 · 권한 관리

BlueTalk는 사이트의 회원 시스템을 그대로 활용하여 사용자를 구분합니다.

1) 사용자 식별

user_id – 사이트의 회원 아이디 또는 PK
nickname – 채팅에 표시할 닉네임
user_key – 서버에서 생성한 서명/토큰 값 (user_id + 비밀키 등으로 생성)

2) 게스트(비회원) 정책

guest_mode – 게스트 사용자의 접속 허용 여부
guest_global – 게스트의 전체 채팅 쓰기 허용 여부
guest_channel – 게스트의 채널 채팅 쓰기 허용 여부

3) 운영자 · 관리자 권한

채팅금지 – 특정 사용자에 대해 일정 시간 동안 채팅을 막을 수 있습니다.
채널 생성 금지 – 임의의 방/채널 생성 기능을 막을 수 있습니다. (옵션)
슈퍼 관리자 – 사이트 전역에서 제재/해제 권한을 가지는 상위 관리자 개념입니다.

운영자 메뉴 및 제재 관련 UI는 JS 위젯에 기본 포함되어 있으며, 실제 판정/저장은 BlueTalk 서버에서 수행합니다.

4. 이미지 · 파일 첨부

채팅 입력창에서 이미지/파일을 첨부하면, 내부적으로는 다음과 같은 순서로 처리됩니다.

[1] 사용자가 파일을 선택
[2] JS 위젯이 /upload/chat-file 엔드포인트로 파일 업로드 (multipart/form-data)
[3] 서버는 DB 또는 저장소에 파일을 보관하고, file.id 등의 정보를 응답
[4] JS 위젯은 해당 file.id를 메시지 전송 payload에 포함
[5] 채팅창에서는 <img src="/chat-file/:id"> 또는 다운로드 링크로 렌더링

현재 파일 업로드 API의 기본 형태는 다음과 같습니다. (개요)

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",      // 또는 'file'
    "name": "example.png",
    "size": 102400,
    "mime": "image/png"
  }
}

실제 상세 파라미터와 에러 코드는 API 개요, 에러 코드 문서를 참고해 주세요.

5. JS 연동 포인트 (요약)

BlueTalk를 실제로 사용하기 위해서는 자바스크립트 초기화 코드에서 site_key / user_id / nickname / user_key를 넘겨주는 것이 핵심입니다.

현재 버전에서는 bluetalk.js가 전역 window 값을 읽어들이고, new BlueTalk(...)로 초기화하는 구조를 사용합니다.

window.SITE_KEY          = "발급받은_site_key";
window.GLOBAL_USER_ID    = "회원아이디_또는_PK";
window.GLOBAL_USER_KEY   = "서버에서_생성한_user_key";
window.GLOBAL_NICKNAME   = "표시할_닉네임";

const bt = new BlueTalk({
    mode:     'global',   // 또는 'channel', 'dm'
    targetId: 'bluetalk'
});
bt.init();

6. 커스터마이징 & 디자인

BlueTalk는 기본적으로 독립된 CSS 네임스페이스를 사용하여, 기존 사이트 디자인과 최대한 충돌하지 않도록 설계되었습니다.