본문으로 건너뛰기

실시간 채팅

wss://data-api.rogi.chat/v1/chat/stream에 표준 WebSocket으로 연결합니다. 서버에서 JSON 이벤트를 보내며 클라이언트가 전송할 메시지는 없습니다. Socket.IO 프로토콜은 지원하지 않습니다.

let cursor;

function connect() {
const url = new URL('wss://data-api.rogi.chat/v1/chat/stream');
if (cursor) url.searchParams.set('cursor', cursor);
const socket = new WebSocket(url);

socket.onmessage = ({data}) => {
const event = JSON.parse(data);
if (event.type === 'chat.message') {
cursor = event.cursor;
console.log(event.user.displayName, event.message);
}
if (event.type === 'chat.gap') {
cursor = undefined;
// 필요한 과거 기록은 방송별 채팅 조회 API에서 다시 읽습니다.
}
};

socket.onclose = () => setTimeout(connect, 1000);
}

connect();

연결 직후 hello를 받습니다. cursor를 지정하지 않으면 연결 당시 최신 메시지 이후부터 받습니다. 연결이 끝나면 마지막 chat.message.cursor로 다시 연결하세요. 연결 수명은 최대 2시간이며, heartbeat는 약 20초 간격으로 전달됩니다.

이벤트​

hello​

{
"type": "hello",
"version": "v1",
"serverTime": "2026-09-23T08:00:00Z",
"broadcastState": "live",
"broadcastId": "example-broadcast-id",
"title": "방송 제목",
"currentCursor": "opaque-current-cursor",
"earliestCursor": "opaque-earliest-cursor",
"cursorRetention": "up to 24 hours and 10000 stream entries"
}

currentCursor와 earliestCursor는 보관된 채팅이 없으면 null입니다. 방송 진단에 성공한 경우 broadcastState는 방송 상태의 state와 같습니다. 진단에 실패하면 WebSocket은 lookup_failed를 보내고 HTTP 상태 조회는 503 status_unavailable을 반환합니다. broadcastId는 지난 방송 조회용 sessionId가 아닙니다.

chat.message​

{
"type": "chat.message",
"eventId": "example-event-id",
"cursor": "opaque-reconnect-cursor",
"receivedAt": "2026-09-23T08:00:05Z",
"user": {"displayName": "시청자"},
"message": "안녕하세요"
}

cursor는 재접속 위치입니다. eventId는 중복 메시지를 식별할 때 사용할 수 있습니다. 실시간 메시지에는 보관 기록의 sessionId와 가명 사용자 ID가 포함되지 않습니다.

broadcast.status​

{
"type": "broadcast.status",
"state": "offline",
"broadcastId": "",
"title": "",
"checkedAt": "2026-09-23T09:00:00Z"
}

방송 상태·ID·제목 중 하나가 바뀌면 전송됩니다. 채팅 수집 연결 상태는 이 이벤트에 포함되지 않습니다. 필요하면 방송 상태 API를 조회하세요.

chat.gap​

{"type":"chat.gap","reason":"cursor_expired"}

이어받을 수 없는 구간이 있을 때 전송됩니다. reason은 cursor_expired, stream_reset, invalid_event 중 하나입니다. cursor 만료 또는 stream 교체 후에는 그 시점의 최신 메시지 이후 새 메시지부터 전송합니다. 이미 보존된 중간 메시지도 자동으로 재생하지 않습니다. 누락된 메시지가 필요한 경우 지난 방송 채팅을 조회하세요. 보관 기록도 모든 메시지의 복구를 보장하지는 않습니다.

heartbeat와 error​

{"type":"heartbeat","serverTime":"2026-09-23T08:00:20Z"}
{"type":"error","code":"chat_unavailable"}

error 이후 연결이 종료됩니다. chat_unavailable 또는 chat_generation_unavailable이 발생하면 잠시 뒤 재연결하세요.

최근 채팅 HTTP 조회​

GET /v1/chats/recent?cursor=&limit=은 WebSocket과 같은 짧은 보존 범위를 조회합니다. cursor 없이 요청하면 보존된 최신 채팅부터 최대 limit건을 시간순으로 반환합니다.

curl -fsS 'https://data-api.rogi.chat/v1/chats/recent?limit=50'
{
"messages": [
{
"type": "chat.message",
"eventId": "example-event-id",
"cursor": "opaque-next-message-cursor",
"receivedAt": "2026-09-23T08:00:05Z",
"user": {"displayName": "시청자"},
"message": "안녕하세요"
}
],
"nextCursor": "opaque-next-message-cursor",
"retention": "up to 24 hours and 10000 stream entries"
}

limit 기본값은 50, 최대값은 100입니다. messages가 비어 있어도 읽기 위치가 이동했다면 nextCursor가 있을 수 있습니다. nextCursor가 null이면 이번 응답에서 새 읽기 위치가 없습니다. cursor가 보존 범위 밖이거나 stream이 교체됐으면 409 cursor_expired를 반환합니다. 이 cursor는 WebSocket의 ?cursor=에도 사용할 수 있습니다.