---
title: "Widget de voz integrable"
description: "Agrega un agente de voz con IA a cualquier sitio web con unas pocas líneas de código"
---
El widget de voz integrable de ThunderPhone permite que quienes visitan tu sitio web hablen con un agente de IA directamente desde el navegador. No se requiere una llamada telefónica: los usuarios hacen clic en un botón e inician una conversación de voz en tiempo real impulsada por ThunderPhone.
El widget se muestra como una barra de cristal esmerilado que se adapta a temas claros y oscuros, con colores de acento y posicionamiento personalizables. Se distribuye como el paquete npm `@thunderphone/widget` y también está disponible mediante CDN para entornos sin empaquetador.
## Requisitos previos
Antes de integrar el widget, completa estos tres pasos en el [Panel de ThunderPhone](https://app.thunderphone.com):
Ve a **Widgets web** en el panel y crea un widget. Selecciona el agente que quieres poner a disposición. Cada widget tiene su propia clave publicable (`pk_live_...`), que es segura para incluir en código del lado del cliente; el agente se determina a partir de la clave.
En el mismo widget, agrega los dominios donde se incorporará. Se admiten comodines (por ejemplo, `*.example.com`). La lista evita que el widget funcione si alguien copia tu clave en otro sitio; no es autenticación, ya que un script fuera de un navegador puede enviar cualquier encabezado `Origin`. `localhost` no se permite automáticamente en producción: agrégalo a la lista para realizar pruebas locales con la API de producción.
Si tu página establece `language`, `voice` o `context`, activa cada una en **Sobrescrituras del navegador**. Los widgets nuevos no aceptan ninguna, y una solicitud de sesión que incluya una configuración desactivada falla con `400 override_not_allowed`. Consulta [Sobrescrituras del navegador](/es/guides/embed-web-widget).
Las claves publicables (`pk_live_...`) **no** son lo mismo que tus tokens secretos de API. Las claves publicables están diseñadas para usarse del lado del cliente y se limitan a las sesiones del widget en tus dominios permitidos. Nunca uses tu token secreto de API en código del lado del cliente.
Las sesiones de widget terminan después de 30 minutos de forma predeterminada, o antes si la duración máxima de llamada del propio agente es menor. Cambia el límite por clave con `max_call_duration_seconds` en la [clave publicable](/api-reference/publishable-keys) (hasta 6 horas), o establécelo en `null` para usar el límite del propio agente.
---
## Inicio rápido
Instala el paquete:
```bash
npm install @thunderphone/widget
```
Agrega el widget a tu aplicación:
```tsx
import { ThunderPhoneWidget } from '@thunderphone/widget'
import '@thunderphone/widget/style.css'
function App() {
return (
)
}
```
Eso es todo. Tus usuarios verán una barra de llamada de cristal esmerilado que los conecta con tu agente de IA con un solo clic.
---
## Personalización
El widget tiene cuatro props de apariencia:
| Prop | Predeterminado | Descripción |
|------|---------|-------------|
| `theme` | `'light'` | `'light'` para cristal blanco, `'dark'` para cristal oscuro |
| `primaryColor` | `'#000000'` (claro) / `'#ffffff'` (oscuro) | Color de acento para el botón de inicio, la forma de onda y el indicador de conexión |
| `title` | `'Voice assistant'` | Texto mostrado en el widget |
| `position` | `'bottom-right'` | Esquina de la ventana gráfica: `'bottom-right'`, `'bottom-left'`, `'top-right'`, `'top-left'` |
```tsx Light theme (default)
```
```tsx Dark theme with custom color
```
Otras tres propiedades personalizan la sesión en lugar de la apariencia -- todas se envían a la solicitud de sesión cuando inicia una llamada. Cada una funciona solo cuando la clave publicable del widget lo permite en **Anulaciones del navegador**; de lo contrario, la solicitud de sesión falla con `400 override_not_allowed`:
| Prop | Descripción |
|------|-------------|
| `language` | Anulación de idioma por sesión: un código o configuración regional como `en`, `es` o `fr-FR` |
| `voice` | Anulación de voz por sesión: un nombre de voz como `maria` |
| `context` | Contexto factual de la página o el sitio que se pasa al agente (truncado del lado del servidor a 12,000 caracteres) |
Consulta la [referencia del componente React](/es/widget/react) para ver la tabla completa de props.
Para una interfaz de usuario completamente personalizada, usa el [hook sin interfaz](/es/widget/headless-hook) para administrar la sesión de voz mientras creas tu propia interfaz. El hook expone niveles de audio en tiempo real para crear visualizaciones que reaccionan al audio.
Cada conversación del widget es una llamada. Cuenta para el [límite de llamadas simultáneas](/api-reference/introduction#call-limits) de tu organización (20 llamadas en curso de forma predeterminada, compartidas con llamadas telefónicas y de otros tipos) y para un límite del widget de 25 sesiones activas (o tu límite de llamadas simultáneas, si es mayor). Al alcanzar cualquiera de los dos límites, no se puede iniciar una nueva conversación hasta que termine una llamada.
---
## Opciones de integración
Elige el método de integración que se adapte a tu plataforma:
Componente de interfaz preconfigurado con controles de llamada y visualización de estado integrados. Importa, pasa props y listo.
Control total sobre la interfaz. El hook `useThunderPhone` administra la sesión de voz mientras creas tu propia interfaz.
No se requiere bundler. Carga el widget mediante una etiqueta de script para sitios estáticos, WordPress y otros entornos que no usan React.
---
## Estilos
El widget incluye temas claros y oscuros integrados controlados por la prop `theme`, y un color de acento controlado por la prop `primaryColor`. Para una personalización más profunda, puedes sobrescribir propiedades y clases personalizadas de CSS. Consulta la [guía de estilos](/es/widget/styling) para obtener más detalles.
¿Necesitas ayuda? Contáctanos en [support@thunderphone.com](mailto:support@thunderphone.com)