Llamadas web: el agente en tu sitio
- Qué obtendrás:
- los visitantes de tu sitio hablan con el agente de la campaña por el micrófono del navegador, sin número de teléfono. La conversación aparece en el registro de la campaña marcada como «Web call»; el informe, el webhook y Telegram funcionan como en las llamadas telefónicas.
- Antes de empezar:
- una campaña «Voice Agent» con un modelo de IA en tiempo real, permisos de administrador del proyecto y acceso al código del sitio (una línea para el widget).
1. Activa las llamadas web en la campaña
- 1
- 2En «Allowed sites», añade los dominios desde los que se puede iniciar una conversación, p. ej. shop.example.com. La coincidencia es exacta: añade www.shop.example.com en una línea aparte.
- 3Si hace falta, cambia «Calls from one IP address per hour» (5 por defecto).
- 4Deja activado «Safe mode»: los visitantes son anónimos y, en este modo, el agente no anota nada en calendarios ni llama a APIs, aunque estén añadidos a la campaña.
- 5Haz clic en «Save web call settings».
Los minutos se descuentan del saldo o del paquete igual que las llamadas telefónicas de la campaña. Las llamadas simultáneas y la duración también siguen la configuración de la campaña y del proyecto. Las acciones telefónicas (transferencia, devolución de llamada, «no llamar», tonos) nunca están disponibles en las llamadas web.
2. Opción A: un widget de una línea
La forma más sencilla: aparece un botón «Hablar con el agente» en una esquina de la página y nuestro script hace el resto.
- 1
- 2Copia la línea con «Copy». La clave se muestra solo una vez.
- 3En data-privacy-url indica la página de política de privacidad de tu sitio.
- 4Pega la línea en las páginas del sitio antes de </body>.
<script src="https://ai.ringostat.com/webcall/v1.js"
data-key="<CLAVE_DEL_WIDGET>"
data-privacy-url="/privacy"
data-lang="es" async></script>| Atributo | Qué define |
|---|---|
| data-key | La clave del widget. Obligatorio. |
| data-privacy-url | La política de privacidad del sitio; sirve una dirección relativa (/privacy). Obligatorio: sin él no aparece el botón. |
| data-lang | Idioma del botón y de los textos: uk, en, pl o es. Sin él, el idioma de la página (<html lang>); si no, inglés. |
| data-position | right (por defecto) o left: la esquina de la página para el botón. |
| data-color | Color del botón, p. ej. #16c07f (3, 4, 6 u 8 dígitos hex). |
| data-container | Un selector CSS, p. ej. #talk: el botón va dentro de ese elemento en vez de la esquina. Si el elemento aparece más tarde (una SPA), el widget lo espera hasta 10 segundos; un selector no válido deja el botón en la esquina con un aviso en la consola. |
| data-auto="false" | Sin nuestro botón: inicias la conversación desde el tuyo (ver abajo). |
Debajo del botón siempre se ve «Estás hablando con un agente de IA, no con una persona. La llamada se graba.» con un enlace a tu política. Un clic abre un panel con los mismos avisos; la conversación empieza solo con el botón del panel, después de permitir el micrófono.
Requisitos del sitio
El botón aparece solo donde el navegador puede dar el micrófono: una página HTTPS, un navegador con navigator.mediaDevices y, en un iframe, el atributo allow="microphone". Si no, no hay botón y sale un aviso en la consola con el prefijo [Ringostat]. Los navegadores integrados de Instagram o Telegram pueden no tener micrófono: el widget indica entonces abrir la página en Safari o Chrome.
Content-Security-Policy: permite script-src https://ai.ringostat.com y connect-src https://apiagent.ringostat.com wss://apiagent.ringostat.com. No hace falta style-src 'unsafe-inline': los estilos del widget son adoptedStyleSheets (los navegadores sin ellos reciben una etiqueta style, que necesita 'unsafe-inline').
SPA y constructores de páginas: cuando el framework vuelve a dibujar la página, el widget vuelve solo. Para mostrarlo o quitarlo desde el código, llama a RingostatWebCall.mount() y RingostatWebCall.unmount() (unmount termina la llamada). mount({ container: "#talk" }) acepta los mismos ajustes que los atributos data, sin el prefijo data-. En Google Tag Manager, pega la línea tal cual en una etiqueta «HTML personalizado».
Cómo obtiene el widget su token
Una clave de widget no necesita tu servidor: el navegador la envía él mismo a POST /web-call/widget-ticket. La solicitud solo se acepta desde una página de un sitio permitido (cabecera Origin), sin cookies; el cuerpo, hasta 8 KB y solo key y metadata. Una dirección IP puede enviar hasta 20 solicitudes por minuto. La respuesta es el mismo token que da webCall.create, o un error con un código de la tabla de abajo y la cabecera Retry-After.
POST https://apiagent.ringostat.com/web-call/widget-ticket
Origin: https://shop.example.com
Content-Type: application/json
{ "key":"<CLAVE_DEL_WIDGET>", "metadata":{ "page":"https://shop.example.com/pricing" } }
→ 200 { "ok":true, "ticket":{ "token":"wct1.…", "wsUrl":"wss://apiagent.ringostat.com/ws/web-call",
"expiresIn":20, "maxDurationSec":180, "callId":"…" } }
→ 403 { "ok":false, "error":{ "code":"origin_not_allowed", "message":"…" } }Tu propio botón en lugar del nuestro
Con data-auto="false" el script no muestra el botón y te da el objeto RingostatWebCall. Una conversación solo puede empezar dentro del clic del usuario: si no, el navegador no da el micrófono. Los avisos de agente de IA y de grabación con el enlace a la política los muestras tú, junto a tu botón.
<script src="https://ai.ringostat.com/webcall/v1.js"
data-key="<CLAVE_DEL_WIDGET>" data-auto="false"></script>
<script>
const call = RingostatWebCall.create({ key: "<CLAVE_DEL_WIDGET>" });
call.on("state", (s) => console.log(s.status)); // connecting → live → ended
call.on("transcript", (t) => console.log(t.role, t.text));
call.on("end", (e) => console.log(e.reason, e.code)); // code: si es un error
talkButton.onclick = () => call.start().catch((err) => console.log(err.code));
stopButton.onclick = () => call.stop();
muteButton.onclick = () => call.setMuted(true);
</script>Un objeto es una conversación: para la siguiente, crea otro con RingostatWebCall.create.
3. Opción B: a través de tu servidor (API)
Para sitios y aplicaciones que deciden ellos mismos a quién dar una conversación: solo a clientes con sesión iniciada, tras una captcha, etc. Tu servidor obtiene un token de un solo uso con webCall.create y se lo pasa al navegador.
- 1Crea una clave «Web calls only»: «Settings» → «Advanced settings» → «+ Generate New Key» → acceso de la clave «Web calls only», y si quieres, campañas. Esa clave solo puede llamar a webCall.create; guárdala en tu servidor y nunca la pongas en una página.
- 2Cuando el visitante hace clic en tu botón y permite el micrófono, el navegador pide un token a tu servidor.
- 3El servidor llama a webCall.create con la IP del visitante y devuelve token y wsUrl al navegador. El token dura 20 segundos y sirve una sola vez.
- 4El navegador se conecta a wsUrl con ese token y empieza la conversación.

