Riferimento API

Riferimento API completo per l'integrazione con la piattaforma Assistant. Include autenticazione, endpoint, schemi di richiesta/risposta, ed esempi di codice pratici.

Autenticazione

L'API supporta due metodi di autenticazione:

Autenticazione con chiave API: Usa gli header X-API-Key e X-API-Secret per l'accesso diretto all'API
Autenticazione con token JWT: Usa i token Bearer ottenuti dall'endpoint del token widget per richieste basate su browser

Genera token JWT di breve durata per l'autenticazione dei widget. Questo endpoint permette ai widget di ottenere token sicuri usando solo il client_id, evitando la necessità di esporre il client_secret negli ambienti browser.

request.json

{"client_id": "YOUR_CLIENT_ID"}

Risposta:

response.json

{  "token": "eyJ...",  "expires_in": 3600,  "token_type": "Bearer"}

Limitazione di frequenza

Le richieste API sono limitate a 1000 all'ora per organizzazione. Le informazioni sulla limitazione di frequenza sono incluse negli header di risposta.

Gestione degli errori

Tutti gli errori API restituiscono risposte JSON strutturate con codici di stato, dettagli degli errori e campi dati opzionali.

error.json

{  "status": "error",  "status_code": 401,  "detail": "Authentication required - ...",  "data": null}

Endpoint API

Assistenti

Gestire le personas degli assistenti IA con configurazioni personalizzate.

Elenca assistenti

list-assistants.sh

curl -X GET https://app.companin.tech/api/v1/assistants/ \  -H "X-API-Key: YOUR_CLIENT_ID" \  -H "X-API-Secret: YOUR_CLIENT_SECRET"

Crea assistente

create-assistant.sh

curl -X POST https://app.companin.tech/api/v1/assistants/ \  -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 assistant for customer inquiries",    "tone": "professional",    "language": "en",    "default_tasks": ["answer_questions", "provide_support"],    "is_active": true  }'

Sessioni

Creare sessioni di visitatori anonimi per interazioni temporanee.

Crea sessione

create-session.sh

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 '{    "assistant_id": "550e8400-e29b-41d4-a716-446655440000",    "visitor_id": "visitor-123",    "locale": "en",    "metadata": {      "source": "website",      "page": "/contact"    }  }'

Invia messaggio nella sessione

send-message.sh

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"    }  }'

Conversazioni

Creare conversazioni persistenti per utenti autenticati.

Crea conversazione

create-conversation.sh

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 '{    "assistant_id": "550e8400-e29b-41d4-a716-446655440000",    "customer_id": "user-456",    "title": "Order Support",    "locale": "en"  }'

Invia messaggio nella conversazione

send-conversation-message.sh

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"    }  }'

Contesti utente

Archiviare e gestire il contesto utente per interazioni personalizzate.

Crea contesto utente

create-context.sh

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      }    }  }'

Base di conoscenze

Caricare e gestire fonti di conoscenza per i tuoi assistenti.

Carica file di conoscenze

upload-file.sh

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"

Aggiungi coppia domanda-risposta

add-qa.sh

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"]  }'

Casi d'uso

Chatbot di Supporto Clienti

support-chatbot.js

// 1. Ottieni token widget per chat basato su browserasync 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. Crea una sessione per visitatore anonimoasync function startSupportSession(token, assistantId) {  const response = await fetch('https://app.companin.tech/api/v1/sessions/', {    method: 'POST',    headers: {      'Authorization': `Bearer ${token}`,      'Content-Type': 'application/json'    },    body: JSON.stringify({      assistant_id: assistantId,      visitor_id: 'visitor-' + Date.now(),      metadata: { source: 'support_widget' }    })  });  return await response.json();}// 3. Invia messaggio cliente e ottieni risposta IAasync 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();}// Esempio di utilizzoconst token = await getWidgetToken();const session = await startSupportSession(token, 'assistant-uuid');const result = await sendMessage(token, session.data.id, 'Ho bisogno di aiuto con il mio ordine');

Assistente Prodotto E-commerce

ecommerce-assistant.js

// 1. Crea contesto utente per personalizzazioneasync 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. Crea conversazione persistente con contestoasync function startPersonalizedChat(assistantId, 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({      assistant_id: assistantId,      customer_id: userId,      user_context_id: userId,      title: 'Product Recommendations',      metadata: { source: 'product_page' }    })  });  return await response.json();}// 3. Chat con conoscenza prodottoasync 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();}// Esempio di utilizzoawait createUserContext('user-123', {  name: 'Alice',  purchases: ['laptop-1', 'mouse-2'],  preferences: { category: 'electronics' }});const conversation = await startPersonalizedChat('assistant-uuid', 'user-123');const result = await askAboutProduct(conversation.data.id, 'Quale laptop consigli?');

Sistema di Gestione della Conoscenza

knowledge-management.js

// 1. Carica documentazione prodottoasync 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. Aggiungi voci FAQasync 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. Aggiungi contenuto webasync 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();}// Esempio di utilizzoconst fileUpload = await uploadDocumentation(pdfFile, 'User Manual v2.0');const faq = await addFAQ(  'Come reimposto la mia password?',  'Vai alle impostazioni e clicca su "Reimposta password"...',  ['password', 'security']);const webContent = await addWebContent(  'https://example.tech/blog/new-features',  'Annuncio delle nuove funzionalità');

Esempi

Ottieni Token Widget

request.sh

curl -X POST https://app.companin.tech/api/v1/auth/widget-token \  -H "Content-Type: application/json" \  -d '{"client_id":"YOUR_CLIENT_ID"}'

Crea Sessione

createSession.js

fetch('https://app.companin.tech/api/v1/sessions', {  method: 'POST',  headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' },  body: JSON.stringify({ assistant_id: 'ASSISTANT_UUID' })})

Supporto CORS

Tutti gli endpoint supportano CORS per integrazioni web
Le richieste preflight sono gestite automaticamente
Le credenziali sono supportate per richieste autenticate

← Indietro Avanti: Panoramica →