Chat Autenticado (Intranet)

Qué es

El Chat Autenticado (Intranet) es una forma de publicar el chatbot dentro de una plataforma donde los usuarios ya iniciaron sesión (intranet, área de cliente, sistema web, ERP, etc.).

El chat reconoce automáticamente quién es el usuario, sin pedir inicio de sesión nuevamente, y mantiene el historial de conversación de cada persona separado y seguro.

1. Cuándo usarlo

Usa el modo Intranet cuando quieres que:

• La atención comience sabiendo quién es el usuario (sin formulario de identificación);
• El historial de conversaciones quede vinculado al ID del usuario en tu sistema;
• Nadie pueda hacerse pasar por otro usuario ni ver conversaciones de terceros.

2. Configurando en la plataforma

1. Accede a tu Proyecto → menú Chatbots → selecciona el chatbot deseado.
2. Haz clic en la pestaña Publicar y luego en la subpestaña Sitios.
3. Haz clic en Agregar.
4. En el modal “Publicar en Sitios o Sistemas Web”, completa:
   • Nombre de la publicación: un nombre interno para identificar esta conexión (ej.: “Portal del Cliente”);
   • Tipo de integración: selecciona “Intranet (Acceso Autenticado)”.
5. Haz clic en Guardar Publicación.

¡Listo! La nueva conexión aparece en el Listado de publicaciones.

3. Qué muestra la plataforma después de crear

Al expandir la publicación creada, verás dos datos esenciales y ejemplos de código:

3.1 Project ID

Identificador público de tu proyecto. Puede aparecer en el código de la página sin problema.

3.2 Secret Token (Intranet)

La clave secreta de la integración. Es la que el servidor de tu plataforma usa para autenticar a los usuarios en el chat.

⚠️ Nunca coloques el Secret Token en el código del navegador (HTML/JavaScript). Debe permanecer solo en el backend de tu aplicación. Si se filtra, cualquier persona podrá generar accesos en nombre de tus usuarios.

3.3 Ejemplos de código

La tarjeta muestra un ejemplo de llamada backend y un ejemplo de script frontend. Corresponden al Modo A de integración — existen dos formas de colocar el chat en tu plataforma, explicadas en la sección 5.

4. Cómo se conecta todo

┌─────────────────────┐  1. usuario logueado   ┌──────────────────────┐
│  Usuario en tu      │ ─────────────────────▶ │  Backend de tu       │
│  plataforma         │                        │  plataforma          │
└─────────────────────┘                        └──────────┬───────────┘
                                                          │ 2. POST /intranet-auth
                                                          │    (Secret Token + datos del usuario)
                                                          ▼
                                               ┌──────────────────────┐
                                               │  API Caramelo        │
                                               │  → valida el secreto │
                                               │  → crea/identifica   │
                                               │    el contacto       │
                                               │  → devuelve el token │
                                               └──────────┬───────────┘
                                                          │ 3. real_time_access_token (24h)
                                                          ▼
                                               ┌──────────────────────┐
                                               │  Tu página HTML      │
                                               │  recibe el token y   │
                                               │  carga el script     │
                                               └──────────┬───────────┘
                                                          │ 4. el chat abre ya identificado
                                                          ▼
                                               ┌──────────────────────┐
                                               │  Chatbot con el      │
                                               │  historial de ese    │
                                               │  usuario             │
                                               └──────────────────────┘

En resumen:

1. El usuario inicia sesión normalmente en tu plataforma;
2. Tu backend llama a la API de Caramelo con el Secret Token y los datos del usuario;
3. La API devuelve un token temporal exclusivo de ese usuario (campo real_time_access_token);
4. Tu página recibe ese token y lo pasa al script del chat (parámetro secure_connection_token);
5. El chat abre ya identificado, con el historial de conversaciones de esa persona.

📌 Atención: un mismo token, dos nombres.

Dónde aparece	Nombre usado
En la respuesta de la API (lo recibe tu backend)	real_time_access_token
En el script del chat (lo envía tu página)	secure_connection_token

Es el mismo valor: tu backend recibe real_time_access_token y tu página lo reenvía al script como secure_connection_token. A lo largo de esta guía, siempre que veas secure_connection_token, léase: “el real_time_access_token que la API devolvió”.

💡 Consejo: el token debe generarse en cada carga de página (expira en 24 horas). No reutilices tokens antiguos ni compartas un mismo token entre usuarios diferentes.

5. Las dos formas de integración

