BlueTalk WebSocket 이벤트 > BlueTalk::블루톡 무료 실시간 채팅 위젯 · 1:1 DM · 웹 채팅 연동

• WebSocket URL : 예) wss://server.bluetalk.kr
• 브라우저에서는 bluetalk.js가 자동으로 WebSocket 연결을 관리합니다.
• 대부분의 경우 직접 WebSocket 코드를 작성할 필요 없이, JS SDK의 UI를 사용하면 됩니다.
• 이 문서는 “서버와 어떤 데이터가 오가는지”를 이해하기 위한 참고용입니다.

로우 레벨 WebSocket 클라이언트를 직접 구현할 수도 있지만, 공식적으로는 bluetalk.js 사용을 권장합니다.

BlueTalk WebSocket 메시지는 기본적으로 다음과 같은 공통 포맷을 가집니다.

{
  "type": "이벤트_타입",
  "data": {
      ...이벤트별_데이터...
  }
}

• type : 이벤트 이름 (예: "chat:message", "dm:message")
• data : 각 이벤트 타입별로 달라지는 실제 payload

이 외에, 필요에 따라 request_id, timestamp 등 공통 필드가 추가될 수 있습니다.

3-1. system:welcome (서버가 보내는 초기 환영 메시지 예시)

{
  "type": "system:welcome",
  "data": {
    "message": "welcome",
    "user_id": "testuser",
    "connected_at": "2025-11-24T10:00:00Z"
  }
}

3-2. system:error (에러 알림)

{
  "type": "system:error",
  "data": {
    "code": "INVALID_USER_KEY",
    "message": "user_key validation failed"
  }
}

실제 에러 코드/메시지 목록은 에러 코드 · 응답 포맷 문서를 참고하세요.

채널(방) 내에서 오가는 일반 채팅 메시지는 chat:message 타입으로 주고받습니다.

4-1. 클라이언트 → 서버 (메시지 전송 요청 예시)

{
  "type": "chat:message",
  "data": {
    "channel_id": "global",
    "content": "안녕하세요, 블루톡입니다!",
    "temp_id": "c_1732420000000"
  }
}

• channel_id : 채널/방 식별자 (예: "global", "board_free" 등)
• content : 전송할 텍스트 내용 (기본 텍스트/마크업 처리 후 서버가 기록)
• temp_id : 클라이언트 임시 ID (옵션, 응답과 매칭용)

4-2. 서버 → 클라이언트 (브로드캐스트 예시)

{
  "type": "chat:message",
  "data": {
    "message_id": "m_1234567890",
    "channel_id": "global",
    "user_id": "testuser",
    "nickname": "테스트유저",
    "avatar_url": "https://example.com/avatar/testuser.png",
    "content": "안녕하세요, 블루톡입니다!",
    "created_at": "2025-11-24T10:00:10Z",
    "is_me": true
  }
}

• message_id : 서버에서 발급한 메시지 고유 ID
• is_me : 이 메시지가 현재 클라이언트 본인이 보낸 것인지 여부에 대한 플래그
• avatar_url : 아바타 이미지 URL (설정에 따라 빈 문자열일 수도 있음)

실제로는 첨부파일, 스타일 정보 등 추가 필드가 포함될 수 있습니다.

특정 사용자와 1:1로 대화하는 DM은 dm:message 타입으로 주고받습니다.

5-1. 클라이언트 → 서버 (DM 전송 요청 예시)

{
  "type": "dm:message",
  "data": {
    "dm_key": "u_testuser:u_admin", 
    "content": "관리자님, 문의 드릴게 있습니다.",
    "temp_id": "d_1732420001000"
  }
}

• dm_key : DM 방을 식별하는 키 (예: "u_보내는유저:u_받는유저" 형태 등)
• content : 전송할 DM 텍스트
• temp_id : 클라이언트 임시 ID (옵션)

5-2. 서버 → 클라이언트 (DM 수신 예시)

{
  "type": "dm:message",
  "data": {
    "message_id": "dm_987654321",
    "dm_key": "u_testuser:u_admin",
    "from_user_id": "u_admin",
    "from_nickname": "관리자",
    "to_user_id": "u_testuser",
    "content": "네, 어떤 부분이 궁금하신가요?",
    "created_at": "2025-11-24T10:01:00Z",
    "is_me": false
  }
}

