고객 지원 AI 에이전트 플랫폼과 통합하기 위한 완전한 API 참조. 인증, 엔드포인트, 요청/응답 스키마 및 실용적인 코드 예제가 포함되어 있습니다.
API는 두 가지 인증 방법을 지원합니다:
위젯 인증을 위한 단기 JWT 토큰을 생성합니다. 이 엔드포인트는 클라이언트 ID만 사용하여 안전한 토큰을 얻을 수 있도록 하여 브라우저 환경에서 클라이언트 비밀을 노출할 필요가 없습니다.
<script src="https://widget.companin.tech/widget.js" data-widget-key="YOUR_WIDGET_KEY" data-instance-id="primary-widget"></script>응답:
{ "token": "eyJ...", "expires_in": 3600, "token_type": "Bearer" }API 요청은 조직당 시간당 1000회로 제한됩니다. 요금 제한 정보는 응답 헤더에 포함되어 있습니다.
모든 API 오류는 상태 코드, 오류 세부정보 및 선택적 데이터 필드가 포함된 구조화된 JSON 응답을 반환합니다.
{ "status": "error", "status_code": 401, "detail": "Authentication required - ...", "data": null }맞춤형 구성으로 AI 에이전트 페르소나를 관리하세요.
curl -X GET https://app.companin.tech/api/v1/agents/ \ -H "X-API-Key: YOUR_CLIENT_ID" \ -H "X-API-Secret: YOUR_CLIENT_SECRET"curl -X POST https://app.companin.tech/api/v1/agents/ \ -H "X-API-Key: YOUR_CLIENT_ID" \ -H "X-API-Secret: YOUR_CLIENT_SECRET" \ -H "Content-Type: application/json" \ -d '{ "name": "Customer Support Bot", "description": "Helpful agent for customer inquiries", "tone": "professional", "language": "en", "default_tasks": ["answer_questions", "provide_support"], "is_active": true }'임시 상호작용을 위한 익명 방문자 세션을 생성하세요.
curl -X POST https://app.companin.tech/api/v1/sessions/ \ -H "X-API-Key: YOUR_CLIENT_ID" \ -H "X-API-Secret: YOUR_CLIENT_SECRET" \ -H "Content-Type: application/json" \ -d '{ "agent_id": "550e8400-e29b-41d4-a716-446655440000", "visitor_id": "visitor-123", "locale": "en", "metadata": { "source": "website", "page": "/contact" } }'curl -X POST https://app.companin.tech/api/v1/sessions/${SESSION_ID}/messages \ -H "X-API-Key: YOUR_CLIENT_ID" \ -H "X-API-Secret: YOUR_CLIENT_SECRET" \ -H "Content-Type: application/json" \ -d '{ "content": "Hello, I need help with my order", "metadata": { "user_type": "customer" } }'인증된 사용자를 위한 지속적인 대화를 생성하세요.
curl -X POST https://app.companin.tech/api/v1/conversations/ \ -H "X-API-Key: YOUR_CLIENT_ID" \ -H "X-API-Secret: YOUR_CLIENT_SECRET" \ -H "Content-Type: application/json" \ -d '{ "agent_id": "550e8400-e29b-41d4-a716-446655440000", "customer_id": "user-456", "title": "Order Support", "locale": "en" }'curl -X POST https://app.companin.tech/api/v1/conversations/${CONVERSATION_ID}/messages \ -H "X-API-Key: YOUR_CLIENT_ID" \ -H "X-API-Secret: YOUR_CLIENT_SECRET" \ -H "Content-Type: application/json" \ -d '{ "content": "Can you help me track my order?", "metadata": { "order_id": "12345" } }'개인화된 상호작용을 위한 사용자 컨텍스트를 저장하고 관리하세요.
curl -X POST https://app.companin.tech/api/v1/contexts/ \ -H "X-API-Key: YOUR_CLIENT_ID" \ -H "X-API-Secret: YOUR_CLIENT_SECRET" \ -H "Content-Type: application/json" \ -d '{ "user_reference": "user-456", "traits": { "name": "John Doe", "email": "john@example.com", "subscription_tier": "premium", "preferences": { "language": "en", "notifications": true } } }'에이전트를 위한 지식 소스를 업로드하고 관리하세요.
curl -X POST https://app.companin.tech/api/v1/knowledge/files/ \ -H "X-API-Key: YOUR_CLIENT_ID" \ -H "X-API-Secret: YOUR_CLIENT_SECRET" \ -F "title=Product Manual" \ -F "file_type=pdf" \ -F "file=@product_manual.pdf"curl -X POST https://app.companin.tech/api/v1/knowledge/qa/ \ -H "X-API-Key: YOUR_CLIENT_ID" \ -H "X-API-Secret: YOUR_CLIENT_SECRET" \ -H "Content-Type: application/json" \ -d '{ "question": "What are your business hours?", "answer": "We are open Monday to Friday, 9 AM to 6 PM EST.", "tags": ["hours", "support"] }'// 1. 브라우저 기반 채팅을 위한 위젯 토큰 가져오기 async function getWidgetToken() { const response = await fetch('https://app.companin.tech/api/v1/auth/widget-token', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ client_id: 'YOUR_CLIENT_ID' }) }); return (await response.json()).token; } // 2. 익명 방문자를 위한 세션 생성 async function startSupportSession(token, agentId) { const response = await fetch('https://app.companin.tech/api/v1/sessions/', { method: 'POST', headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ agent_id: agentId, visitor_id: 'visitor-' + Date.now(), metadata: { source: 'support_widget' } }) }); return await response.json(); } // 3. 고객 메시지를 보내고 AI 응답 받기 async function sendMessage(token, sessionId, message) { const response = await fetch(`https://app.companin.tech/api/v1/sessions/${sessionId}/messages`, { method: 'POST', headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ content: message, metadata: { user_type: 'customer' } }) }); return await response.json(); } // 사용 예제 const token = await getWidgetToken(); const session = await startSupportSession(token, 'agent-uuid'); const result = await sendMessage(token, session.data.id, '주문에 도움이 필요합니다');// 1. 개인화를 위한 사용자 컨텍스트 생성 async function createUserContext(userId, userData) { const response = await fetch('https://app.companin.tech/api/v1/contexts/', { method: 'POST', headers: { 'X-API-Key': 'YOUR_CLIENT_ID', 'X-API-Secret': 'YOUR_CLIENT_SECRET', 'Content-Type': 'application/json' }, body: JSON.stringify({ user_reference: userId, traits: { name: userData.name, purchase_history: userData.purchases, preferences: userData.preferences } }) }); return await response.json(); } // 2. 컨텍스트가 있는 지속적인 대화 생성 async function startPersonalizedChat(agentId, userId) { const response = await fetch('https://app.companin.tech/api/v1/conversations/', { method: 'POST', headers: { 'X-API-Key': 'YOUR_CLIENT_ID', 'X-API-Secret': 'YOUR_CLIENT_SECRET', 'Content-Type': 'application/json' }, body: JSON.stringify({ agent_id: agentId, customer_id: userId, user_context_id: userId, title: 'Product Recommendations', metadata: { source: 'product_page' } }) }); return await response.json(); } // 3. 제품 지식으로 채팅하기 async function askAboutProduct(conversationId, question) { const response = await fetch(`https://app.companin.tech/api/v1/conversations/${conversationId}/messages`, { method: 'POST', headers: { 'X-API-Key': 'YOUR_CLIENT_ID', 'X-API-Secret': 'YOUR_CLIENT_SECRET', 'Content-Type': 'application/json' }, body: JSON.stringify({ content: question, metadata: { context: 'product_inquiry' } }) }); return await response.json(); } // 사용 예제 await createUserContext('user-123', { name: 'Alice', purchases: ['laptop-1', 'mouse-2'], preferences: { category: 'electronics' } }); const conversation = await startPersonalizedChat('agent-uuid', 'user-123'); const result = await askAboutProduct(conversation.data.id, '어떤 노트북을 추천하시나요?');// 1. 제품 문서 업로드 async function uploadDocumentation(file, title) { const formData = new FormData(); formData.append('title', title); formData.append('file_type', 'pdf'); formData.append('file', file); const response = await fetch('https://app.companin.tech/api/v1/knowledge/files/', { method: 'POST', headers: { 'X-API-Key': 'YOUR_CLIENT_ID', 'X-API-Secret': 'YOUR_CLIENT_SECRET' }, body: formData }); return await response.json(); } // 2. FAQ 항목 추가 async function addFAQ(question, answer, tags) { const response = await fetch('https://app.companin.tech/api/v1/knowledge/qa/', { method: 'POST', headers: { 'X-API-Key': 'YOUR_CLIENT_ID', 'X-API-Secret': 'YOUR_CLIENT_SECRET', 'Content-Type': 'application/json' }, body: JSON.stringify({ question, answer, tags, source: 'manual' }) }); return await response.json(); } // 3. 웹 콘텐츠 추가 async function addWebContent(url, title) { const response = await fetch('https://app.companin.tech/api/v1/knowledge/urls/', { method: 'POST', headers: { 'X-API-Key': 'YOUR_CLIENT_ID', 'X-API-Secret': 'YOUR_CLIENT_SECRET', 'Content-Type': 'application/json' }, body: JSON.stringify({ url, title }) }); return await response.json(); } // 사용 예제 const fileUpload = await uploadDocumentation(pdfFile, 'User Manual v2.0'); const faq = await addFAQ( '비밀번호를 어떻게 재설정하나요?', '설정으로 가서 "비밀번호 재설정"을 클릭하세요...', ['password', 'security'] ); const webContent = await addWebContent( 'https://example.tech/blog/new-features', '신규 기능 발표' );curl -X POST https://app.companin.tech/api/v1/auth/widget-token \ -H "Content-Type: application/json" \ -d '{"client_id":"YOUR_CLIENT_ID"}'fetch('https://app.companin.tech/api/v1/sessions', { method: 'POST', headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ agent_id: 'AGENT_UUID' }) })