talkmate-sdk

v1.0.2

Published

3 months ago

TalkMate AI Chatbot SDK for web applications - Build intelligent FAQ-based chatbots with ease

0High
0Medium
0Low

ggulbae

chatbot ai sdk react typescript talkmate faq customer-support widget javascript html web

TalkMate SDK

TalkMate AI 챗봇을 웹 애플리케이션에 쉽게 통합할 수 있는 TypeScript SDK입니다.

특징

🚀 간편한 통합: HTML과 React에서 모두 사용 가능
💬 실시간 채팅: WebSocket을 통한 실시간 메시지 교환
📚 FAQ 지원: 계층적 FAQ 시스템
🎨 커스터마이징: 테마, 색상, 위치 등 자유로운 설정
📱 반응형: 모바일과 데스크톱 모두 지원
🔧 TypeScript: 완전한 타입 지원

설치

npm install talkmate-sdk

빠른 시작

HTML에서 사용하기

<!DOCTYPE html>
<html>
<head>
    <title>TalkMate SDK Demo</title>
</head>
<body>
    <div id="talkmate-widget"></div>
    
    <script src="https://unpkg.com/talkmate-sdk/dist/index.js"></script>
    <script>
        const widget = new TalkMateSDK.HTMLWidget({
            container: '#talkmate-widget',
            config: {
                apiKey: 'your-api-key',
                baseUrl: 'https://api.talkmate.com',
                projectId: 'your-project-id'
            },
            widgetConfig: {
                position: 'bottom-right',
                theme: 'light',
                primaryColor: '#3B82F6',
                title: 'TalkMate'
            }
        });
    </script>
</body>
</html>

React에서 사용하기

import React from 'react';
import { TalkMateWidget } from 'talkmate-sdk';

function App() {
    return (
        <div>
            <h1>My App</h1>
            <TalkMateWidget
                config={{
                    apiKey: 'your-api-key',
                    baseUrl: 'https://api.talkmate.com',
                    projectId: 'your-project-id'
                }}
                widgetConfig={{
                    position: 'bottom-right',
                    theme: 'light',
                    primaryColor: '#3B82F6',
                    title: 'TalkMate'
                }}
                onMessage={(message) => {
                    console.log('New message:', message);
                }}
                onSessionChange={(session) => {
                    console.log('Session changed:', session);
                }}
            />
        </div>
    );
}

export default App;

API 참조

TalkMateClient

핵심 클라이언트 클래스로, API와의 모든 통신을 담당합니다.

import { TalkMateClient } from 'talkmate-sdk';

const client = new TalkMateClient({
    apiKey: 'your-api-key',
    baseUrl: 'https://api.talkmate.com',
    projectId: 'your-project-id',
    debug: true
});

// 메시지 전송
const response = await client.sendMessage('안녕하세요!');

// 세션 생성
const session = await client.createSession('새 대화');

// FAQ 항목 조회
const faqItems = await client.getFAQItems();

HTMLWidget

HTML 페이지에 챗봇 위젯을 추가합니다.

import { HTMLWidget } from 'talkmate-sdk';

const widget = new HTMLWidget({
    container: '#widget-container',
    config: {
        apiKey: 'your-api-key',
        projectId: 'your-project-id'
    },
    widgetConfig: {
        position: 'bottom-right',
        theme: 'dark',
        primaryColor: '#FF6B6B',
        showFAQ: true,
        showHistory: true
    },
    onMessage: (message) => {
        console.log('Message received:', message);
    }
});

// 위젯 열기/닫기
widget.open();
widget.close();

// 위젯 제거
widget.destroy();

TalkMateWidget (React)

React 애플리케이션에서 사용할 수 있는 챗봇 컴포넌트입니다.

import { TalkMateWidget } from 'talkmate-sdk';

<TalkMateWidget
    config={{
        apiKey: 'your-api-key',
        projectId: 'your-project-id'
    }}
    widgetConfig={{
        position: 'bottom-left',
        theme: 'auto',
        primaryColor: '#10B981',
        placeholder: '질문을 입력하세요...',
        welcomeMessage: '안녕하세요! 무엇을 도와드릴까요?'
    }}
    onMessage={(message) => {
        // 메시지 처리
    }}
    onSessionChange={(session) => {
        // 세션 변경 처리
    }}
    className="custom-widget"
    style={{ zIndex: 9999 }}
/>

설정 옵션

TalkMateConfig

interface TalkMateConfig {
    apiKey: string;           // 필수: API 키
    baseUrl?: string;         // API 기본 URL (기본값: http://localhost:8000/api/v1)
    projectId?: string;       // 프로젝트 ID
    userId?: string;          // 사용자 ID
    debug?: boolean;          // 디버그 모드 (기본값: false)
}

WidgetConfig

interface WidgetConfig {
    position?: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
    theme?: 'light' | 'dark' | 'auto';
    primaryColor?: string;
    showFAQ?: boolean;
    showHistory?: boolean;
    placeholder?: string;
    title?: string;
    welcomeMessage?: string;
}

이벤트 처리

SDK는 다양한 이벤트를 발생시킵니다:

client.on('message:received', (message) => {
    console.log('새 메시지:', message);
});

client.on('session:created', (session) => {
    console.log('새 세션:', session);
});

client.on('error', (error) => {
    console.error('오류 발생:', error);
});

FAQ 시스템

FAQ 항목은 계층적 구조를 지원합니다:

interface FAQItem {
    id: string;
    question: string;
    answer: string;
    parentId?: string;
    children?: FAQItem[];
    order: number;
    isActive: boolean;
}

테마 커스터마이징

CSS 변수 사용

.talkmate-widget {
    --primary-color: #3B82F6;
    --background-color: #ffffff;
    --text-color: #333333;
    --border-color: #e9ecef;
}

다크 테마

widgetConfig: {
    theme: 'dark'
}

브라우저 지원

Chrome 60+
Firefox 55+
Safari 12+
Edge 79+

라이선스

MIT License

지원

문제가 있거나 기능 요청이 있으시면 GitHub Issues에 문의해주세요.

변경 로그

1.0.0

초기 릴리스
HTML 위젯 지원
React 컴포넌트 지원
FAQ 시스템
실시간 채팅
테마 커스터마이징