Chat Autenticado (Intranet)

Qué es

El Chat Autenticado (Intranet) es una forma de publicar el agente dentro de una plataforma en la que los usuarios ya iniciaron sesión, como una intranet, un área de cliente, un sistema web o un ERP.

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

1. Cuándo usar

Usa el modo Intranet cuando quieres que:

• La atención empiece 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 la conversación de otras personas.

2. Creando la conexión

1. Entra en el proyecto, haz clic en Robots Agentes de IA en el menú lateral y abre el agente.
2. Haz clic en la pestaña Canales.
3. Haz clic en Agregar canal. Si el agente todavía no tiene ninguna conexión, la lista de canales aparece directamente.
4. En el grupo Web, elige Web autenticada (intranet) y haz clic en Seleccionar.
5. En Destino y acceso, haz clic en Continuar. La plataforma avisa que se va a crear una conexión de intranet.
6. En Configuración, completa:
   • Nombre de la conexión: un nombre interno para reconocerla después, como “Portal del Cliente”;
   • Dominios permitidos (opcional): los sitios en los que el chat puede funcionar, uno por línea.
7. Haz clic en Crear conexión.

En la pantalla “Conexión creada”, haz clic en Gestionar conexión e instrucciones completas. A diferencia de los otros modos, la intranet no tiene un código listo para pegar: las credenciales y los ejemplos están en la página de la conexión.

⚠️ Atención: crear la conexión no publica una versión del agente. Mientras no se publique ninguna versión, el chat atiende con el borrador actual. Mira cómo publicar en Tu Primer Agente.

3. Lo que muestra la plataforma en la conexión

Para volver a la conexión después, abre la pestaña Canales, busca la conexión en Tus conexiones y haz clic en Gestionar.

3.1 Ejemplos de código

En Instalación, elige qué copiar:

• Backend (tu servidor): la llamada que hace tu servidor para autenticar a cada usuario;
• Frontend (navegador): el código que abre el chat en la página con el token que devuelve tu backend.

Los dos ya vienen con el Project ID de tu proyecto. Corresponden al Modo A de integración. Hay dos formas de poner el chat en tu plataforma, explicadas en la sección 5.

3.2 Secreto de la integración

En Credenciales y acciones, el bloque Secreto de la integración (intranet) guarda la clave secreta de la conexión. Es la que usa el servidor de tu plataforma para autenticar a los usuarios en el chat. El secreto está oculto: haz clic en Revelar secreto para verlo y copiarlo, y en Ocultar cuando termines. En los ejemplos de código aparece como SEU_SECRET_TOKEN.

⚠️ Nunca pongas el secreto en el código del navegador (HTML o JavaScript). Debe quedar solo en el backend de tu aplicación. Si se filtra, cualquier persona podrá generar accesos en nombre de tus usuarios.

4. Cómo se conecta todo

┌─────────────────────┐   1. inicia sesión     ┌──────────────────────┐
│  Usuario en tu      │ ─────────────────────▶ │  Backend de tu       │
│  plataforma         │                        │  plataforma          │
└─────────────────────┘                        └──────────┬───────────┘
                                                          │ 2. POST /intranet-auth
                                                          │    (secreto + 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 se abre ya identificado
                                                          ▼
                                               ┌──────────────────────┐
                                               │  Chat 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 secreto de la integración 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 se lo pasa al script del chat (parámetro secure_connection_token);
5. El chat se 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 (la 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 se lo pasa al script como secure_connection_token. A lo largo de esta guía, siempre que veas secure_connection_token, entiende “el real_time_access_token que devolvió la API”.

💡 Consejo: genera el token en cada carga de página, porque expira en 24 horas. No reutilices tokens antiguos ni compartas el mismo token entre usuarios distintos.

5. Las dos formas de integración

Hay dos modos de poner el chat autenticado en tu plataforma. Los dos usan el mismo script (sdk/latest/client.js) y la misma llamada intranet-auth en el backend. Lo que cambia es cómo llega el token hasta el 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 funciona en el navegador (React, Vue, Angular) o quieres controlar cuándo se abre el 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 que inició sesión:

curl -X POST https://api.carameloai.com/api/chatbox/project/SEU_PROJECT_ID/intranet-auth \
  -H "Authorization: Bearer SEU_SECRET_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "external_customer_id": "user-123",
    "name": "Nome do Usuário",
    "email": "usuario@exemplo.com"
  }'

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

<!-- Caramelo AI chatbot (intranet) -->
<script src="https://static.carameloai.com/sdk/latest/client.js"></script>
<script>
  window.CarameloChatbot
    .create({
      secure_connection_token: 'TOKEN_RETORNADO_PELO_SEU_BACKEND',
      project_id: 'SEU_PROJECT_ID'
    })
    .start();
</script>

El script se carga y abre el chat automáticamente, ya identificado.

📌 ¿Ya lo instalaste con el código antiguo? El formato anterior, con var carameloaiChatbot y el script prod/index.js, sigue funcionando.

5.2 Modo B: bajo demanda (async)

┌──────────────────┐  1. abre la página  ┌───────────────────────────┐
│  Usuario con     │ ──────────────────▶ │  Página carga client.js   │
│  sesión iniciada │                     │  (aún no aparece nada)    │
└──────────────────┘                     └────────────┬──────────────┘
                                                      │ 2. chat.start()
                                                      ▼
                                         ┌───────────────────────────┐
                                         │  El SDK hace POST a TU    │
                                         │  endpoint (mismo origen)  │
                                         └────────────┬──────────────┘
                                                      │ 3. tu backend llama al
                                                      │    intranet-auth (con el secreto)
                                                      ▼
                                         ┌───────────────────────────┐
                                         │  El token vuelve al       │
                                         │  navegador                │
                                         │  → el chat se abre ya     │
                                         │    identificado           │
                                         └───────────────────────────┘

Paso 1 (backend): crea un endpoint en tu dominio, como /api/chatbot-token. Identifica al usuario a partir de la sesión, llama a 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/SEU_PROJECT_ID/intranet-auth',
    {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer SEU_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): crea el chat apuntando a tu endpoint, con autoStart: false, e inícialo cuando quieras:

<script src="https://static.carameloai.com/sdk/latest/client.js"></script>
<script>
  var chat = window.CarameloChatbot.create(
    {
      project_id: 'SEU_PROJECT_ID',
      auth_endpoint: '/api/chatbot-token', // endpoint en TU dominio
      on_error: function (err) {
        console.error('Falha ao iniciar o chat', err);
      }
    },
    { autoStart: false }
  );

  // El chat solo se abre cuando tú lo indiques, por ejemplo al hacer clic en un botón:
  document.getElementById('abrir-chat').addEventListener('click', function () {
    chat.start();
  });
</script>

Si ya usas el formato antiguo, con var carameloaiChatbot y CarameloChatbotClient.start(), sigue funcionando.

6. Ajustando la apariencia

En Gestionar, las secciones Configuraciones y Avanzado tienen las mismas opciones del Chat Público: posición del globo, modo compacto, mantener chat abierto, contenedor fijo, temporización y dominios permitidos. Mira qué hace cada una en la guía del Chat Público. Haz clic en Guardar después de cambiar algo.

7. Preguntas frecuentes