Developer cookbook

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 sencillo.
   • 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 restringidas por origen. Debes indicar cada nombre de host que insertará el widget. localhost / 127.0.0.1 siempre están permitidos durante el desarrollo local.

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"]
  }'

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.

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.

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#