> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thunderphone.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Widget de voz integrable
> 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 **Desarrolladores** en la configuración del panel y crea una clave publicable. Las claves publicables comienzan con `pk_live_` y es seguro incluirlas en código del lado del cliente.
En la misma configuración de Desarrolladores, agrega los dominios donde se integrará el widget. `localhost` siempre está permitido para desarrollo. Se admiten comodines (por ejemplo, `*.example.com`).
Ve a **Widgets web** en el panel y crea un widget. Selecciona el agente que quieres exponer y la clave publicable que quieres usar. El agente se resuelve automáticamente a partir de la configuración de tu clave publicable.
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.
***
## Inicio rápido
Instala el paquete:
```bash theme={null}
npm install @thunderphone/widget
```
Agrega el widget a tu aplicación:
```tsx theme={null}
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) theme={null}
```
```tsx Dark theme with custom color theme={null}
```
Otras tres props personalizan la sesión en lugar de la apariencia; todas se reenvían a la solicitud de sesión cuando inicia una llamada:
| 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.
***
## 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)