empleado.uno
← Todas las integraciones

Guía de integración del Agente-Web (voz)

Cómo montar el asistente de voz en tiempo real para que tu sitio conteste hablando.

v1.0.1 · actualizado el 2026-08-08

Ver markdown crudo

Integrar el Agente-Web (voz) de empleado.uno en tu sitio

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

El Agente-Web es un widget de voz en tiempo real (WebRTC): el visitante pulsa un botón,
habla con tu asistente de IA y este responde con voz al instante, con el mismo cerebro,
conocimiento y herramientas que el resto de tus canales. Se instala pegando un script.

1. Instalación en 2 minutos

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

<script>
  window.empleadoUnoAgentConfig = { agenteWebId: "TU_AGENTE_WEB_ID" };
</script>
<script src="https://sys.empleado.uno/sdk/agente-web.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-agente-web-config" strategy="afterInteractive">
          {`window.empleadoUnoAgentConfig = { agenteWebId: "TU_AGENTE_WEB_ID" };`}
        </Script>
        <Script src="https://sys.empleado.uno/sdk/agente-web.js" strategy="afterInteractive" />
      </body>
    </html>
  )
}

Requisitos:

  1. El dominio donde lo instalas debe estar en Dominios permitidos de la configuración
    (protección anti-abuso; sin esto el widget rechaza la llamada).
  2. El sitio debe servirse por HTTPS (el navegador no da acceso al micrófono en HTTP).

2. Opciones de window.empleadoUnoAgentConfig

Opción Tipo Qué hace
agenteWebId string (requerido) ID del widget, viene del dashboard.
position string Esquina donde aparece: bottom-right (default), bottom-left, top-right, top-left.
accent string (hex) Color de acento del botón y la interfaz.
launcherText string Texto del botón flotante.
greeting string Frase de invitación del panel.
baseUrl string Solo para entornos especiales; normalmente no lo necesitas.

Importante: el saludo, el color, el texto del botón, la posición y los límites de
llamada también se configuran en el dashboard, y ese valor manda sobre el del snippet.
Los cambios llegan al widget en tiempo real sin tocar tu web.

3. Posición del widget

Por defecto aparece abajo a la derecha. Dos formas de cambiarlo:

  1. Dashboard (recomendado): Agente-Web → Configuración → “Posición en la página”.
  2. Snippet: window.empleadoUnoAgentConfig = { agenteWebId: "…", position: "bottom-left" }.

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

4. Cómo funciona una llamada

  1. El visitante pulsa el botón y (la primera vez) deja nombre y correo.
  2. Un captcha invisible valida que no es un bot; el navegador pide permiso de micrófono.
  3. La llamada corre por WebRTC con tu asistente; hay controles de silenciar y colgar.
  4. Al terminar, la interacción queda registrada en tu cuenta (CRM, métricas y minutos).

La duración máxima por llamada y el tope diario de minutos se controlan desde el dashboard.

5. Seguridad (resumen para tu auditoría)

  • El navegador nunca recibe claves privadas: el backend emite credenciales efímeras por sesión.
  • Allowlist estricta de dominios y países; captcha invisible (Cloudflare Turnstile); límites de
    concurrencia y de minutos configurables.
  • El script se sirve siempre fresco (sin caché) desde https://sys.empleado.uno/sdk/agente-web.js.

6. Reglas para no romper el widget

  • No renombres las clases .eaw-* ni la variable global window.empleadoUnoAgentConfig.
  • No copies el contenido del script a tu bundle: referencia siempre la URL oficial.
  • No envuelvas el widget en contenedores con transform/filter CSS: rompen position:fixed.

7. 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 pide micrófono / no suena Sitio en HTTP o permiso denegado Sirve por HTTPS y revisa permisos del navegador.
“Servicio no disponible” Sin créditos/minutos de voz activos Revisa plan y minutos en el dashboard.
“Ocupado” Tope de llamadas simultáneas alcanzado Sube la concurrencia en el dashboard o reintenta.
Aparece en la esquina equivocada Posición configurada en el dashboard El dashboard manda sobre el snippet: cámbiala ahí.

8. 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 voz Agente-Web de empleado.uno en mi sitio siguiendo la guía oficial:
https://www.empleado.uno/api/public/docs/agente-web-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. El sitio debe servirse
por HTTPS.