📖 DOCUMENTATION

Ideal AI Chatbot SDK
가이드

script 태그 하나로 어느 웹사이트에나 AI 챗봇을 붙이는 방법

<script src="https://your-server.com/chatbot-widget.js" data-bot-id="봇-ID" data-endpoint="https://your-server.com"> </script>
관리자 가이드
🗺️ 서비스 개요

관리자 패널에서 챗봇을 만들고, 문서를 업로드하면 AI가 자동으로 답변합니다. 완성된 챗봇은 script 태그 하나로 어느 웹사이트에나 붙일 수 있습니다.

📚
Q&A 봇
질문-답변 쌍을 직접 등록합니다. GPT를 호출하지 않아 비용이 없고, 정해진 답변만 반환합니다.
✨
AI 봇
문서를 업로드하면 GPT가 문서를 참조해 자유롭게 답변합니다. 시스템 프롬프트로 말투를 지정할 수 있습니다.
🤖 봇 만들기
1
새 챗봇 만들기 클릭
좌측 사이드바에서 "새 챗봇 만들기"를 클릭합니다.
2
유형 선택
Q&A 봇 또는 AI 봇 중 하나를 선택합니다. 이후 변경 불가합니다.
3
이름 및 설정 입력
봇 이름, 시스템 프롬프트(AI 봇), 위젯 제목·색상·시작 인사말을 설정합니다.
4
테스트 후 임베드
테스트 메뉴에서 동작을 확인한 뒤 설정 페이지 하단의 임베드 코드를 복사합니다.

봇 메뉴 구성

메뉴설명
설정봇 이름, 프롬프트, 위젯 색상·제목·인사말 변경 + 임베드 코드
Q&A 관리질문-답변 쌍 추가/수정/삭제 (Q&A 봇 전용)
문서 관리파일 업로드 및 폴더 구조 관리
테스트실제 동작 확인, 참조 문서 및 유사도 표시
대화 기록세션별 실제 사용자 대화 내역 열람
📚 Q&A 봇 관리 Q&A Bot

미리 등록한 질문-답변 쌍을 기반으로 응답합니다. 사용자 질문과 의미적으로 가장 가까운 답변을 자동으로 찾아 반환합니다.

1
봇 선택 → 사이드바 "Q&A 관리" 클릭
2
질문과 답변 입력 후 추가
등록 시 질문이 자동으로 임베딩되어 저장됩니다.
3
테스트 메뉴에서 확인
질문을 입력해보고 의도한 답변이 나오는지 확인합니다.
💡
답변이 안 나올 때 유사도가 낮으면 "답변을 찾지 못했습니다"를 반환합니다. 질문을 다양하게 등록하거나, 사용자가 실제로 쓸 표현으로 질문을 작성해보세요.
✨ AI 봇 & 문서 업로드 AI Bot

문서를 업로드하면 AI가 내용을 읽고 사용자 질문에 맞는 답변을 생성합니다.

문서 업로드

방식설명
파일 업로드여러 파일 한번에 선택. ZIP은 내부 파일 자동 추출
폴더 업로드폴더 전체를 선택하면 디렉토리 구조 그대로 저장

지원 파일 형식

.txt .md .pdf .docx .hwp .hwpx .html .csv .zip

시스템 프롬프트 예시

시스템 프롬프트 
당신은 [회사명]의 친절한 고객지원 상담원입니다.
- 항상 공손하고 간결하게 답변해주세요.
- 모르는 내용은 솔직하게 모른다고 말하세요.
- 업로드된 문서 내용을 기반으로 답변하세요.
- 한국어로만 응답하세요.
💡
문서가 잘 검색되는지 확인하려면 테스트 메뉴에서 질문하면 답변 아래에 참조된 문서 이름과 유사도(%)가 표시됩니다. 참조 문서가 없다면 문서 내용이 질문과 의미적으로 가깝지 않은 경우입니다.
🌐 위젯 임베드

봇 설정 페이지 하단의 임베드 코드를 복사해 웹사이트 </body> 태그 바로 위에 붙여넣으세요.

임베드 코드 
<script src="https://your-server.com/chatbot-widget.js"
        data-bot-id="여기에-봇-ID"
        data-endpoint="https://your-server.com"></script>
동작설명
열기 / 닫기우측 하단 플로팅 버튼 클릭
세션 초기화위젯 닫을 때 자동으로 새 세션 시작
중복 방지같은 코드 여러 번 삽입해도 위젯은 하나만 표시
🐘 그누보드에 설치하기

그누보드는 PHP 기반이지만 위젯은 순수 JS이므로 script 태그만 추가하면 됩니다. 챗봇 서버(Next.js)는 별도로 운영되며 그누보드 서버에는 아무것도 설치하지 않아도 됩니다.

방법 1 — 그누보드 관리자에서 설정 권장

그누보드 관리자 → 환경설정 → 기본환경설정 → "공통 하단 스크립트" 항목에 임베드 코드를 붙여넣습니다. 파일을 직접 수정하지 않아도 됩니다.

