개발자 문서

Live Chat을 사이트와 관리자 화면에 넣기

위젯은 스크립트 태그 한 줄이면 됩니다. 자사 버튼용 작은 JavaScript API, 관리자 화면에서 바로 들어오는 싱글 사인온, 그리고 AI 어시스턴트가 연동을 맡을 수 있는 MCP 서버가 있습니다.

위젯 추가하기

채팅을 보여 줄 모든 페이지의 </body> 바로 앞에 이 태그를 붙여 넣으세요. 워크스페이스 ID는 설정 › 일반에서 확인할 수 있고, 설정 › 위젯에서 태그 전체를 복사할 수도 있습니다.

스크립트는 가볍고, 방문자가 채팅을 열기 전까지는 다른 것을 불러오지 않습니다. 일반 HTML, WordPress, Shopify, Next.js, 싱글 페이지 앱 등 어떤 사이트에서도 작동합니다.

<script src="https://chat.hibira.io/w/v1.js"
        data-workspace="ws_..." async></script>

각 사이트 주소를 설정 › 위젯 › 위젯을 쓸 수 있는 사이트에 추가하세요. 목록에 없는 사이트에서는 위젯이 작동하지 않습니다.

위젯 옵션

스크립트 태그에 다음 속성을 지정할 수 있습니다.

<script src="https://chat.hibira.io/w/v1.js"
        data-workspace="ws_..."
        data-color="#0f766e"
        data-lang="ja"
        async></script>

속성	설명
`data-workspace`	필수. 워크스페이스 ID(ws_...).
`data-color`	버튼과 헤더 색상을 #0f766e 같은 16진수 값으로 지정합니다. 기본값 #4f46e5.
`data-lang`	위젯 언어: en, ja, ko, zh-TW, zh-CN, th, vi. 기본값은 방문자의 브라우저 언어입니다.
`data-launcher="none"`	둥근 채팅 버튼을 표시하지 않습니다. 페이지의 버튼으로 채팅을 엽니다(JavaScript API 참고).
`nonce`	엄격한 Content-Security-Policy가 있는 페이지에서는 위젯이 추가하는 스타일과 스크립트에 스크립트 태그의 nonce를 붙입니다.

JavaScript API

스크립트가 로드되면 window.HibiraLiveChat으로 페이지에서 채팅을 열고 닫을 수 있습니다. 코드가 위젯보다 먼저 실행될 수 있다면 hibira-livechat:ready 이벤트를 기다리세요.

<button type="button" id="talk-to-sales">Talk to sales</button>

<script src="https://chat.hibira.io/w/v1.js"
        data-workspace="ws_..." data-launcher="none" async></script>
<script>
  document.getElementById("talk-to-sales").addEventListener("click", function () {
    if (window.HibiraLiveChat) window.HibiraLiveChat.open({ topic: "sales" });
  });
  window.addEventListener("hibira-livechat:ready", function () {
    // The widget is loaded: HibiraLiveChat.open() and .close() work now.
  });
</script>

호출 또는 이벤트	설명
`HibiraLiveChat.open()`	채팅 창을 엽니다.
`HibiraLiveChat.open({ topic: "sales" })`	채팅을 열고 새 대화를 영업 문의로 표시합니다. 받은편지함에서도 영업 문의로 보입니다.
`HibiraLiveChat.close()`	채팅 창을 닫습니다.
`hibira-livechat:ready`	위젯 로드가 끝나면 window에서 발생하는 이벤트입니다.
`hibira_chat_open, hibira_chat_start, hibira_chat_message, hibira_chat_rating`	설정 › 위젯에서 애널리틱스를 켜면, 사이트에 이미 있는 gtag 또는 Tag Manager로 보내는 Google 애널리틱스 이벤트입니다. 개인 정보는 보내지 않습니다.

Content-Security-Policy

사이트가 엄격한 Content-Security-Policy를 보낸다면 아래 호스트를 허용하고, 스크립트 태그에 페이지의 nonce를 붙이세요. 위젯은 그 nonce를 자신이 추가하는 모든 요소에 넘겨줍니다.

challenges.cloudflare.com은 새 방문자의 첫 메시지 스팸 검사에 쓰입니다.

script-src  'nonce-R4nd0m' https://chat.hibira.io https://challenges.cloudflare.com;
style-src   'nonce-R4nd0m';
connect-src https://chat.hibira.io wss://*.hibira.io;
img-src     https://chat.hibira.io data:;
frame-src   https://challenges.cloudflare.com;

<script src="https://chat.hibira.io/w/v1.js" nonce="R4nd0m"
        data-workspace="ws_..." async></script>

상담원 싱글 사인온(JWT) Starter 이상

직원은 별도 비밀번호 없이 자사 관리자 화면에서 Live Chat 받은편지함으로 바로 들어옵니다. 서버가 로그인한 직원을 위해 수명이 짧은 토큰에 서명하고 Live Chat으로 보냅니다.

팀 › 싱글 사인온에서 싱글 사인온을 켜고 시크릿을 복사합니다.
시크릿은 서버에만 저장합니다(예: 환경 변수 HIBIRA_LIVECHAT_SSO_SECRET). 브라우저 코드에는 절대 넣지 마세요.
관리자 화면에 자사 라우트로 가는 링크를 추가합니다. 그 라우트에서 직원인지 확인하고, 아래 토큰에 서명한 뒤 /sso/jwt로 리디렉션합니다.
처음 로그인한 사람은 빈 좌석이 있으면 상담원으로 추가됩니다. 역할은 로그인할 때마다 토큰에 맞춰집니다.

