Inserta el widget web

Añade un agente de voz a tu sitio de marketing o soporte con una sola etiqueta de script; quienes lo visitan hablan con él directamente desde el navegador, sin necesidad de número de teléfono.

El widget web ofrece a los visitantes de tu sitio una conversación de clic para hablar con un agente de IA, usando el micrófono del navegador. Es un SDK independiente de JavaScript / React con su propia referencia del SDK — esta guía se centra en la configuración de ThunderPhone que necesita el widget.

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. El más simple.
   • mode="webhook" — tu servidor selecciona el agente por visitante mediante un webhook web.incoming. Úsalo para usuarios que iniciaron sesión, pruebas A/B o enrutamiento por página.
3. Enumera los dominios permitidos

   Indica cada nombre de host que incorporará el widget. Los navegadores envían el origen de la página con cada solicitud de sesión, por lo que la lista evita que tu clave funcione cuando alguien la copia en otro sitio. No es autenticación: un script fuera de un navegador puede enviar cualquier encabezado Origin. localhost no se permite automáticamente en producción; para realizar pruebas locales con la API de producción, agrega localhost a la lista.

4. Elige las anulaciones del navegador

   Decide qué configuraciones de sesión puede enviar tu página. Las claves nuevas no aceptan ninguna; consulta Anulaciones del navegador.

Crea una clave publicable#

curl -X POST https://api.thunderphone.com/v1/publishable-key \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name":            "Marketing site (prod)",
    "mode":            "agent",
    "agent_id":        12,
    "allowed_domains": ["example.com", "*.example.com"],
    "allowed_overrides": ["context"]
  }'

curl -X POST https://api.thunderphone.com/v1/publishable-key \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name":            "Support (dynamic)",
    "mode":            "webhook",
    "webhook_url":     "https://example.com/thunderphone/widget-hook",
    "allowed_domains": ["support.example.com"]
  }'

La respuesta incluye una key que comienza con pk_live_.... Las claves publicables son públicas por diseño — puedes incluirlas de forma segura en tu paquete de front-end. Consulta la referencia de claves publicables para ver todos los campos.

Añade el widget a tu sitio#

La documentación del SDK del widget cubre tres opciones de integración:

Las tres aceptan la misma publishableKey y muestran el botón del micrófono más el elemento de audio durante la llamada.

Anulaciones del navegador#

El widget puede enviar cuatro configuraciones por sesión desde la página:

Tu clave publicable es pública, por lo que cualquiera que la tenga puede enviar estas configuraciones, incluso desde un script que suplante tu dominio. Por lo tanto, cada una está desactivada hasta que la habilites en la clave: selecciónala en Anulaciones del navegador cuando crees o edites el widget en el panel, o configura allowed_overrides mediante la API de claves publicables. Permite solo lo que realmente envía tu página.

Una solicitud de sesión que incluya una configuración que la clave no permite falla con 400 y la indica:

{
  "error": "override_not_allowed",
  "fields": ["voice"],
  "message": "This publishable key does not allow the browser to set `voice`. ..."
}

La verificación se aplica en ambos modos. En el modo webhook, una configuración permitida también se reenvía a tu webhook web.incoming (context llega como website_context). Las claves creadas antes de que existiera esta configuración permiten las cuatro, por lo que las integraciones existentes siguen funcionando; desactiva lo que no uses.

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 del prompt. Se indica al agente que lo trate como contenido de la página, no como instrucciones.

Webhooks del modo widget#

Cuando mode="webhook", ThunderPhone llama a tu webhook_url al inicio de 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:

{
  "prompt":  "You are a VIP concierge for Jane Doe.",
  "voice":   "john",
  "product": "storm-base",
  "tools":   [ /* per-customer tools */ ]
}

Puedes combinar el contexto de tu propia sesión (qué cliente está navegando, en qué página está) en el prompt e intercambiar agentes en cada lanzamiento gradual.

Observa las sesiones#

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

Próximos pasos#