Dynamic variables en el widget

Dynamic variables en el widget

Las dynamic variables permiten enviar datos del contexto actual de la página web al agente en el momento exacto en que el cliente inicia la llamada. El agente los recibe como variables en el prompt y puede usarlos para personalizar la conversación sin que el cliente tenga que repetirlos.

Casos de uso comunes

• Pasar la página o el servicio que el cliente estaba viendo ("el cliente está en la página de ortodoncia").
• Incluir el nombre del cliente si ya está logueado en tu sitio.
• Indicar el idioma preferido según la configuración del navegador.
• Pasar UTM params para atribución de marketing.

Cómo funciona

Al iniciar la sesión, el widget envía las dynamic variables a ElevenLabs como parte del payload de inicio. El agente las recibe inyectadas en el prompt del sistema.

Implementación en JavaScript

<elevenlabs-convai id="voice-widget" agent-id="TU_AGENT_ID"></elevenlabs-convai>

<script>
  const widget = document.getElementById("voice-widget");

  widget.addEventListener("elevenlabs-convai:call_started", () => {
    // Las variables se pasan antes de que el agente tome el turno
  });

  // Pasar dynamic variables al inicializar
  widget.setAttribute("dynamic-variables", JSON.stringify({
    pagina_actual: document.title,
    servicio_visto: "ortodoncia",
    nombre_cliente: "Juan Pérez",   // Si está disponible
    idioma: navigator.language.slice(0, 2)
  }));
</script>

Implementación en React / Next.js

"use client";
import { useEffect, useRef } from "react";

interface Props {
  agentId: string;
  clientName?: string;
  currentService?: string;
}

export default function VoiceWidget({ agentId, clientName, currentService }: Props) {
  const widgetRef = useRef<HTMLElement>(null);

  useEffect(() => {
    if (widgetRef.current) {
      widgetRef.current.setAttribute(
        "dynamic-variables",
        JSON.stringify({
          nombre_cliente: clientName ?? "visitante",
          servicio_visto: currentService ?? "general",
          pagina: window.location.pathname,
        })
      );
    }
  }, [clientName, currentService]);

  return (
    <>
      {/* @ts-expect-error custom element */}
      <elevenlabs-convai
        ref={widgetRef}
        agent-id={agentId}
      />
    </>
  );
}

Referenciar variables en el prompt

En el prompt del sistema, referencia las variables con la sintaxis {{nombre_variable}}:

Eres María, asistente de Clínica Dental Ramírez.

El cliente que está iniciando la llamada se llama {{nombre_cliente}}.
En este momento está viendo información sobre {{servicio_visto}}.

Personaliza el saludo usando su nombre si está disponible.

Variables reservadas por el sistema

El sistema ya inyecta automáticamente las siguientes variables — no es necesario pasarlas manualmente:

| Variable | Contenido |

|---|---|

| tenant_name | Nombre del negocio |

| tenant_timezone | Zona horaria del tenant |

| current_datetime | Fecha y hora actual en la zona del tenant |

| available_services | Lista de servicios del tenant |

Límites

• Máximo 20 variables por sesión.
• El valor de cada variable no debe superar 500 caracteres.
• Los valores deben ser strings planos — no JSON anidado.