import crypto from "node:crypto";

const b64 = (v) => Buffer.from(JSON.stringify(v)).toString("base64url");

// Build a new URL on every click, behind your admin panel's own login.
export function liveChatSsoUrl(user) {
  const now = Math.floor(Date.now() / 1000);
  const head = b64({ alg: "HS256", typ: "JWT" });
  const body = b64({
    iss: "ws_...",                 // your Workspace ID
    sub: String(user.id),          // the user's ID in your system
    email: user.email,
    name: user.name,
    role: user.isAdmin ? "admin" : "agent",
    jti: crypto.randomUUID(),      // single use
    iat: now,
    exp: now + 120,                // 5 minutes at most
  });
  const sig = crypto
    .createHmac("sha256", process.env.HIBIRA_LIVECHAT_SSO_SECRET)
    .update(head + "." + body)
    .digest("base64url");
  return "https://chat.hibira.io/sso/jwt?" + new URLSearchParams({
    jwt: head + "." + body + "." + sig,
    return_to: "/inbox",
  });
}

클레임	의미
`iss`	필수. 워크스페이스 ID.
`sub`	필수. 자사 시스템의 사용자 ID(최대 200자). 이메일이 바뀌어도 같은 상담원으로 연결됩니다.
`email`	필수. 사용자의 이메일 주소.
`name`	선택. 방문자와 팀원에게 보이는 이름.
`role`	선택. agent(기본값) 또는 admin.
`jti`	필수. 이 토큰의 고유 ID(최대 128자). 토큰마다 한 번만 쓸 수 있습니다.
`iat`	선택. 서명한 시각(Unix 초).
`exp`	필수. 만료 시각(Unix 초). 지금부터 최대 5분입니다.

HS256으로 서명하고 토큰을 ?jwt=로 /sso/jwt에 보냅니다. return_to에 /inbox 같은 경로를 넣으면 로그인 후 이동할 곳을 정할 수 있습니다.
시계 오차는 30초까지 허용합니다.
시크릿을 교체해도 이전 시크릿은 24시간 동안 유효하므로 중단 없이 새 시크릿을 배포할 수 있습니다.
작동을 확인했다면 '싱글 사인온만 허용'을 켜세요. 상담원은 관리자 화면으로만 로그인할 수 있고, 소유자는 계속 이메일로도 로그인할 수 있습니다.

Node.js, Laravel, PHP, Python, Django, Rails, Go, Java, .NET용 코드는 아래 MCP 서버에서 받을 수 있습니다.

AI 어시스턴트(MCP)

Live Chat MCP 서버를 쓰면 Claude, Cursor, VS Code 같은 AI 어시스턴트가 자사 코드에 싱글 사인온을 연동할 수 있습니다. 어시스턴트는 브라우저에서 Live Chat 계정으로 로그인하며, 승인은 워크스페이스 소유자와 관리자만 할 수 있습니다.

SSO 시크릿은 MCP를 거치지 않습니다. 어시스턴트는 설정을 읽고, 사용하는 스택에 맞는 코드를 작성하고, 서명한 토큰을 아무도 로그인시키지 않고 검사합니다.

# Claude Code
claude mcp add --transport http hibira-live-chat https://chat.hibira.io/mcp

# Any client with remote MCP servers (Cursor, VS Code, ...)
{ "mcpServers": { "hibira-live-chat": { "url": "https://chat.hibira.io/mcp" } } }

도구	설명
`get_sso_setup`	싱글 사인온 사용 여부, 워크스페이스 ID, 로그인 URL, 토큰 클레임과 제한, 빈 좌석.
`get_sso_snippet`	토큰에 서명하고 직원을 리디렉션하는 서버 코드. 워크스페이스 ID가 채워져 있습니다.
`check_sso_token`	실제 로그인과 똑같이 토큰을 검사하고 문제를 모두 알려 줍니다. 토큰은 소모되지 않습니다.
`list_agents`	워크스페이스의 상담원, 역할, 추가된 방식, 마지막 접속 시각.
`set_sso_only`	'싱글 사인온만 허용'을 켜거나 끕니다. 소유자 전용.

Claude Code, Cursor, Codex, Gemini CLI용 Hibira 플러그인에 이 서버가 이미 들어 있습니다. 모든 AI 앱 연결을 한 번에 끊으려면 팀 › 싱글 사인온 › AI 앱 연결 해제를 사용하세요.

REST API와 웹훅 출시 예정

대화, 메시지, 평가를 위한 REST API와 새 대화, 메시지, 평가 웹훅이 Team 플랜 이상에 추가될 예정입니다. 준비되면 이 페이지에서 안내합니다.

그때까지는 받은편지함에서 대화를 CSV나 JSON으로, 설정 › 데이터 및 개인정보에서 워크스페이스 전체를 내보낼 수 있습니다.

AI 도구용

AI 어시스턴트와 답변 엔진을 위한 Live Chat 텍스트 요약입니다. /llms.txt는 짧은 버전이고, /llms-full.txt에는 이 문서와 모든 기능 페이지 전문이 들어 있습니다.

curl https://chat.hibira.io/llms.txt
curl https://chat.hibira.io/llms-full.txt

가장 먼저 만나 보세요

이메일을 남기시면 차례가 되는 대로 초대를 보내 드립니다.

대기자 명단 등록