Integración Web Autenticada

Visión General

Esta guía describe los pasos necesarios para implementar el chat de Caramelo AI de forma segura dentro de tu intranet o área autenticada, utilizando el flujo autenticado (Server-to-Server).

Este flujo garantiza que solo los usuarios autenticados en tu sistema puedan acceder al chatbot y que el historial de conversaciones se mantenga de forma segura y vinculado al usuario.

Cómo Funciona

El proceso consiste en dos pasos principales:

1. Backend (Server-to-Server): Tu servidor se comunica con la API de Caramelo AI enviando los datos del usuario autenticado y un token secreto. Nuestra API devuelve un token de conexión temporal (real_time_access_token).
2. Frontend: Tu servidor inyecta ese token temporal en el HTML de la página. El SDK de Caramelo AI utilizará ese token para iniciar la conexión segura del chatbot.

┌──────────────┐       POST /intranet-auth       ┌──────────────────┐
│  Tu Backend  │ ──────────────────────────────► │  API Caramelo AI │
│              │ ◄────────────────────────────── │                  │
│              │     real_time_access_token       │                  │
└──────┬───────┘                                  └──────────────────┘
       │
       │  Inyecta token en el HTML
       ▼
┌──────────────┐
│   Frontend   │ ──► SDK authenticated.js ──► WebSocket seguro
│   (Browser)  │
└──────────────┘

Prerrequisitos

Antes de comenzar, asegúrate de tener:

⚠️ Atención: El secret_token debe mantenerse en secreto en tu backend y NUNCA exponerse en el frontend.

Paso 1: Autenticación en el Backend (Server-to-Server)

Cuando el usuario acceda a la página del chat, tu servidor debe hacer una solicitud POST a la API de Caramelo AI antes de renderizar la página.

Endpoint

POST https://api.carameloai.com/api/chatbox/project/{project_id}/intranet-auth

Sustituye {project_id} por el ID de tu proyecto.

Headers

{
  "Content-Type": "application/json"
}

Body (JSON)

{
  "secret_token": "TU_SECRET_TOKEN",
  "external_customer_id": "12345",
  "name": "Juan García",
  "email": "juan@email.com",
  "lang": "es"
}

Parámetros

Respuesta Exitosa (200 OK)

{
  "real_time_access_token": "eyJhbGciOiJIUzI1NiIsIn...",
  "customer_id": "c_...",
  "chat": { ... },
  "chatbot": { ... }
}

El valor que necesitarás usar en el siguiente paso es real_time_access_token.

Paso 2: Configuración en el Frontend

Con el real_time_access_token devuelto por la API, tu servidor debe inyectarlo como secure_connection_token en el HTML de la página donde se mostrará el chatbot.

Agrega el siguiente código en tu página (idealmente antes del cierre de la etiqueta </body>):

<!-- 1. Configuración del Chatbot con el Token Seguro -->
<script>
    var carameloaiChatbot = {
        secure_connection_token: "INSERTA_AQUÍ_EL_REAL_TIME_ACCESS_TOKEN",
        project_id: "INSERTA_AQUÍ_EL_PROJECT_ID"
    };
</script>

<!-- 2. Inicialización del SDK (Modo Autenticado) -->
<script src="https://static.carameloai.com/sdk/latest/authenticated.js"></script>

⚠️ Importante: El archivo cargado en el paso 2 es authenticated.js, que es diferente del index.js usado en flujos públicos. No los mezcles.

Ejemplo Completo (Node.js / Express)

Aquí tienes un ejemplo simplificado de cómo tu backend podría generar la página:

const PROJECT_ID = "p_xyz123";
const SECRET_TOKEN = process.env.CARAMELO_SECRET_TOKEN;

app.get('/mi-intranet', async (req, res) => {
    // 1. Obtiene datos del usuario ya logueado en tu sistema
    const user = req.user;

    // 2. Llama a la API de Caramelo
    const response = await fetch(
        `https://api.carameloai.com/api/chatbox/project/${PROJECT_ID}/intranet-auth`,
        {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify({
                secret_token: SECRET_TOKEN,
                external_customer_id: user.id,
                name: user.name,
                email: user.email
            })
        }
    );

    const data = await response.json();
    const secureToken = data.real_time_access_token;

    // 3. Renderiza el HTML con el token inyectado
    res.send(`
        <html>
        <head><title>Mi Intranet</title></head>
        <body>
            <h1>Bienvenido, ${user.name}</h1>

            <!-- Inyección del token generado en el backend -->
            <script>
                var carameloaiChatbot = {
                    secure_connection_token: "${secureToken}",
                    project_id: "${PROJECT_ID}"
                };
            </script>
            <script src="https://static.carameloai.com/sdk/latest/authenticated.js"></script>
        </body>
        </html>
    `);
});

Preguntas Frecuentes