Skip to main content
El widget web ofrece a quienes visitan tu sitio una conversación de clic para hablar con un agente de IA, mediante el micrófono del navegador. Es un SDK de JavaScript / React independiente con su propia referencia del SDK — esta guía se centra en la configuración de ThunderPhone que necesita el widget.
Puedes hacer todo esto sin cURL: la página del panel Widgets web (/dashboard/web-widgets) crea el widget, configura su modo y agente, administra los dominios permitidos y te proporciona el fragmento de inserción.

​
Requisitos previos

1

Crea un agente

El agente cuyo prompt y voz ejecutarán la sesión del widget. Configura widget_enabled: true (el valor predeterminado).
2

Decide el modo de enrutamiento

  • mode="agent" — un agente estático por clave. La opción más sencilla.
  • mode="webhook" — tu servidor elige el agente para cada visitante mediante un webhook web.incoming. Úsalo para usuarios con sesión iniciada, pruebas A/B o enrutamiento por página.
3

Enumera los dominios permitidos

Las claves publicables están bloqueadas por origen. Debes indicar cada nombre de host que incorporará el widget. localhost / 127.0.0.1 siempre están permitidos durante el desarrollo local.

​
Crea una clave publicable

La respuesta incluye una key que comienza con pk_live_.... Las claves publicables son públicas por diseño — es seguro incluirlas en tu paquete de front-end. Consulta la referencia de claves publicables para ver todos los campos.
allowed_domains debe contener al menos una entrada. *.example.com coincide con subdominios (por ejemplo, api.example.com), pero no con el dominio raíz. Se rechazan los comodines sin restricciones como * o *.*.

​
Integra el widget en tu sitio

En la documentación del SDK del widget se incluyen tres opciones de integración:

Componente de React

<ThunderPhoneWidget publishableKey="pk_live_..." />.

Hook sin interfaz

useThunderPhone() para interfaces personalizadas.

Etiqueta de script de CDN

ThunderPhone.mount({...}) para sitios sin empaquetador.
Las tres opciones aceptan la misma publishableKey y muestran el botón del micrófono junto con el elemento de audio durante la llamada. El context del widget se trunca a 12,000 caracteres (aproximadamente 3,400 tokens de texto típico en inglés) y cuenta para el recargo por tamaño de prompt.

​
Webhooks del modo widget

Cuando mode="webhook", ThunderPhone llama a tu webhook_url al iniciar cada sesión con una carga útil web.incoming. Devuelve la configuración del agente que quieres ejecutar para ese visitante — sigue el mismo esquema de respuesta que las llamadas telefónicas:
Puedes combinar el contexto de tu propia sesión (qué cliente está navegando, en qué página se encuentra) en el prompt e intercambiar agentes según el lanzamiento.

​
Observa las sesiones

Las sesiones del widget aparecen en GET /v1/calls con direction="widget" — misma transcripción, grabación, evaluación y facturación que las llamadas telefónicas. Filtra por direction para crear un panel exclusivo para widgets.

​
Próximos pasos

Referencia del SDK del widget

Detalles de integración con React / hook / CDN.

Configuración dinámica por llamada

Implementa el flujo mode="webhook" de principio a fin.

Referencia de claves publicables

Todos los campos del recurso de clave.

API de sesiones de micrófono

Omite el widget; controla LiveKit directamente para interfaces personalizadas.