시작하기

채팅을 내 서비스에 붙이는 데 필요한 것은 셋이다. 콘솔에서 만든 앱, 토큰을 발급하는 백엔드 엔드포인트 하나, 브라우저의 SDK.

sh
npm install @kispi/chat

진입점이 둘이다. SDK는 런타임 의존성이 없고 타입 선언을 포함한다.

진입점 어디서 쓰는 키
@kispi/chat 브라우저(와 Node) publishable key(pk_)
@kispi/chat/server 내 백엔드 secret key(sk_)

1. 콘솔에서 앱을 만든다

가입한 뒤 새 앱을 누른다. 앱 하나가 테넌트 하나다 — 유저·방·메시지·키가 앱마다 따로 있다. 만들자마자 키 두 개가 나온다.

키 어디에 두나 무엇을 하나
publishable key(pk_…) 프론트엔드 코드 어느 앱인지만 말한다. 공개값이다
secret key(sk_…) 백엔드의 환경변수 그 앱의 모든 데이터다. 토큰 발급과 서버 API에 쓴다

sk_는 만든 순간 한 번만 보인다. 콘솔은 그 값을 저장하지 않으므로 바로 비밀 저장소에 옮겨 둔다. 잃어버렸으면 새 sk_를 발급하고 옛 것을 폐기한다(키 교체).

화면을 누르는 대신 스크립트나 AI로 앱을 만들고 싶다면 계정 키(ck_) 하나로 된다. 콘솔 API를 본다.

허용 origin

앱을 만들 때 적는 허용 origin은 브라우저에서 이 pk_를 쓸 수 있는 페이지의 origin이다.

  • 스킴·호스트·포트가 정확히 맞아야 한다. https://example.com과 https://www.example.com은 다른 origin이다.
  • http://localhost:3000과 http://127.0.0.1:3000도 다르다. 개발용 origin은 따로 넣는다.
  • 목록에 없는 페이지에서 쓰면 unauthorized로 거절된다. 목록은 키 화면에서 허용 origin 칸을 눌러 바꾼다.

2. 백엔드가 토큰을 발급한다

엔진은 사람이 누구인지 모른다. 토큰의 서명을 검증하고 그 안의 유저 id를 액면 그대로 믿을 뿐이다. 누가 로그인했는지는 서비스가 아니까, 필요한 것은 그 사람에게 토큰을 발급하는 엔드포인트 하나다.

ts
// src/routes/api/chat-token/+server.ts (SvelteKit) — 어떤 프레임워크든 모양은 같다
import { json } from '@sveltejs/kit'
import { createChatServer } from '@kispi/chat/server'
import { env } from '$env/dynamic/private'

const chat = createChatServer({
  secretKey: env.CHAT_SECRET_KEY // sk_…
})

export const POST = async ({ locals }) => {
  const user = locals.user // 서비스의 세션
  if (!user) return new Response(null, { status: 401 })
  return json({
    token: chat.token({
      userId: String(user.id), // 이 사람의 id
      name: user.nickname,
      avatar: user.avatarUrl, // 선택
      ttlSeconds: 3600 // 선택. 기본 1시간, 최대 24시간
    })
  })
}
python
# chat_token()은 "서버 연동" 쪽에 있다 — 여기서는 그것을 부르기만 한다
@app.post("/api/chat-token")
def issue_chat_token():
    user = current_user()  # 서비스의 세션
    if user is None:
        return "", 401
    return {"token": chat_token(SK, str(user.id), user.nickname, ttl=3600)}
go
// chatToken()은 "서버 연동" 쪽에 있다 — 여기서는 그것을 부르기만 한다
func issueChatToken(w http.ResponseWriter, r *http.Request) {
	user, ok := currentUser(r) // 서비스의 세션
	if !ok {
		http.Error(w, "", http.StatusUnauthorized)
		return
	}
	token, err := chatToken(sk, user.ID, user.Nickname, time.Hour)
	if err != nil {
		http.Error(w, "", http.StatusInternalServerError)
		return
	}
	json.NewEncoder(w).Encode(map[string]string{"token": token})
}
kotlin
// chatToken()은 "서버 연동" 쪽에 있다 — 여기서는 그것을 부르기만 한다
@PostMapping("/api/chat-token")
fun issueChatToken(session: HttpSession): Map<String, String> {
    val user = session.user ?: throw ResponseStatusException(HttpStatus.UNAUTHORIZED)
    return mapOf("token" to chatToken(sk, user.id.toString(), user.nickname))
}

chat.token()은 네트워크를 타지 않는 로컬 서명이라 요청마다 불러도 된다. 다른 언어도 같다 — 서명뿐이라 엔진을 부르지 않는다. name은 접속할 때마다 이 값으로 덮어쓴다. 토큰 규격 자체는 서버 연동에 있고, 로그인하지 않은 방문자는 비로그인 사용자가 같은 엔드포인트에서 발급하는 법을 적는다.

3. 브라우저가 주고받는다

iOS·Android·Flutter나 Swift·Kotlin·Dart·Python 같은 JS 밖의 언어라면 이 단계의 SDK 대신 실시간 프로토콜(WebSocket)과 REST API를 따른다. 토큰을 발급하는 2단계는 그대로다.

ts
// chat.ts
import { createChatClient } from '@kispi/chat'

export const chat = createChatClient({
  key: import.meta.env.VITE_CHAT_PK, // pk_…
  token: async () => {
    const res = await fetch('/api/chat-token', { method: 'POST' })
    return (await res.json()).token
  }
})