방법 2 — tail.php 직접 수정

그누보드 루트의 tail.php 파일을 열고 </body> 바로 위에 임베드 코드를 추가합니다.

tail.php 
<!-- 챗봇 위젯 -->
<script src="https://your-server.com/chatbot-widget.js"
        data-bot-id="봇-ID"
        data-endpoint="https://your-server.com"></script>

</body>
</html>

방법 3 — 특정 페이지에만 표시 (PHP 조건)

tail.php — 조건부 표시 
<?php if (is_member()) { ?>  // 로그인 회원에게만
<script src="https://your-server.com/chatbot-widget.js"
        data-bot-id="봇-ID"
        data-endpoint="https://your-server.com"></script>
<?php } ?>
조건 함수의미
is_member()로그인한 회원 여부
is_admin()관리자 여부 (관리자에겐 숨기기: !is_admin())
$bo_table == 'notice'특정 게시판에서만 표시
🛒 Cafe24 호스팅에 적용하기

카페24 쇼핑몰 또는 호스팅 서비스에서 챗봇 위젯을 추가하는 방법입니다. 마찬가지로 챗봇 서버에는 아무런 작업이 없으며, script 태그만 추가하면 됩니다.

방법 1 — 쇼핑몰 관리자 스크립트 설정 권장

카페24 쇼핑몰 관리자에서 코드 수정 없이 스크립트를 추가할 수 있습니다.

