Ringostat
Entrar

Llamadas web: interfaz propia (SDK)

~12 min · Para desarrolladores: el widget listo, tu propio botón y animación sobre el SDK o todo a través de tu servidor. SPA, instalación, requisitos.
Qué obtendrás:
una conversación con el agente de la campaña en tu sitio con la interfaz que necesites: desde una línea de código hasta tu propio botón, animación y tokens emitidos por tu servidor.
Antes de empezar:
una campaña con las llamadas web activadas y los sitios permitidos añadidos (ver «Llamadas web: el agente en tu sitio»), una clave de widget o una clave «Web calls only», acceso al código del sitio.

El script https://ai.ringostat.com/webcall/v1.js es a la vez el widget listo y el SDK para tu propia interfaz. Elige el nivel según cuánta interfaz quieras hacer tú:

A. Widget listoNada: el script dibuja el botón, el panel y los avisos; el aspecto viene del constructor del panel.Clave de widget (pública).
B. Interfaz propiaEl botón, los estados, la animación y los avisos; el SDK lleva la llamada.Clave de widget (pública).
C. Servidor propioLo mismo que en B y, además, tu servidor decide quién obtiene una conversación.Clave «Web calls only», solo en el servidor.

1. Nivel A: el widget listo del constructor

  1. 1
    Editor de la campaña → bloque «Web calls» → «Connection» → pestaña «Widget» → «Open builder».
  2. 2
    Elige «How to show»: «Floating button» (en la esquina de la pantalla), «Block on the page» (dentro de <div id="ringostat-call">) u «Own button» (nivel B, el código ya trae un botón).
  3. 3
    Ajusta el estilo, el color, el texto del botón, el nombre del agente, el idioma y los márgenes, guarda y copia el código. En data-privacy-url pon tu política de privacidad.
<script src="https://ai.ringostat.com/webcall/v1.js"
        data-key="<CLAVE_DEL_WIDGET>"
        data-privacy-url="https://example.com/privacy" async></script>

El aspecto se guarda en el panel: el widget lo lee al cargarse (GET /web-call/widget-config, espera como máximo 1,5 segundos y lo recuerda 5 minutos dentro de la pestaña). Por eso, tras cambiar algo en el constructor, el código del sitio no se toca; solo hace falta código nuevo si cambia «How to show». Si los ajustes no cargan, el botón aparece con el aspecto estándar.

Cualquier atributo data de la línea prevalece sobre lo guardado en el panel. Además de los atributos de la guía básica (data-lang, data-position, data-color, data-container), el aspecto lo definen:

data-styleorb: botón con esfera (por defecto); pill: botón simple; aura: la esfera viva de nuestra landing (carga v1-aura.js desde el mismo sitio que v1.js).
data-sizes, m o l.
data-labelTexto del botón, hasta 40 caracteres. Sin él, el texto estándar en el idioma del widget.
data-titleNombre del agente en el panel de la llamada, hasta 60 caracteres.
data-palettePara aura: default, dental, auto, realestate, shop o cuatro colores separados por comas "#oscuro,#principal,#menta,#celeste". Sin él, a partir de data-color.
data-motionPara aura: calm, normal o lively.
data-offset-x, data-offset-yDistancia del botón flotante al lateral y al borde inferior, 0–200 px (16 por defecto).

Un valor desconocido se sustituye por el estándar y la transparencia del color se descarta. Ningún atributo oculta los avisos de IA y grabación.

Idioma. Si el sitio ya tiene una línea antigua con el atributo data-lang, esta prevalece sobre el idioma del constructor. Si cambiaste el idioma en el constructor, sustituye una vez la línea antigua por la nueva; si no, el idioma no cambiará.
La misma clave dos veces como botón flotante (la línea en el tema y en GTM) da un solo widget y el aviso «duplicate snippet ignored» en la consola. Bloques en la página (data-container) puede haber varios.

2. Nivel B: tu propia interfaz con el SDK

Con data-auto="false" el script no dibuja nada y ofrece window.RingostatWebCall. El SDK lleva la llamada (micrófono, token, audio, interrupciones) y tú haces el botón, los estados y la animación. El modo «Own button» del constructor genera justo este tipo de código; abajo, de qué se compone.

