Volledige API-referentie voor integratie met het Customer Support AI Agent-platform. Inclusief authenticatie, eindpunten, aanvraag-/antwoordschema's en praktische codevoorbeelden.
De API ondersteunt twee authenticatiemethoden:
Genereer kortlevende JWT-tokens voor widgetauthenticatie. Dit eindpunt stelt widgets in staat om veilige tokens te verkrijgen met alleen de client_id, waardoor de noodzaak om de client_secret in browseromgevingen bloot te stellen, wordt vermeden.
Als je de widget installeert met de standaard script-tag, hoef je dit zelf niet aan te roepen — de embed voert de uitwisseling uit bij het laden. Roep het alleen direct aan wanneer je je eigen chatoppervlak tegen de API bouwt. De Origin van het verzoek moet op de toegestane origin-lijst van de applicatie staan, en minten zijn beperkt tot 30 per minuut per IP.
curl -X POST https://app.companin.tech/api/v1/auth/widget-token \ -H "Content-Type: application/json" \ -H "Origin: https://your-site.example" \ -d '{ "client_id": "YOUR_CLIENT_ID" }'Antwoord:
{ "token": "eyJ...", "expires_in": 3600, "token_type": "Bearer" }API-aanvragen zijn beperkt tot 100 per uur per organisatie. Het overschrijden van de limiet retourneert HTTP 429; reacties die een backoff-hint bevatten, hebben een Retry-After-header. Widgetverkeer wordt apart gemeten en telt niet mee voor dit budget. Als je een hogere limiet nodig hebt, neem dan contact met ons op.
Alle API-fouten retourneren gestructureerde JSON-antwoorden met statuscodes, foutdetails en optionele gegevensvelden.
{ "status": "error", "status_code": 401, "detail": "Authentication required - ...", "data": null }Roep deze eindpunten aan vanaf je server. De X-API-Secret mag nooit de browser bereiken, en browserverzoeken van je eigen domein worden afgewezen door CORS — zie CORS-ondersteuning hieronder.
Beheer AI-agent persona's met aangepaste configuraties.
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 }'Creëer anonieme bezoekersessies voor tijdelijke interacties.
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" } }'Creëer persistente gesprekken voor geauthenticeerde gebruikers.
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" } }'Sla gebruikerscontext op en beheer deze voor gepersonaliseerde interacties.
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 } } }'Upload en beheer kennisbronnen voor uw agenten.
Opmerking: POST /api/v1/knowledge/files/ registreert een kennisbestandinvoer en de bijbehorende metadata — het accepteert geen bestandsinhoud. Om het bestand zelf te uploaden, gebruik het dashboard of POST multipart form data naar /knowledge-base/ met een geauthenticeerde dashboardsessie.
# Registers a knowledge file entry (metadata only — see the note above). 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" \ -H "Content-Type: application/json" \ -d '{ "title": "Product Manual", "file_type": "pdf", "summary": "Installation and troubleshooting guide" }'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. Verkrijg widgettoken voor browsergebaseerde chat 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. Creëer een sessie voor anonieme bezoeker 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. Stuur klantbericht en ontvang AI-antwoord 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(); } // Gebruik voorbeeld const token = await getWidgetToken(); const session = await startSupportSession(token, 'agent-uuid'); const result = await sendMessage(token, session.data.id, 'Ik heb hulp nodig met mijn bestelling');// 1. Creëer gebruikerscontext voor personalisatie 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. Creëer persistente conversatie met context 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. Chat met productkennis 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(); } // Gebruik voorbeeld 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, 'Welke laptop raadt u aan?');// 1. Upload productdocumentatie async function registerDocumentation(title, summary) { // Registers the entry + its metadata. File content is uploaded separately // (dashboard, or multipart POST to /knowledge-base/ with a dashboard session). 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', 'Content-Type': 'application/json' }, body: JSON.stringify({ title, file_type: 'pdf', summary }) }); return await response.json(); } // 2. Voeg FAQ-items toe 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. Voeg webinhoud toe 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(); } // Gebruik voorbeeld const fileEntry = await registerDocumentation('User Manual v2.0', 'Setup and troubleshooting'); const faq = await addFAQ( 'Hoe reset ik mijn wachtwoord?', 'Ga naar instellingen en klik op "Wachtwoord resetten"...', ['password', 'security'] ); const webContent = await addWebContent( 'https://example.tech/blog/new-features', 'Aankondiging nieuwe functies' );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' }) })