Widgets para sitios web
Integra tu agente de voz IA en cualquier sitio web para que los visitantes puedan iniciar una conversación de voz directamente desde el navegador. La pestaña Widgets ofrece códigos de integración, opciones de personalización y ajustes de seguridad de dominio.
El Widget de devolución de llamada funciona de forma muy distinta a los widgets de esta página: en lugar de iniciar una llamada de voz en el navegador, recoge el número de teléfono del visitante y hace que tu agente lo llame de vuelta. Consulta la página dedicada Widget de devolución de llamada.
Tipos de widget
Hanc.AI ofrece cuatro tipos de widgets en navegador, además de un Widget de devolución de llamada independiente para llamadas telefónicas:
| Widget | Nombre de etiqueta | Descripción | Recomendado para |
|---|---|---|---|
| Widget flotante | hanc-ai-floating-call | Botón orbe que flota sobre tu página | Llamada a la acción siempre visible |
| Widget píldora | hanc-ai-pill-call | Botón compacto con forma de píldora colocado en línea en tu contenido | Huella mínima dentro de un diseño existente |
| Widget píldora flotante | hanc-ai-pill-float-call | Misma forma compacta de píldora, pero flota con la página como el widget flotante | Cuando quieres una estética de píldora que siga al visitante al hacer scroll |
| Widget en línea | hanc-ai-inline-call | Botón de llamada de tamaño completo integrado en el contenido de la página | Secciones dedicadas "Habla con nosotros" |
| Widget de devolución de llamada | hanc-ai-callback | Formulario de número de teléfono; el agente llama de vuelta al visitante | Páginas de captación de leads, landings de alta intención: ver Widget de devolución de llamada |
Atributos comunes
Todos los tipos de widget admiten estos atributos básicos:
| Atributo | Obligatorio | Descripción | Predeterminado |
|---|---|---|---|
agent-id | Sí | Identificador único de tu agente | — |
voice-service-url | No | Sobrescribir la URL del servicio de voz | Detección automática |
api-base-url | No | Sobrescribir la URL base de la API | Detección automática |
Atributos de visualización
| Atributo | Descripción | Valores | Predeterminado |
|---|---|---|---|
position | Posición del widget en la página | bottom-right, bottom-left, top-right, top-left, static | bottom-right |
size | Tamaño del widget en píxeles | Número | 120 |
theme | Nombre del tema de color | Ver Temas de color | default |
Atributos de texto del botón
| Atributo | Descripción | Predeterminado |
|---|---|---|
button-start-text | Texto mostrado en el botón inactivo | "Call" |
button-connecting-text | Texto mostrado durante la conexión | "Connecting..." |
button-end-text | Texto mostrado durante una llamada activa | — |
Atributos de términos
| Atributo | Descripción | Predeterminado |
|---|---|---|
terms-enabled | Activa el diálogo de consentimiento antes de la llamada | false |
terms-content | Texto de consentimiento en formato Markdown | "" |
terms-url | Enlace a tu página de Términos y Condiciones | "https://hanc.ai/terms" |
privacy-url | Enlace a tu página de Política de Privacidad | "https://hanc.ai/privacy" |
Los atributos de términos definidos en el elemento HTML son sobrescritos por la configuración de widget del agente obtenida desde la API, a menos que skip-fetch esté en true.
Atributos de sonido
| Atributo | Descripción | Predeterminado |
|---|---|---|
sound-enabled | Activa los sonidos de inicio/fin de llamada | true |
sound-volume | Volumen de los efectos de sonido | 0.25 |
sound-preset | Identificador del preset de sonido | "1" |
Temas de color
Personaliza la apariencia del widget con 11 temas de color integrados:
| Tema | Valor |
|---|---|
| Predeterminado | default |
| Púrpura | purple |
| Azul | blue |
| Cian | cyan |
| Esmeralda | emerald |
| Ámbar | amber |
| Mandarina | tangerine |
| Rosa | rose |
| Brasa | ember |
| Negro | black |
| Blanco | white |
Cada tema tiene variantes oscura y clara. Define el tema mediante el atributo theme en el código de integración, o configúralo en los ajustes de widget del agente.
Ejemplos de integración
Widget flotante
<hanc-ai-floating-call agent-id="YOUR_AGENT_ID"></hanc-ai-floating-call>
<script src="https://unpkg.com/hanc-webrtc-widgets" async type="text/javascript"></script>
Widget flotante con tema y posición
<hanc-ai-floating-call
agent-id="YOUR_AGENT_ID"
theme="emerald"
position="bottom-left"
size="140"
></hanc-ai-floating-call>
<script src="https://unpkg.com/hanc-webrtc-widgets" async type="text/javascript"></script>
Widget píldora
<hanc-ai-pill-call agent-id="YOUR_AGENT_ID"></hanc-ai-pill-call>
<script src="https://unpkg.com/hanc-webrtc-widgets" async type="text/javascript"></script>
Widget en línea
<hanc-ai-inline-call agent-id="YOUR_AGENT_ID"></hanc-ai-inline-call>
<script src="https://unpkg.com/hanc-webrtc-widgets" async type="text/javascript"></script>
La URL del script anterior siempre carga el último widget publicado: tu sitio recibe mejoras automáticamente. Si necesitas fijarlo a una versión conocida y estable, indícalo explícitamente con https://unpkg.com/hanc-webrtc-widgets@1.4.0 (sustituye por la versión que quieras). La etiqueta @latest es la predeterminada cuando no se especifica versión.
Eventos del widget
Los widgets emiten eventos que puedes escuchar en JavaScript:
| Evento | Descripción |
|---|---|
status-changed | Se dispara cuando cambia el estado de la llamada |
connecting | Se está estableciendo la llamada |
connected | La llamada está activa |
idle | No hay llamada activa |
error | Ocurrió un error |
audio-track | Se recibió la pista de audio remoto (para visualización) |
local-audio-track | Pista de audio del micrófono local (para visualización) |
microphone-enabled | Se activó el micrófono |
microphone-disabled | Se desactivó el micrófono |
call-start | Se dispara cuando una llamada se inicia correctamente |
call-end | Se dispara cuando finaliza la llamada |
Ejemplo: escuchar eventos
const widget = document.querySelector('hanc-ai-floating-call');
widget.addEventListener('call-start', () => {
console.log('Call started');
});
widget.addEventListener('call-end', () => {
console.log('Call ended');
});
Requisitos técnicos
Los widgets requieren que el navegador del visitante admita:
- WebGL 2.0: para renderizado
- Web Audio API: para procesamiento de audio
- WebRTC: para comunicación de voz en tiempo real
Todos los navegadores modernos (Chrome, Firefox, Safari, Edge) admiten estas tecnologías.
Restricciones de dominio
Controla qué sitios web pueden integrar el widget de tu agente.
Dominios siempre permitidos
Los siguientes dominios siempre están permitidos independientemente de la configuración:
hanc.ai(y subdominios)hanc.me(y subdominios)localhost
Permitir todos los dominios
Por defecto, tu widget puede integrarse en cualquier sitio web. Activa "Permitir todos los dominios" en los ajustes del widget para restringirlo.
Restringir a dominios específicos
Cuando esté restringido, añade cada dominio que deba permitirse:
- Introduce los nombres de dominio sin
https://(p. ej.,example.com) - Los subdominios necesitan entradas separadas (p. ej.,
www.example.com,shop.example.com) - Se pueden especificar puertos (p. ej.,
localhost:3000) - Se pueden incluir como máximo 50 dominios en la lista blanca
Para agentes en producción, restringe los widgets a tus propios dominios para evitar integraciones no autorizadas.
Términos y condiciones
Activa un diálogo de consentimiento antes de que los llamantes puedan iniciar una conversación.
Configuración
| Ajuste | Descripción |
|---|---|
| Activar términos | Activa o desactiva el diálogo de términos |
| Contenido de los términos | Texto de consentimiento en formato Markdown mostrado a los usuarios (máx. 5.000 caracteres) |
| URL de términos | Enlace a tu página completa de Términos y Condiciones |
| URL de privacidad | Enlace a tu página de Política de Privacidad |
Cuando está activado:
- Los usuarios ven un diálogo de consentimiento antes de iniciar una llamada
- Deben hacer clic en "Aceptar" para continuar
- El consentimiento se almacena localmente en el navegador
- El botón Restablecer consentimiento borra el consentimiento almacenado para pruebas
Formato del contenido
El contenido de los términos admite formato Markdown:
- Usa
####para encabezados - Usa
**negrita**para énfasis - Usa saltos de línea para mejorar la legibilidad
Relacionado
- Widget de devolución de llamada: devoluciones de llamada para visitantes que prefieren no hablar en el navegador
- Visión general de agentes de voz IA
- Ajustes: ajustes del agente incluida la configuración del widget
- Integraciones: claves API y configuración de números de teléfono