RingostatWebCall.create({ key })Un nuevo objeto de conversación. Un objeto es una conversación: para la siguiente crea otro.
call.start()Pide el micrófono, obtiene un token y se conecta. Solo dentro del manejador de un clic, antes de cualquier await. Una Promise; si hay error, se rechaza con err.code.
call.stop()Termina la conversación por parte del visitante.
call.setMuted(true | false)Silencia y reactiva el micrófono; el agente recibe silencio y la llamada no se corta.
call.on(evento, fn)Suscripción a un evento; devuelve una función que la cancela.
state{ status, agentSpeaking, userSpeaking }; status: idle → connecting → live → ended.
transcript{ role: "agent" | "user", text, final, id }: subtítulos. Mientras final sea false, la frase aún se está precisando: sustituye su texto por id en lugar de añadirlo.
levelVolumen del micrófono del visitante, 0..1, unas 20 veces por segundo (0 si está silenciado).
outputLevelVolumen de la voz del agente, 0..1, unas 30 veces por segundo; 0 al final.
end{ reason, code? }, exactamente una vez. reason: user_ended, stop(); failed, la llamada no empezó; error, un error del servidor; disconnected, se cortó la conexión (sin code); cualquier otro, el servidor terminó la llamada (el agente se despidió, se agotó la duración). code aparece cuando reason es failed o error.

Errores: qué mostrar al visitante

El código llega en el evento end (e.code) y en err.code si start() se rechaza. Es cómodo mostrar los mensajes en un solo sitio, en end, y dejar que start().catch() solo absorba el rechazo.

mic_denied«Permite el acceso al micrófono para hablar con el agente» y cómo hacerlo: icono del candado o del micrófono en la barra de direcciones → permitir → «Otra vez».
mic_not_found«Micrófono no encontrado»: conecta uno o cierra la aplicación que lo está usando.
mic_unsupported«Este navegador no da acceso al micrófono: abre la página en Safari o Chrome». Pasa en los navegadores integrados de Instagram, Telegram, Facebook y en navegadores antiguos.
busy«El agente está ocupado, inténtalo en un minuto». En err.retryAfter, dentro de cuántos segundos.
rate_limited, daily_limit«Demasiados intentos, inténtalo un poco más tarde».
origin_not_allowed, web_calls_disabled, insufficient_fundsAl visitante: «La conversación no está disponible ahora». Son ajustes del panel: el sitio no está en «Allowed sites», las llamadas web están desactivadas, no hay saldo.
unavailable, timeout, connect_failed, audio_unavailable; reason disconnected«No se pudo conectar. Inténtalo de nuevo».

Ejemplo: tu propia esfera en ~20 líneas

Un botón, un círculo que «respira» al ritmo de la voz del agente (outputLevel), un estado, el silencio del micrófono y los avisos obligatorios con el enlace a la política. La página funciona tal cual: pon tu clave de widget, la dirección de la política y añade el dominio a «Allowed sites».

<div class="rwc">
  <div id="orb" class="orb" aria-hidden="true"></div>
  <button id="talk" type="button">Hablar con el agente</button>
  <button id="mute" type="button" hidden>Silenciar</button>
  <p id="status" role="status" aria-live="polite"></p>
  <p class="notice">Estás hablando con un agente de IA, no con una persona. La llamada se graba.
    <a href="https://example.com/privacy" target="_blank" rel="noopener">Política de privacidad</a></p>