DM UI에서는 dm_key를 기준으로 대화를 묶어서 표시할 수 있으며,
실제 키 규칙은 서비스 구현에 따라 달라질 수 있습니다.

채널(방)에 입장/퇴장할 때는 channel:join, channel:leave 이벤트가 사용됩니다.

6-1. 채널 입장 요청 (클라이언트 → 서버)

{
  "type": "channel:join",
  "data": {
    "channel_id": "global"
  }
}

6-2. 채널 입장 브로드캐스트 (서버 → 클라이언트)

{
  "type": "channel:join",
  "data": {
    "channel_id": "global",
    "user_id": "testuser",
    "nickname": "테스트유저",
    "joined_at": "2025-11-24T10:02:00Z"
  }
}

6-3. 채널 퇴장 (channel:leave)

{
  "type": "channel:leave",
  "data": {
    "channel_id": "global",
    "user_id": "testuser",
    "nickname": "테스트유저",
    "left_at": "2025-11-24T10:05:00Z"
  }
}

채널 입장/퇴장 이벤트를 통해 우측 참여자 목록이나 “누가 방에 들어왔는지/나갔는지” 알림을 구현할 수 있습니다.

Presence(프레즌스)는 현재 접속자 수, 온라인 상태 등에 대한 정보를 나타냅니다. 구현 방식에 따라 여러 형태가 있을 수 있지만, 예시는 다음과 같습니다.

7-1. presence:update (서버 → 클라이언트)

{
  "type": "presence:update",
  "data": {
    "channel_id": "global",
    "online_count": 12,
    "users": [
      { "user_id": "u_1", "nickname": "유저1" },
      { "user_id": "u_2", "nickname": "유저2" }
      // ... 생략
    ]
  }
}

Presence 정보는 주기적으로 또는 이벤트 기반으로 업데이트될 수 있으며,
실제 서비스에서는 성능/프라이버시 정책에 따라 users 상세 목록은 제한될 수 있습니다.

운영자/관리자가 특정 사용자에게 제재를 가할 경우, 관련 이벤트는 admin: prefix를 사용합니다. 실제 타입명/필드는 서비스 정책에 따라 달라질 수 있습니다.

8-1. admin:ban (서버 → 클라이언트)

{
  "type": "admin:ban",
  "data": {
    "target_user_id": "baduser",
    "scope": "chat",              // chat / channel_create / all 등
    "duration_sec": 3600,
    "reason": "욕설 및 도배",
    "until": "2025-11-24T11:00:00Z"
  }
}

8-2. admin:kick (서버 → 클라이언트)

{
  "type": "admin:kick",
  "data": {
    "target_user_id": "baduser",
    "channel_id": "global",
    "reason": "불건전한 내용"
  }
}

클라이언트는 admin:ban, admin:kick 이벤트를 수신했을 때
UI에서 해당 사용자에게 채팅 입력창 비활성화, 토스트 알림, 방에서 내보내기 등의 처리를 하면 됩니다.

위에서 소개한 이벤트 외에도, 서비스 정책/구현에 따라 custom: prefix를 가진 이벤트나 추가 필드가 도입될 수 있습니다.

• 예) custom:typing – “상대방 입력 중” 표시
• 예) custom:reaction – 메시지에 이모지 리액션 등
• 예) custom:notice – 운영자 공지/시스템 안내

새로운 이벤트가 추가되면, 관련 문서와 예제가 별도로 제공될 예정입니다.

WebSocket 이벤트 흐름을 이해했다면, 이제 HTTP 기반 API와 에러 구조를 함께 보는 것이 좋습니다.

1. REST API 엔드포인트
   인증/업로드 등 HTTP 기반 API 상세 설명
2. 에러 코드 · 응답 포맷
   공통 에러 구조와 주요 에러 코드 정리

실제 연동 예제 코드(PHP/Node/Python, 그누보드/아미나)는 예제 · 자료실 게시판에서 순차적으로 제공될 예정입니다.