1
쇼핑몰 관리자 로그인
카페24 관리자 페이지(https://echosting.cafe24.com)에 로그인합니다.
2
쇼핑몰 설정 → 기본 설정 이동
상단 메뉴에서 쇼핑몰 설정 → 기본 설정 → 검색엔진 최적화(SEO)로 이동합니다.
3
"공통 스크립트" 항목에 코드 추가
"헤더/바디 공통 스크립트" 또는 "바디 스크립트 (하단)" 입력란에 임베드 코드를 붙여넣습니다.
4
저장 후 쇼핑몰에서 확인
저장 후 쇼핑몰 메인 페이지를 열면 우측 하단에 챗봇 버튼이 나타납니다.

방법 2 — 디자인 편집 (HTML 직접 수정)

스킨 파일을 직접 수정하는 방법입니다. 특정 페이지에만 챗봇을 추가하거나 세밀한 제어가 필요할 때 사용합니다.

1
디자인 → 내 디자인 → 편집
카페24 관리자 → 디자인 → 내 디자인에서 현재 적용 중인 스킨의 편집 버튼을 클릭합니다.
2
레이아웃 파일 열기
화면 하단 파일 목록에서 layout/basic/layout.html 또는 html/layout.html을 엽니다.
3
</body> 바로 위에 코드 추가
파일 맨 아래 </body> 태그를 찾아 바로 위에 임베드 코드를 붙여넣습니다.
4
저장 → 쇼핑몰에서 확인
layout.html — </body> 바로 위에 추가 
<!-- 챗봇 위젯 -->
<script src="https://your-server.com/chatbot-widget.js"
        data-bot-id="봇-ID"
        data-endpoint="https://your-server.com"></script>

</body>
</html>
⚠️
카페24 일반 웹호스팅의 경우 쇼핑몰이 아닌 일반 웹호스팅(PHP/HTML)을 사용한다면 FTP로 접속해 공통 레이아웃 파일(footer.php, bottom.php 등)의 </body> 위에 코드를 추가하면 됩니다.
📱 앱 웹뷰에 적용하기

React Native, Flutter, iOS(WKWebView), Android(WebView) 등 앱 내 웹뷰에서도 동일하게 동작합니다. 웹뷰가 일반 브라우저처럼 HTML을 렌더링하므로 별도 작업 없이 script 태그만 추가하면 됩니다.

방법 1 — 웹뷰로 관리자 페이지 URL 직접 로드

별도의 챗봇 전용 페이지를 만들어 웹뷰로 띄우는 방식입니다. 앱에서 챗봇 버튼을 누르면 웹뷰가 열리는 구조입니다.

React Native — WebView 예시 
import { WebView } from 'react-native-webview';

export default function ChatbotScreen() {
  return (
    <WebView
      source={{ uri: 'https://your-server.com/chat/봇-ID' }}
      style={{ flex: 1 }}
    />
  );
}

방법 2 — 기존 웹페이지에 위젯 임베드 후 웹뷰로 로드

이미 운영 중인 웹사이트에 챗봇 위젯을 추가했다면, 해당 URL을 웹뷰로 열면 앱에서도 위젯이 그대로 동작합니다.

방법 3 — HTML 문자열을 웹뷰에 직접 주입

외부 URL 없이 앱 내부에서 챗봇 화면을 직접 렌더링하는 방식입니다.

React Native — HTML 직접 주입 
import { WebView } from 'react-native-webview';

const html = `
<!DOCTYPE html>
<html>
<head>
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <style>
    body { margin: 0; height: 100vh; display: flex; flex-direction: column; }
  </style>
</head>
<body>
  <script
    src="https://your-server.com/chatbot-widget.js"
    data-bot-id="봇-ID"
    data-endpoint="https://your-server.com">
  </script>
</body>
</html>
`;

export default function ChatbotScreen() {
  return (
    <WebView
      source={{ html }}
      originWhitelist={['*']}
      style={{ flex: 1 }}
    />
  );
}
💡
Flutter의 경우 webview_flutter 패키지를 사용합니다. WebViewController로 URL을 로드하거나 loadHtmlString()으로 HTML을 직접 주입하는 방식이 동일하게 적용됩니다.
⚠️
Android 주의사항 Android WebView는 기본적으로 JavaScript가 비활성화되어 있습니다. webView.settings.javaScriptEnabled = true를 설정해야 위젯이 정상 동작합니다.
개발자 가이드
🚀 서버 설치 & 빠른 시작
1
의존성 설치
npm install 실행
2
환경변수 설정
프로젝트 루트에 .env.local 파일 생성 후 아래 환경변수 섹션 참고
3
서버 실행
개발: npm run dev / 프로덕션: npm run build && npm start
4
슈퍼 어드민에서 테넌트 생성
/admin 접속 후 업체(테넌트) 계정을 생성합니다. DB 스키마는 최초 요청 시 자동 생성됩니다.
🔑 환경변수
.env.local 
# OpenAI API 키 (필수)
OPENAI_API_KEY=sk-proj-...

# Neon PostgreSQL 연결 문자열 (필수)
DATABASE_URL=postgresql://...

# 서버 URL (임베드 코드 생성에 사용)
NEXT_PUBLIC_BASE_URL=http://localhost:3000
⚠️
보안 주의 OPENAI_API_KEY와 DATABASE_URL은 절대 클라이언트에 노출되면 안 됩니다. NEXT_PUBLIC_ 접두사를 붙이지 마세요.
🔌 채팅 API

커스텀 UI를 만들 때 직접 호출할 수 있습니다.

POST /api/chat/:botId

Request 
{
  "message": "배송은 얼마나 걸리나요?",
  "sessionId": "uuid-v4",       // 세션 구분, 없으면 자동 생성
  "history": [                      // AI 봇 전용, 선택사항
    { "role": "user", "content": "안녕하세요" },
    { "role": "assistant", "content": "안녕하세요!" }
  ]
}
Response 
{
  "reply": "평균 2~3 영업일 내에 배송됩니다.",
  "usedDocs": [                     // AI 봇 전용
    { "title": "배송 정책.pdf", "score": 82 }
  ]
}
🔍 RAG 검색

AI 봇은 질문을 임베딩한 뒤 업로드된 문서들과 코사인 유사도를 비교해 관련 문서를 GPT 컨텍스트에 주입합니다.

파라미터기본값설명
DOC_THRESHOLD0.25이 유사도 미만 문서 제외
DOC_TOP_K5유사도 상위 K개 문서만 사용
임베딩 모델text-embedding-3-small질문 및 문서 임베딩

app/api/chat/[botId]/route.ts 상단의 상수를 수정해 조정할 수 있습니다.

🗄️ 데이터베이스

Neon PostgreSQL을 사용합니다. 서버 최초 요청 시 스키마가 자동 생성됩니다.

테이블설명
tenants테넌트(업체) 정보
bots챗봇 설정 (type, prompt, model, widget_color 등)
qa_pairsQ&A 쌍 + 임베딩 벡터
doc_folders문서 폴더 구조 (계층형)
documents업로드된 문서 텍스트 + 임베딩 벡터
chat_logs세션별 대화 기록
📁 폴더 구조
프로젝트 구조 
chatbot/
├── app/
│   ├── layout.tsx                    # 사이드바 레이아웃
│   ├── page.tsx                      # 챗봇 카드 목록
│   ├── Sidebar.tsx                   # LNB + 가이드 패널 트리거
│   ├── GuidePanel.tsx                # 우측 슬라이드 가이드 패널
│   ├── admin/                        # 슈퍼 어드민 (테넌트 관리)
│   ├── bots/[id]/
│   │   ├── page.tsx                  # 봇 설정 + 임베드 코드
│   │   ├── qa/                       # Q&A 관리
│   │   ├── docs/                     # 문서 관리
│   │   ├── test/                     # 테스트 채팅
│   │   └── logs/                     # 대화 기록
│   └── api/
│       ├── chat/[botId]/route.ts     # 채팅 (RAG 포함)
│       ├── bots/[id]/docs/upload/    # 파일/폴더/ZIP 업로드
│       └── widget/[botId]/route.ts   # 위젯 설정 조회
├── lib/
│   ├── neon.ts                       # Neon PostgreSQL 클라이언트
│   ├── db.ts                         # 스키마 초기화 + 타입
│   └── embeddings.ts                 # 임베딩 + 코사인 유사도
├── public/
│   └── chatbot-widget.js             # 임베드 위젯
└── .env.local