</div>
<style>
  .orb { width: 96px; height: 96px; margin: 24px; border-radius: 50%; pointer-events: none;
         background: radial-gradient(circle at 35% 30%, #c6f7de, #16c07f 55%, #0a6646); transition: transform .1s; }
  .notice { font-size: 12px; color: #6b7686; }
</style>

<script src="https://ai.ringostat.com/webcall/v1.js" data-key="<CLAVE_DEL_WIDGET>" data-auto="false"></script>
<script>
  const ERRORS = {
    mic_denied: "Permite el acceso al micrófono para hablar con el agente.",
    mic_not_found: "Micrófono no encontrado.",
    mic_unsupported: "Sin micrófono: abre la página en Safari o Chrome.",
    busy: "El agente está ocupado. Inténtalo en un minuto.",
    rate_limited: "Demasiados intentos. Inténtalo un poco más tarde.",
    daily_limit: "Demasiados intentos. Inténtalo un poco más tarde.",
  };
  const FAIL = "No se pudo conectar. Inténtalo de nuevo.";
  const $ = (id) => document.getElementById(id);
  let call = null, muted = false;

  $("talk").onclick = () => {
    if (call) return call.stop();                  // el segundo clic termina la llamada
    call = RingostatWebCall.create({ key: "<CLAVE_DEL_WIDGET>" });
    call.on("state", (s) => {
      $("status").textContent = s.status === "live" ? "Habla, el agente te escucha" : s.status === "connecting" ? "Conectando…" : "";
      $("mute").hidden = s.status !== "live";
    });
    call.on("outputLevel", (v) => { $("orb").style.transform = "scale(" + (1 + v * 0.4) + ")"; });
    call.on("end", (e) => {
      call = null; muted = false;
      $("talk").textContent = "Hablar con el agente";
      $("mute").textContent = "Silenciar";
      $("status").textContent = e.code ? ERRORS[e.code] || FAIL
        : e.reason === "disconnected" ? FAIL : "¡Gracias por la conversación!";
    });
    $("talk").textContent = "Terminar";
    call.start().catch(() => {});                  // el mensaje lo muestra el evento end
  };
  $("mute").onclick = () => {
    muted = !muted;
    call && call.setMuted(muted);
    $("mute").textContent = muted ? "Activar micrófono" : "Silenciar";
  };
</script>

Subtítulos e indicador del micrófono: añade el marcado junto al botón y las suscripciones al manejador $("talk").onclick justo después de create() (antes del clic, call todavía es null). Los manejadores de eventos deben ser breves y no lanzar errores: un error en el manejador de level detiene ese fragmento del micrófono y el agente no oirá al visitante.

<!-- marcado: junto al botón -->
<p id="caption" aria-live="polite"></p>
<div style="height: 4px; background: #e6e6e6"><div id="mic" style="height: 4px; width: 0; background: #16c07f"></div></div>

// en el manejador $("talk").onclick, justo después de call = RingostatWebCall.create(...):
call.on("transcript", (t) => { if (t.role === "agent") $("caption").textContent = t.text; });
call.on("level", (v) => {
  const mic = $("mic");
  if (mic) mic.style.width = Math.round(v * 100) + "%";
});
Los avisos «Estás hablando con un agente de IA, no con una persona» y «La llamada se graba» con el enlace a la política de privacidad son obligatorios (EU AI Act, art. 50) y deben verse junto al botón antes de que empiece la conversación. En tu propia interfaz son responsabilidad tuya: no los ocultes, no los hagas menores de 12 px y no los quites de las páginas con el botón.

3. Nivel C: un token de tu servidor

Cuando la conversación no es para todos (solo clientes con sesión iniciada, tras un captcha, con tu propio límite), el token lo emite tu servidor con webCall.create y una clave «Web calls only». Guarda la clave en el servidor; nunca llega a la página. Los parámetros y códigos de error de webCall.create están en la sección «Opción B: a través de tu servidor» de la guía básica.

En el navegador la interfaz es la misma que en el nivel B; solo que en lugar de key va getTicket: una función que devuelve { token, wsUrl } de tu servidor. El SDK pide primero el micrófono, luego llama a getTicket (el token dura 20 segundos) y se conecta.

<script src="https://ai.ringostat.com/webcall/v1.js" data-auto="false"></script>
<script>
  // en lugar de RingostatWebCall.create({ key }) del ejemplo anterior:
  call = RingostatWebCall.create({
    getTicket: (signal) =>
      fetch("/api/web-call-token", { method: "POST", signal }).then((r) => r.json()),
  });
</script>
// Servidor (Node.js 18+, Express): POST /api/web-call-token
app.post("/api/web-call-token", async (req, res) => {
  // 1. Comprueba al visitante: tu sesión, captcha, límite.
  try {
    const r = await fetch("https://apiagent.ringostat.com/rpc", {
      method: "POST",
      headers: { "Content-Type": "application/json", "X-API-Key": process.env.RINGOSTAT_WEB_CALLS_KEY },
      body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "webCall.create",
        params: { campaignId: 799, clientIp: req.ip } }),   // IP pública del visitante
      signal: AbortSignal.timeout(10000),
    });
    const { result, error } = await r.json();
    if (!result) return res.status(503).json({ code: (error && error.data && error.data.code) || "unavailable" });
    res.json({ token: result.token, wsUrl: result.wsUrl });  // solo esto, nunca la clave
  } catch {
    res.status(503).json({ code: "unavailable" });  // Ringostat no responde, tardó más de 10 s o no devolvió JSON
  }
});

Si getTicket se rechaza o devuelve algo distinto de { token, wsUrl } con una dirección wss://, la llamada termina con el código unavailable. Tu endpoint puede devolver el motivo del rechazo (busy, rate_limited) en su propia respuesta y la página, mostrar su propio texto. Detrás de un proxy, toma clientIp de una cabecera de confianza (X-Forwarded-For de tu balanceador).

4. SPA: React, Next.js, Vue

  • Incluye el script una sola vez para toda la aplicación (index.html, el layout raíz), no en un componente de página.
  • Si el router vuelve a dibujar el body o el contenedor, el widget vuelve solo. data-container puede aparecer en la página hasta 10 segundos después del script.
  • RingostatWebCall.unmount() termina la llamada, quita los widgets y deja de vigilarlos. RingostatWebCall.mount(options?) vuelve a mostrar el widget; options son los mismos parámetros que los atributos data, en camelCase y sin data-: { container: "#talk", offsetX: "24" }. Mientras haya un widget a la vista, mount() devuelve el existente; para moverlo a otro contenedor, llama antes a unmount().
  • v1.js se carga de forma asíncrona, así que el efecto de una página o la primera ruta pueden ejecutarse antes. Por eso, en una SPA pon data-auto="false" y muestra el widget con la función webCallFor de abajo: espera al SDK y aplica lo que necesita la ruta actual, sin que el widget «parpadee» donde no debe estar. mount() devuelve una Promise con el elemento del widget o null (el motivo, en un aviso [Ringostat] de la consola).
// webCallRoute.js: un solo módulo para toda la aplicación.
// next: false, sin widget; undefined, el botón flotante; { container: "#talk" }, en un bloque.
let want, shown, timer, seq = 0;
export async function webCallFor(next) {
  want = next;
  const w = window.RingostatWebCall;
  if (!w || !w.mount) {                            // v1.js aún se está cargando: se aplica en cuanto esté
    timer = timer || setInterval(() => {
      if (window.RingostatWebCall && window.RingostatWebCall.mount) { clearInterval(timer); timer = 0; webCallFor(want); }
    }, 100);
    return;
  }
  const key = JSON.stringify(want === undefined ? null : want);
  if (key === shown) return;                       // el mismo modo: el widget y la llamada siguen
  const my = ++seq;                                 // cada llamada lleva su número: la respuesta de una llamada antigua se ignora
  shown = key;
  w.unmount();
  if (want === false) return;
  let host = null;
  try { host = await w.mount(want); } catch {}
  if (!host && my === seq) shown = undefined;       // no se mostró (p. ej. no hubo contenedor en 10 s): la siguiente llamada lo reintenta
}
// Next.js, app/layout.tsx: el script una vez; con data-auto="false" el widget lo muestra webCallFor
import Script from "next/script";
<Script src="https://ai.ringostat.com/webcall/v1.js" strategy="afterInteractive"
  data-key="<CLAVE_DEL_WIDGET>" data-privacy-url="/privacy" data-auto="false" />

// Next.js: un componente de cliente en el layout raíz decide según la ruta
"use client";
import { useEffect } from "react";
import { usePathname } from "next/navigation";
import { webCallFor } from "./webCallRoute";
export function WebCallRoute() {
  const path = usePathname();
  useEffect(() => {
    webCallFor(path.startsWith("/checkout") ? false : path === "/contacts" ? { container: "#talk" } : undefined);
  }, [path]);
  return null;
}

// Vue Router: funciona también para la primera ruta
router.afterEach((to) => webCallFor(to.meta.webCall));  // meta: { webCall: false } o { webCall: { container: "#talk" } }

Para el nivel B en una SPA, crea el objeto de la conversación en el manejador del clic, como en el ejemplo, y llama a call.stop() al salir de la página (en el cleanup del efecto o en onBeforeUnmount), para que la llamada no siga sin interfaz.

5. Instalación en el sitio

Tu propio sitioPega el código antes de </body> en todas las páginas que necesiten el botón (en la plantilla común).
TildaSite settings → More → HTML code for the body → pega el código → guarda y publica todas las páginas. Para «Block on the page», añade <div id="ringostat-call"></div> con un bloque «HTML code» (T123) donde corresponda.
WordPressUn plugin para código en header/footer (p. ej. WPCode) → Footer → pega el código y guarda. O el footer.php del tema hijo, antes de </body>.
Google Tag ManagerNueva etiqueta «Custom HTML» → pega el código tal cual → activador All Pages → Submit y Publish. Funciona aunque GTM ejecuta el script sin document.currentScript: el widget encuentra su línea solo. El botón aparece un poco más tarde que con el código en la plantilla.
WixSettings → Custom Code → + Add Custom Code → pega el código, All pages, Place Code in: Body - end. Hace falta un dominio conectado.
ShopifyOnline Store → Themes → … → Edit code → layout/theme.liquid → pega el código antes de </body> → Save.

Añade a «Allowed sites» cada dominio donde esté el código, incluidos www y las direcciones de prueba del constructor de sitios (p. ej. project123.tilda.ws): la coincidencia es exacta.

6. Requisitos y límites

  • HTTPS. El navegador solo da el micrófono a páginas seguras; para desarrollo sirve http://localhost.
  • Permiso del micrófono. El primer inicio muestra la petición del navegador. Un iframe necesita allow="microphone": <iframe src="…" allow="microphone">; el Origin de la petición es entonces el dominio de la página del iframe: añade ese a «Allowed sites».
  • Los navegadores integrados (Instagram, Telegram, Facebook) a menudo no dan micrófono: start() termina con mic_unsupported. El widget listo no aparece en páginas sin micrófono (sin HTTPS, sin navigator.mediaDevices, un iframe sin allow); en tu propia interfaz oculta el botón si !window.isSecureContext || !navigator.mediaDevices?.getUserMedia.
  • Content-Security-Policy: como en la guía básica (script-src https://ai.ringostat.com, connect-src https://apiagent.ringostat.com wss://apiagent.ringostat.com). Para el nivel C añade a connect-src la dirección de tu endpoint (normalmente 'self'). Con una CSP basada en nonce, pon el nonce en la etiqueta de v1.js: v1-aura.js recibe el mismo.
  • Sitios permitidos: el token solo se emite para páginas de los dominios de la lista de la campaña; la coincidencia es exacta.
  • Inicio solo en un clic: call.start() va en el manejador de un clic, no al cargar la página ni tras un temporizador o un await largo. Si no, el navegador no da ni micrófono ni audio.
  • Un botón flotante por clave y página; un duplicado se ignora con un aviso en la consola.
  • Los avisos obligatorios de IA y grabación con el enlace a la política de privacidad no se desactivan con ningún ajuste; en tu propia interfaz los muestras tú.
  • La duración de la llamada, las llamadas simultáneas y el límite de conversaciones por IP vienen de los ajustes de la campaña y del proyecto.
  • No copies v1.js a tu servidor: cargado desde ai.ringostat.com, se actualiza solo. Una copia debe servirse con Content-Type: application/javascript; charset=UTF-8 y con v1-aura.js al lado; si no, se rompen los textos o el estilo aura.

Qué sigue