chat.on('state', (s) => setStatus(s)) // connecting | open | reconnecting | closed
chat.connect().catch(() => {})

재접속과 토큰 갱신은 SDK가 한다. 방은 백엔드가 만든다 — 키로 연다고 방이 생기지 않고, 없는 키를 구독하면 not_found다. rooms.ensure는 있으면 그대로 돌려주는 get-or-create다.

ts
// 백엔드. 2단계에서 만든 createChatServer 인스턴스다
await chat.rooms.ensure({ key: 'lobby', type: 'public' })

방 key는 영문 대소문자·숫자와 _ . : -만 쓰고 1~128자다(^[A-Za-z0-9_.:-]{1,128}$). 한글이나 공백이 들어가면 400 invalid이므로, 사람이 읽는 이름은 name에 두고 key는 order-1234 같은 ASCII 별칭으로 정한다.

아래부터는 다시 브라우저, 3단계에서 만든 createChatClient 쪽이다.

ts
const room = chat.roomByKey('lobby')
await room.subscribe() // 라이브 피드 + 최근 20건(엔진 기본 페이지)

room.on('messages', (all) => render(all)) // 목록이 바뀔 때마다 통째로
room.on('message.created', (m) => append(m)) // 또는 새 메시지 하나씩

const ack = await room.send({ text: '안녕' }) // { messageId, seq }
await room.send({ text: '이거 봐', attachments: [{ type: 'image', url, key }] })
await room.react(ack.messageId, '👍')
await room.markRead(room.lastSeq)
room.typing()

const { hasMore } = await room.loadOlder() // 스크롤을 올려 과거를 볼 때. 끝이면 false

room.messages는 언제나 seq 오름차순이고 구멍이 없다. 바뀔 때마다 새 배열이라 참조로 비교하는 상태(Svelte $state.raw, React useState, Vue shallowRef)에 그대로 넣는다. 파일은 엔진이 보관하지 않는다 — 쓰고 있는 저장소(S3 같은 것)에 올리고 그 주소를 attachments에 싣는다(url은 https://로 시작해야 한다).

두 이벤트는 꼭 처리한다.

  • reset — SDK가 목록을 버리고 다시 채웠다. 렌더한 것을 버리고 room.messages로 다시 그린다.
  • error — 히스토리를 읽는 데 실패했다. 방이 스스로 다시 구독하므로 알리기만 한다.
저장되나 재접속 뒤
메시지 된다 SDK가 구멍을 메운다
리액션 된다 히스토리에 실려 온다. 끊긴 동안의 변화(리액션·스레드 수·수정·삭제)는 SDK가 재접속 때 방의 최근 한 페이지(20건)에 맞춘다. 그보다 오래된 행은 reload()
읽음 커서(markRead) 된다 rooms.list()의 unread가 반영한다
presence 안 된다 새로 받는다
typing 안 된다 놓쳐도 된다. 한 사람당 많아야 3초에 한 번 오므로 마지막 것 뒤 5초쯤 보여 주고 지운다. 방마다 3초 창에 3명까지만 방송하므로 붐비는 방에서는 입력 중인데 알려지지 않는 사람이 있다

typing은 보낸 사람에게도 온다 — "X가 입력 중"을 그린다면 자기 userId는 건너뛴다. 실패는 ChatError로 던지고, err.code가 rate_limited면 err.retryAfterMs만큼 기다린다.

한도

속도와 크기의 한도는 앱마다 다르다. 기본값은 아래와 같고, 콘솔의 한도 탭에서 앱마다 보고 바꾼다.

한도 기본값 세는 단위
메시지 보내기 초당 5, 한꺼번에 10 유저
리액션 초당 10 유저
typing 초당 20 유저
메시지 수정 초당 2 유저
접속 분당 10 유저
동시 연결 10 유저
접속 수립 분당 60 pk_ + IP
구독 100 연결
메시지 길이 4000자 메시지
첨부 10개 메시지
리액션 종류 20개 메시지
프레임 크기 64 KB 연결
저장 메시지 수 제한 없음 앱
수정 가능 시간 제한 없음 메시지
  • 서버 API(sk_)로 보내는 메시지에는 속도 한도가 걸리지 않고, 수정 가능 시간도 적용되지 않는다.
  • 저장 메시지 수는 삭제된 메시지(tombstone)도 센다. 한도를 정한 앱이 가득 차면 새 메시지는 quota_exceeded(REST 403)로 거절되고, 기다려도 풀리지 않으므로 재시도하지 않는다.
  • 속도와 크기는 그 앱의 상한까지 올릴 수 있다. 낮추는 것도 되지만 프레임 크기는 기본 64 KB 아래로 내릴 수 없다. 보내기 대기열(sendQueueSize)은 모든 앱에 같은 값으로 고정이다.
  • 붙어 있는 연결에는 30초 안에 닿는다. 접속에서 정해지는 값(접속 속도, 동시 연결, 구독 수, 프레임 크기)은 다음 접속부터다. 지금 걸린 값은 접속 때 hello.limits로도 온다.

4. 웹훅 (선택)

발행·수정·삭제를 백엔드가 들어야 할 때 쓴다 — 푸시 알림, 검색 색인, 감사 로그. 발행 전에 끼어들어 거절하거나 본문을 바꾸는 before_publish도 있다. 받는 쪽 코드와 서명 검증은 웹훅에 있다.

다음