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.
Si instalas el widget con la etiqueta de script estándar, no necesitas llamar esto tú mismo; la incrustación realiza el intercambio al cargar. Llama a esto directamente solo cuando estés construyendo tu propia superficie de chat contra la API. El Origin de la solicitud debe estar en la lista de orígenes permitidos de la aplicación, y los mints están limitados a 30 por minuto por 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" }'Respuesta:
{ "token": "eyJ...", "expires_in": 3600, "token_type": "Bearer" }Las solicitudes de API tienen un límite de tasa de 100 por hora por organización. Exceder el límite devuelve HTTP 429; las respuestas que llevan una sugerencia de retroceso incluyen un encabezado Retry-After. El tráfico de widgets se mide por separado y no se cuenta contra este presupuesto. Si necesitas un límite más alto, contáctanos.
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 }Llama a estos endpoints desde tu servidor. El X-API-Secret nunca debe llegar al navegador, y las solicitudes del navegador desde tu propio dominio son rechazadas por CORS — consulta Soporte CORS a continuación.
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.
Nota: POST /api/v1/knowledge/files/ registra una entrada de archivo de conocimiento y su metadata — no acepta contenido de archivo. Para subir el archivo en sí, utiliza el panel de control, o POST datos de formulario multipart a /knowledge-base/ con una sesión de panel de control autenticada.
# 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. 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 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. 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 fileEntry = await registerDocumentation('User Manual v2.0', 'Setup and troubleshooting'); 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' }) })