# 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):

```html
<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:

```jsx
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:

```text
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.
```
