Widget web y llamadas desde el navegador

Un agente publicado con el canal Web (WebRTC) se puede llamar desde cualquier navegador, sin teléfono. Hay dos formas de hacerlo:

• El widget: una página lista para usar que se inserta en tu web o se comparte como enlace. No hay que programar nada.
• Tu propia aplicación: tu equipo de desarrollo pide una llamada a NappAI y la integra en vuestra interfaz.

Las dos llaman a la versión publicada del agente, nunca al borrador.

Requisitos

1. El agente publicado con Web (WebRTC) marcado en Configurar consumo. Consulta Publicar un agente.
2. Una clave API de NappAI. Créala en Configuración → Claves API. Crea una para cada web donde pongas el widget: si algún día tienes que revocarla, no afecta al resto. Consulta Claves API.

El widget

1. Genera el enlace

Pulsa Widget en la fila del agente, o baja hasta Widget para tu web en Configurar consumo.

1. En Clave API que usará el widget, elige la clave.
2. En Modo de visualización, elige Avatar u Onda de audio.
3. Si quieres, personaliza el avatar.

Con la clave elegida aparecen la URL del widget, el botón Abrir vista previa y el Código de integración (iframe).

2. Pruébalo

Pulsa Abrir vista previa. El widget se abre en otra pestaña, tal como lo verán tus visitantes:

Pulsa Start Conversation, acepta el permiso del micrófono y habla.

3. Ponlo en tu web

Copia el Código de integración (iframe) y pégalo en tu página, o pásaselo a quien mantenga tu web. Tiene este aspecto:

<iframe
  src="https://<tu-instancia>/voice.html?q=..."
  width="400"
  height="600"
  frameborder="0"
  allow="microphone"
></iframe>

• Deja allow="microphone" tal cual. Sin él, el navegador no deja al widget usar el micrófono.
• La página donde lo pongas debe abrirse con https://. Los navegadores no dan el micrófono a páginas sin conexión segura.
• Ajusta width y height (ancho y alto) a tu diseño. El widget se adapta al tamaño.

Un enlace para compartir

La URL del widget también funciona sola: abre la llamada en una página completa. Sirve para mandarla por correo o chat, o para ponerla en un botón “Llámanos” o en un código QR.

Quién llama

Por teléfono, el agente sabe qué número le llama. En el widget puedes decirle tú quién es el visitante: un teléfono, un correo o un número de cliente, lo que tu web sepa de él.

• Para probarlo, escribe el valor en Caller (optional), en la misma ventana del widget. Se añade a la URL y al código de integración.
• Para que cada visitante llegue con el suyo, tu web añade al src del iframe &caller= con el valor en base64:

const caller = btoa(String.fromCharCode(...new TextEncoder().encode("+34600111222")));
iframe.src += "&caller=" + encodeURIComponent(caller);

El agente lo recibe antes de que hable el visitante, si Tell The Model About The Call está activado en el Voice Agent, y queda como llamante en el historial. Se le presenta como lo que dice la web, no como un dato comprobado: cualquiera que edite la URL puede cambiarlo, así que no lo uses para dar acceso a datos privados.

El enlace lleva la clave API

La URL del widget incluye la clave API que elegiste. Cualquiera que vea el código de tu página puede leerla. Por eso conviene una clave dedicada solo al widget. Si crees que se ha difundido donde no debía, revócala en Claves API y genera un código nuevo.

Desde tu propia aplicación

Si prefieres una interfaz propia, tu equipo de desarrollo tiene lo necesario en Configurar consumo → URLs de producción:

1. Vuestra aplicación envía una petición POST a la dirección Abrir llamada, con la clave API en la cabecera x-api-key y el Cuerpo de la petición que muestra la ventana.
2. NappAI responde con la dirección del servidor de voz (url) y un permiso de acceso para esa llamada (token).
3. Con esos dos datos, la aplicación entra en la llamada, envía el micrófono del usuario y reproduce la voz del agente. El agente dice su saludo en cuanto la persona se conecta.

Campo del cuerpo	Obligatorio	Qué es
client_id	Sí	El identificador del agente: el mismo que muestra Cuerpo de la petición.
user_name	No	El nombre con el que aparece la persona en la llamada.
caller	No	Quién llama, si vuestra aplicación lo sabe: un teléfono, un correo o un número de cliente. El agente lo ve como llamante. phone_number sigue funcionando para lo mismo.

Cada petición abre una llamada nueva, y su permiso de acceso solo sirve para esa llamada. Si el agente no está publicado o tiene Enabled desactivado, no se abre ninguna llamada.

Protege la clave

Haz la petición desde vuestro servidor y entrega al navegador solo la dirección y el permiso de acceso de la llamada. El permiso caduca y vale para una sola llamada; la clave API da acceso a tu cuenta.

Problemas habituales

Síntoma	Causa probable
El widget se queda conectando	El agente no está publicado con Web (WebRTC), o tiene Enabled desactivado.
El navegador no pide el micrófono	Falta allow="microphone" en el código insertado, o la página no se abre con https://.
Se conecta pero el agente no habla	Mira el historial: una llamada Fallida muestra el motivo, por ejemplo una credencial sin saldo.
El agente se oye a sí mismo	El visitante usa altavoces. Activa Echo Cancellation en el componente Voice Agent o recomienda auriculares.