Ringostat
Entrar

Llamadas web: el agente en tu sitio

~7 min · Un botón «Hablar con el agente» en tu sitio: un widget de una línea o tu propia integración por API.
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. 1
    Editor de la campaña → bloque «Web calls» → «Let visitors talk to the agent in the browser».
    Bloque «Web calls»
    Bloque «Web calls»
  2. 2
    En «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.
  3. 3
    Si hace falta, cambia «Calls from one IP address per hour» (5 por defecto).
  4. 4
    Deja 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.
  5. 5
    Haz 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.

Si el bloque indica por qué las llamadas web no empezarán ahora (el modelo no es en tiempo real, no hay sitios, la campaña está archivada, etc.), corrígelo primero. Un miembro del proyecto ve el bloque, pero solo puede restringir el acceso: desactivar las llamadas o activar el modo seguro.

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. 1
    En el bloque «Web calls» → «Connection», abre la pestaña «Widget» y haz clic en «Create a widget key».
    Pestaña «Widget»
    Pestaña «Widget»
  2. 2
    Copia la línea con «Copy». La clave se muestra solo una vez.
  3. 3
    En data-privacy-url indica la página de política de privacidad de tu sitio.
  4. 4
    Pega 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>
data-keyLa clave del widget. Obligatorio.
data-privacy-urlLa política de privacidad del sitio; sirve una dirección relativa (/privacy). Obligatorio: sin él no aparece el botón.
data-langIdioma 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-positionright (por defecto) o left: la esquina de la página para el botón.
data-colorColor del botón, p. ej. #16c07f (3, 4, 6 u 8 dígitos hex).
data-containerUn 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.

El script se carga desde nuestro dominio, así que las actualizaciones llegan a tu sitio solas. Los cambios incompatibles saldrán como v2.js, y v1.js seguirá funcionando.

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».

La clave del widget es pública: se ve en el código de la página. Solo sirve para una cosa: iniciar una llamada web de esta campaña desde una página de un sitio permitido. Puedes revocarla en la página de claves API.

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.

  1. 1
    Crea 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.
  2. 2
    Cuando el visitante hace clic en tu botón y permite el micrófono, el navegador pide un token a tu servidor.
  3. 3
    El 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.
  4. 4
    El navegador se conecta a wsUrl con ese token y empieza la conversación.
Pestaña «API»: un ejemplo de solicitud para esta campaña
Pestaña «API»: un ejemplo de solicitud para esta campaña
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":"…" }
campaignIdID de una campaña con las llamadas web activadas. Obligatorio.
clientIpLa 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.
externalIdTu propio identificador (hasta 128 caracteres) para vincular la conversación con tus datos.
metadataSolo 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.

Protege la dirección de tu servidor que entrega los tokens: con tu propia sesión, una captcha o un límite. La comprobación del sitio (Origin) no es autenticación: un script puede falsificarla. Pide el micrófono antes de solicitar el token: el token dura solo 20 segundos.

Errores

origin_not_allowedLa página no es de un sitio permitido (widget).Añade el dominio a «Allowed sites», www por separado.
web_calls_disabledLas llamadas web están desactivadas en la campaña.Actívalas en el bloque «Web calls».
busyTodas 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_limitedSe agotó el límite por IP o de solicitudes.Espera retry_after_seconds o sube el límite por IP.
insufficient_fundsEl proyecto no tiene fondos para una llamada.Recarga el saldo o el paquete.
not_foundNo 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.
unavailableLas llamadas web no empezarán ahora: el motivo está bajo el interruptor del bloque.Mira el motivo en el panel.
mic_deniedEl 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_foundNo hay micrófono o lo usa otra aplicación.Conecta un micrófono o cierra la aplicación que lo usa.
mic_unsupportedEl 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