Referencia completa de API para integrar con la plataforma de Agente de Soporte al Cliente AI. Incluye autenticación, puntos finales, esquemas de solicitud/respuesta y ejemplos de código prácticos.
La API admite dos métodos de autenticación:
Genera tokens JWT de corta duración para la autenticación del widget. Este punto final permite a los widgets obtener tokens seguros utilizando solo el client_id, evitando la necesidad de exponer el client_secret en entornos de navegador.
<script src="https://widget.companin.tech/widget.js" data-widget-key="YOUR_WIDGET_KEY" data-instance-id="primary-widget"></script>Respuesta:
{ "token": "eyJ...", "expires_in": 3600, "token_type": "Bearer" }Las solicitudes de API están limitadas a 1000 por hora por organización. La información sobre la limitación de tasa se incluye en los encabezados de respuesta.
Todos los errores de API devuelven respuestas JSON estructuradas con códigos de estado, detalles de error y campos de datos opcionales.
{ "status": "error", "status_code": 401, "detail": "Authentication required - ...", "data": null }Gestiona las personalidades del agente de IA con configuraciones personalizadas.
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 }'Crea sesiones de visitantes anónimos para interacciones temporales.
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" } }'Crea conversaciones persistentes para usuarios autenticados.
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" } }'Almacena y gestiona el contexto del usuario para interacciones personalizadas.
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 } } }'Sube y gestiona fuentes de conocimiento para tus agentes.
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. Obtener token del widget para chat basado en navegador 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. Crear una sesión para visitante anónimo 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. Enviar mensaje del cliente y obtener respuesta de IA 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(); } // Ejemplo de uso const token = await getWidgetToken(); const session = await startSupportSession(token, 'agent-uuid'); const result = await sendMessage(token, session.data.id, 'Necesito ayuda con mi pedido');// 1. Crear contexto de usuario para personalización 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. Crear conversación persistente con contexto 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. Chatear con conocimiento del producto 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(); } // Ejemplo de uso 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, '¿Qué laptop recomiendas?');// 1. Subir documentación del producto 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. Agregar entradas de preguntas frecuentes 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. Agregar contenido web 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(); } // Ejemplo de uso const fileUpload = await uploadDocumentation(pdfFile, 'User Manual v2.0'); const faq = await addFAQ( '¿Cómo restablezco mi contraseña?', 'Ve a la configuración y haz clic en "Restablecer contraseña"...', ['password', 'security'] ); const webContent = await addWebContent( 'https://example.tech/blog/new-features', 'Anuncio de nuevas funciones' );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' }) })