Existen dos modos de colocar el chat autenticado en tu plataforma. Ambos usan la misma llamada intranet-auth en el backend — lo que cambia es cómo llega el token hasta el script del chat:

🤔 ¿No sabes cuál elegir? Si tu página se genera en el servidor en cada acceso, usa el Modo A (más simple). Si tu aplicación corre en el navegador (React, Vue, Angular) o quieres controlar el momento de apertura del chat, usa el Modo B.

5.1 Modo A — Token inyectado por el servidor (SSR)

Paso 1 — Backend: al renderizar la página, tu servidor llama a la API de Caramelo con los datos del usuario logueado:

curl -X POST https://api.carameloai.com/api/chatbox/project/{PROJECT_ID}/intranet-auth \
  -H "Authorization: Bearer {SECRET_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "external_customer_id": "user-123",
    "name": "Nombre del Usuario",
    "email": "usuario@ejemplo.com"
  }'

Paso 2 — Frontend: tu servidor inyecta el token devuelto en el HTML de la página, junto con el script del chat:

<script>
  var carameloaiChatbot = {
    secure_connection_token: "<realtime_access_token_aquí>",
    project_id: "TU_PROJECT_ID",
    pluginVersion: "VERSIÓN_DEL_PLUGIN"
  };
</script>
<script src="https://static.carameloai.com/prod/index.js"></script>

El script carga, lee la configuración y abre el chat automáticamente, ya identificado.

5.2 Modo B — Bajo demanda (Async)

┌──────────────────┐  1. abre la página  ┌───────────────────────────┐
│ Usuario logueado │ ──────────────────▶ │  La página carga client.js│
└──────────────────┘                     │  (nada aparece todavía)   │
                                         └────────────┬──────────────┘
                                                      │ 2. CarameloChatbotClient.start()
                                                      ▼
                                         ┌───────────────────────────┐
                                         │  El SDK hace POST a TU    │
                                         │  endpoint (mismo origen)  │
                                         └────────────┬──────────────┘
                                                      │ 3. tu backend llama al
                                                      │    intranet-auth (con el Secret)
                                                      ▼
                                         ┌───────────────────────────┐
                                         │  El token vuelve al naveg.│
                                         │  → el chat abre identific.│
                                         └───────────────────────────┘

Paso 1 — Backend: crea un endpoint en tu dominio (ej.: /api/chatbot-token). Este identifica al usuario logueado por la sesión, llama al intranet-auth y devuelve el token:

// Ejemplo en Node.js / Express
app.post('/api/chatbot-token', async (req, res) => {
  const user = req.user; // usuario ya autenticado en TU plataforma
  if (!user) {
    return res.status(401).json({ error: 'unauthenticated' });
  }

  const response = await fetch(
    'https://api.carameloai.com/api/chatbox/project/TU_PROJECT_ID/intranet-auth',
    {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer TU_SECRET_TOKEN', // nunca expuesto al navegador
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        external_customer_id: user.id,
        name: user.name,
        email: user.email
      })
    }
  );

  const data = await response.json();
  res.json({ real_time_access_token: data.real_time_access_token });
});

Paso 2 — Frontend: carga el client.js apuntando a tu endpoint e inicia el chat cuando quieras:

<script>
  var carameloaiChatbot = {
    project_id: "TU_PROJECT_ID",
    auth_endpoint: "/api/chatbot-token",  // endpoint en TU dominio
    on_error: function (err) {
      console.error("Error al iniciar el chat", err);
    }
  };
</script>
<script src="https://static.carameloai.com/sdk/latest/client.js"></script>
<script>
  // El chat solo abre cuando tú lo ordenes — ej.: al hacer clic en un botón:
  document.getElementById("abrir-chat").addEventListener("click", function () {
    CarameloChatbotClient.start();
  });
</script>

6. Configuraciones visuales del chat

En la misma pantalla de la publicación, también puedes ajustar el comportamiento del widget (haz clic en Guardar después de modificar):

• Posición del chat en el sitio: esquina de la pantalla donde aparece el globo;
• Iniciar y mantener la caja de conversación abierta: el chat queda siempre abierto, sin opción de cerrar;
• Modo Compacto: el chat ocupa el menor tamaño posible;
• Retención de Atención: después de un tiempo de inactividad, la pestaña del navegador llama la atención y el chat queda brillando;
• Renderizar en un lugar fijo de la página: en lugar de flotar, el chat se muestra dentro de un <div> específico de tu layout.

7. Preguntas frecuentes