POST https://apiagent.ringostat.com/rpc
X-API-Key: <CLAVE_DE_LLAMADAS_WEB>
Content-Type: application/json
{ "jsonrpc":"2.0", "id":1, "method":"webCall.create",
"params":{ "campaignId":799, "clientIp":"203.0.113.7",
"externalId":"order-1842",
"metadata":{ "page":"https://shop.example.com/pricing", "utm_source":"google" } } }
→ "result": { "token":"wct1.…", "wsUrl":"wss://apiagent.ringostat.com/ws/web-call",
"expiresIn":20, "maxDurationSec":180, "callId":"…" }| Parámetro | Qué es |
|---|---|
| campaignId | ID de una campaña con las llamadas web activadas. Obligatorio. |
| clientIp | La IP pública del visitante tal como la ve tu servidor. Obligatorio: el límite por hora por IP se cuenta con ella. Las direcciones privadas y locales se rechazan. |
| externalId | Tu propio identificador (hasta 128 caracteres) para vincular la conversación con tus datos. |
| metadata | Solo las claves page, utm_source, utm_medium, utm_campaign, utm_term, utm_content y source, con valores de texto. El agente nunca las ve; page se guarda sin la query ni #. |
En el navegador, el mismo script lleva la conversación: en lugar de una clave de widget pasa getTicket, una función que pide el token a tu servidor. El script pide primero el micrófono, luego llama a getTicket y se conecta.
<script src="https://ai.ringostat.com/webcall/v1.js" data-auto="false"></script>
<script>
const call = RingostatWebCall.create({
// tu endpoint: comprueba al visitante y llama a webCall.create
getTicket: () => fetch("/api/web-call-token", { method: "POST" }).then((r) => r.json()),
});
talkButton.onclick = () => call.start(); // eventos y stop: como en el ejemplo de arriba
</script>Sin el SDK: abre un WebSocket a wsUrl con dos subprotocolos: ringostat-web.v1 y token.<token>. Envía el micrófono como {"type":"audio","data":<base64>}: PCM16 mono 48 kHz en tramas de 20–40 ms; termina la conversación con {"type":"stop"}. El servidor envía audio (mismo formato), state, transcript_ai y transcript_user, y al final end con el motivo.
Errores
| Código | Qué significa | Qué hacer |
|---|---|---|
| origin_not_allowed | La página no es de un sitio permitido (widget). | Añade el dominio a «Allowed sites», www por separado. |
| web_calls_disabled | Las llamadas web están desactivadas en la campaña. | Actívalas en el bloque «Web calls». |
| busy | Todas las llamadas simultáneas de la campaña o del proyecto están ocupadas. | Reintenta tras Retry-After segundos; si hace falta, aumenta las llamadas simultáneas. |
| rate_limited | Se agotó el límite por IP o de solicitudes. | Espera retry_after_seconds o sube el límite por IP. |
| insufficient_funds | El proyecto no tiene fondos para una llamada. | Recarga el saldo o el paquete. |
| not_found | No existe la campaña, es de otro proyecto o la clave no está vinculada a ella. | Revisa campaignId y las campañas de la clave. |
| unavailable | Las llamadas web no empezarán ahora: el motivo está bajo el interruptor del bloque. | Mira el motivo en el panel. |
| mic_denied | El visitante no permitió el micrófono (solo en el navegador). | Pide permitir el micrófono para el sitio e inténtalo de nuevo. |
| mic_not_found | No hay micrófono o lo usa otra aplicación. | Conecta un micrófono o cierra la aplicación que lo usa. |
| mic_unsupported | El navegador no da micrófono a las páginas (integrado en una app o antiguo). | Abre la página en Safari o Chrome. |
webCall.create devuelve el código en error.data.code con el estado HTTP correspondiente; el widget muestra al visitante un texto breve y claro en lugar del código.
Cómo desactivarlo
Desactiva «Let visitors talk to the agent in the browser» en la campaña o elimina la clave: no empezarán conversaciones nuevas y las activas terminarán.
Qué sigue
- Llamadas web: tu propia interfaz con el SDK — tu propio botón y animación, SPA, Tilda, WordPress, GTM.
- API y webhooks — resultados de las llamadas web en tu CRM.
- Métodos /rpc con ejemplos — webCall.create entre los demás métodos.

