← HUZY Chat

개발자 문서

사이트에 실시간 채팅을 붙이고, 회원을 닉네임에 연결하고, 메시지 API를 직접 호출하는 방법입니다.

1. 시작하기

HUZY Chat에 가입한 뒤 마이페이지에서 서비스 ID, 애플리케이션 이름, 운영 모드와 허용 도메인(Origin)을 등록하면 App Key와 Identity Secret이 발급됩니다. 공개 채팅과 상담원 모드는 생성 후 변경할 수 없습니다. 브라우저 주소창의 Origin과 등록 도메인이 같아야 채팅이 열립니다.

npm install @huzydev/chat

패키지 없이 스크립트만 써도 됩니다. 두 방식 모두 같은 widget.js를 로드합니다.

2. 위젯

npm / React

'use client';
import { useEffect } from 'react';
import { mountHuzyChat } from '@huzydev/chat';

export default function HuzyChatWidget() {
  useEffect(() => mountHuzyChat({
    projectKey: process.env.NEXT_PUBLIC_HUZY_CHAT_PROJECT_KEY!,
    color: '#6d5dfc',
    position: 'right',
    identityEndpoint: '/api/huzy-chat/identity',
  }), []);
  return null;
}

스크립트

<script
  async
  src="https://chat.huzy.net/widget.js"
  data-project-key="YOUR_PROJECT_KEY"
  data-position="right"
  data-color="#6d5dfc"
  data-identity-endpoint="/api/huzy-chat/identity"
></script>

projectKey는 필수입니다. position은 left 또는 right, color는 버튼 색입니다. 쿠키가 아닌 Bearer 토큰으로 로그인한 사이트는 authStorageKey에 localStorage 키를 넣으면 위젯이 Authorization: Bearer로 전달합니다.

상담원 모드

설치 코드는 공개 채팅과 같습니다. 상담원 모드 앱은 위젯이 자동으로 문의 아이콘과 “채팅 상담” 문구를 표시합니다. 앱 관리에서 상담 시간, 예상 처리시간, 상담사별 최대 배정 수, 대기 제한 시간, 비속어 필터, 빠른 답변과 상담사 계정을 관리합니다. 상담사는 서비스 ID·아이디·비밀번호로 접속해 상담 분류, 내부 메모, 이관과 종료 결과를 관리합니다. 방문자는 대기 순번과 예상 대기시간을 확인할 수 있습니다.

3. 사이트 회원 연결

비로그인 방문자는 닉네임을 직접 정합니다. 사이트 회원을 채팅에 붙이면 닉네임이 계정 이름으로 고정되고, 차단·도배 제한이 회원 ID 기준으로 묶입니다. 다른 채팅 SaaS의 user token과 같습니다.

  1. 마이페이지의 Identity Secret을 사이트 서버 환경변수로만 저장합니다. 브라우저 번들에 넣지 마세요.
  2. 위젯에 identityEndpoint를 지정합니다. 위젯이 이 URL로 POST합니다 (credentials: include).
  3. 엔드포인트는 로그인 사용자를 확인한 뒤 HMAC 토큰을 { "token": "…" }로 반환합니다. 비로그인이면 401이어도 됩니다. 위젯은 그때 익명으로 동작합니다.
import { createIdentityToken } from '@huzydev/chat/identity';
import { NextResponse } from 'next/server';

export async function POST(request: Request) {
  const user = await getCurrentUser(request);
  if (!user) return NextResponse.json({ error: '로그인이 필요합니다.' }, { status: 401 });

  const token = createIdentityToken({
    secret: process.env.HUZY_CHAT_IDENTITY_SECRET!,
    projectKey: process.env.NEXT_PUBLIC_HUZY_CHAT_PROJECT_KEY!,
    sub: user.id,
    name: user.nickname,
    role: user.role,
    expiresIn: 300,
  });
  return NextResponse.json({ token }, { headers: { 'Cache-Control': 'no-store' } });
}

토큰은 base64url(JSON).HMAC-SHA256입니다. payload에는 sub, name(최대 24자), projectKey, exp가 들어갑니다. Secret이 App Key의 Identity Secret과 같고 projectKey가 일치해야 회원으로 인정됩니다.

NEXT_PUBLIC_HUZY_CHAT_PROJECT_KEY=hc_…
HUZY_CHAT_IDENTITY_SECRET=마이페이지의_Identity_Secret

4. REST API

Base URL https://chat.huzy.net. 위젯을 쓰면 embed token은 자동입니다. 직접 채팅 UI를 만들 때만 아래 API를 호출하세요. 모든 메시지 API는 등록 Origin에서 발급한 embed token이 필요합니다.

Embed token

GET /api/embed-token/{projectKey}

요청 Origin이 허용 목록과 같으면 { "token": "…", "expiresIn": 900 }을 반환합니다. 이후 X-Huzy-Chat-Embed-Token 헤더 또는 ?embedToken=로 전달합니다.

메시지 조회

GET /api/projects/{projectKey}/messages?after={id}
{
  "messages": [
    { "id": "123", "name": "닉네임", "content": "안녕하세요", "createdAt": "2026-09-01T01:00:00.000Z", "visitor": "a1b2c3d4e5" }
  ],
  "project": { "name": "내 서비스", "branding": true }
}

after가 없으면 최근 50개, 있으면 그 이후 최대 100개입니다. 플랜 보관기간이 지난 메시지는 제외됩니다.

메시지 전송

POST /api/projects/{projectKey}/messages
Content-Type: application/json
X-Huzy-Chat-Embed-Token: {embedToken}

{
  "visitorId": "12자 이상 방문자 식별값",
  "name": "닉네임",
  "content": "메시지 (최대 300자)",
  "identityToken": "회원 연동 토큰 (선택)"
}

성공은 201과 message 객체입니다. App Key/도메인 오류와 차단은 403, 잘못된 본문은 400, 0.5초 연속 전송·분당 20건·월 한도는 429입니다.

헬스체크

GET /api/health

5. 실시간

임베드 채팅방은 WebSocket을 씁니다.

wss://chat.huzy.net/socket?projectKey={projectKey}&embedToken={embedToken}&after={lastMessageId}

서버가 새 메시지를 JSON 텍스트로 푸시합니다. 필드는 REST 메시지 객체와 같습니다.

WebSocket을 쓰기 어려우면 SSE를 쓸 수 있습니다. 약 50초 후 연결이 끝나므로 클라이언트가 다시 연결해야 합니다.

GET /api/projects/{projectKey}/stream?after={id}&embedToken={embedToken}

운영과 한도

Free는 월 5,000메시지·7일 보관이며, 상담모드는 계정당 1개·생성일부터 1개월·상담사 2명까지 이용할 수 있습니다. Pro는 월 100,000·90일입니다. 마이페이지에서 메시지 숨김과 30일 차단을 할 수 있습니다. 원문 IP와 방문자 ID는 저장하지 않고 해시만 보관합니다.

패키지 저장소: npmjs.com/package/@huzydev/chat