Guía de integración del Webchat

Cómo incrustar el chat en cualquier página web y adaptarlo a tu marca en unos minutos.

v1.0.1 · actualizado el 2026-08-08

Integrar el Webchat de empleado.uno en tu sitio

Audiencia: desarrolladores y agentes de IA (Cursor, Claude Code, v0, Lovable, …) a los que
les pidieron “instala este chat en mi web”. Esta es la guía oficial. Con el snippet y esta
página tienes todo lo necesario; no hay pasos ocultos.

El Webchat es un widget de chat con IA que atiende a los visitantes de tu sitio: responde con el
conocimiento configurado en tu cuenta, captura contactos en el CRM y escala a un humano cuando
hace falta. Se instala pegando un script; toda la apariencia y el comportamiento se gestionan
desde el dashboard y llegan al widget en tiempo real (no hay que tocar el código de nuevo).

1. Instalación en 2 minutos

Pega esto antes del cierre de </body> (reemplaza TU_WEBCHAT_ID por el ID que te dio el
dashboard — en la sección Instalar ya viene relleno):

<script>
  window.empleadoUnoConfig = { webchatId: "TU_WEBCHAT_ID" };
</script>
<script src="https://sys.empleado.uno/sdk/webchat.js" async defer></script>

En Next.js / React:

import Script from 'next/script'

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        {children}
        <Script id="eo-webchat-config" strategy="afterInteractive">
          {`window.empleadoUnoConfig = { webchatId: "TU_WEBCHAT_ID" };`}
        </Script>
        <Script src="https://sys.empleado.uno/sdk/webchat.js" strategy="afterInteractive" />
      </body>
    </html>
  )
}

Requisito único: el dominio donde lo instalas debe estar en Dominios permitidos de la
configuración del webchat (protección anti-abuso). Si el widget muestra “Sitio no autorizado”,
es eso.

2. Opciones de `window.empleadoUnoConfig`

Opción	Tipo	Qué hace
`webchatId`	string (requerido)	ID del webchat, viene del dashboard.
`position`	string	Esquina donde aparece: `bottom-right` (default), `bottom-left`, `top-right`, `top-left`.
`user`	`{ name, email }`	Identidad conocida: el chat conecta directo sin pedir datos.
`metadata`	`{ user_id, token, tenant_id }`	Referencias de TU sistema; se guardan con la conversación (no son autenticación).
`internalLinks`	boolean	Opt-in: renderiza `[texto](/ruta)` de las respuestas como enlaces reales.
`baseUrl`	string	Solo para entornos especiales; normalmente no lo necesitas.

Importante: colores, textos, saludo, forma del botón y posición también se configuran en
el dashboard, y ese valor manda sobre el del snippet. Cambios en el dashboard se aplican en
tiempo real sin tocar tu web.

3. Posición del widget

Por defecto el chat aparece abajo a la derecha. Puedes cambiarlo de dos formas:

Dashboard (recomendado): Webchat → Apariencia → “Posición en la página”.
Snippet: window.empleadoUnoConfig = { webchatId: "…", position: "bottom-left" }.

Valores válidos: bottom-right, bottom-left, top-right, top-left.

4. Identificar al usuario (opcional)

Si el chat vive en una zona con sesión iniciada (portal de clientes, intranet), pásale el usuario
y el chat conecta directo, sin formulario:

<script>
  window.empleadoUnoConfig = {
    webchatId: "TU_WEBCHAT_ID",
    user: { name: "Ana Pérez", email: "ana@tuweb.com" },
    metadata: { user_id: "id-en-tu-sistema" },
  };
</script>
<script src="https://sys.empleado.uno/sdk/webchat.js" async defer></script>

5. Memoria de conversación

El widget recuerda al visitante (identificador local en su navegador) y reanuda la misma
conversación aunque cierre el chat, navegue a otra página o recargue: al reabrir se repinta el
historial. No tienes que hacer nada para habilitarlo.

6. Seguridad (resumen para tu auditoría)

El navegador nunca escribe directo a la base de datos: todo pasa por la API de la
plataforma con un token de solo lectura de corta vida.
Captcha invisible (Cloudflare Turnstile) contra bots; allowlist estricta de dominios; límites
de frecuencia por sesión.
El script se sirve siempre fresco (sin caché) desde https://sys.empleado.uno/sdk/webchat.js.

7. Reglas para no romper el widget

No renombres las clases .ewc-* ni la variable global window.empleadoUnoConfig.
No copies el contenido del script a tu bundle: referencia siempre la URL oficial (así recibes
mejoras automáticamente).
No envuelvas el widget en contenedores con transform/filter CSS: rompen position:fixed.

8. Solución de problemas

Síntoma	Causa probable	Solución
“Sitio no autorizado”	El dominio no está en Dominios permitidos	Agrégalo en el dashboard (incluye `https://` y el subdominio exacto).
“No pudimos validar la seguridad”	Bloqueadores/VPN interfieren con el captcha	Prueba sin bloqueadores u otra red.
“Servicio no disponible”	La cuenta no tiene créditos de IA activos	Revisa el plan/créditos en el dashboard.
El widget no aparece	El script no se cargó o `webchatId` inválido	Revisa la consola del navegador y el ID.
Aparece en la esquina equivocada	Posición configurada en el dashboard	El dashboard manda sobre el snippet: cámbiala ahí.

9. Prompt listo para tu agente de IA

Copia esto en tu asistente de código junto con tu snippet de la sección Instalar:

Integra el widget de webchat de empleado.uno en mi sitio siguiendo la guía oficial:
https://www.empleado.uno/api/public/docs/webchat-integration
Pega el snippet que te doy antes de </body> (o en el layout raíz si es Next.js), no renombres
nada del script y no lo copies inline: referencia la URL oficial del SDK.