DesplegarWeb

Personalización del widget

Descubre cómo personalizar la apariencia del widget para que se adapte a tu marca y el comportamiento del agente desde HTML.

Los widgets permiten integrar al instante ElevenAgents en cualquier sitio web. Puedes personalizar tu widget desde la interfaz o mediante nuestros SDK de ElevenAgents con tipado seguro para tener un control total sobre el estilo y el comportamiento. Las anulaciones del SDK tienen prioridad sobre la personalización desde la interfaz. Nuestro widget es multimodal y puede procesar tanto texto como audio.

También puedes obtener la configuración del widget de un agente y su enlace compartible desde Claude u otro cliente MCP a través del servidor MCP alojado.

Configuración de modalidad

El widget admite modos de entrada flexibles para adaptarse a tu caso de uso. Configura estas opciones en el panel, en Canales → Widget → Interfaz.

La multimodalidad es totalmente compatible con nuestros SDK de cliente. Consulta más información aquí.

Opciones de interfaz del widget

Modos disponibles:

  • Solo voz (predeterminado): usuarios interactúan únicamente mediante voz.
  • Voz + texto: usuarios pueden alternar entre la entrada de voz y texto durante las conversaciones.
  • Modo de chat: las conversaciones comienzan en modo de chat (solo texto), sin capacidades de voz, cuando se inician con un mensaje de texto.

Para obtener más información sobre cómo usar el modo de chat (solo texto) con nuestros SDK, consulta nuestra guía del modo de chat.

El widget usa el modo de solo voz de forma predeterminada. Activa el interruptor de entrada de texto para permitir interacciones multimodales, o habilita el modo de solo texto para conversaciones exclusivamente basadas en texto cuando se inicien mediante texto.

Insertar el widget

Actualmente, los widgets requieren agentes públicos con la autenticación desactivada. Asegúrate de desactivarla en la pestaña Avanzado de la configuración de tu agente.

Añade este fragmento de código a la sección <body> de tu sitio web. Colócalo en tu archivo principal index.html para que esté disponible en todo el sitio:

Código de inserción del widget
<elevenlabs-convai agent-id="<replace-with-agent_7101k5zvyjhmfg983brhmhkd98n6>"></elevenlabs-convai>
<script
  src="https://unpkg.com/@elevenlabs/convai-widget-embed"
  async
  type="text/javascript"
></script>

Para mejorar la seguridad, define los dominios permitidos en la Lista de permitidos de tu agente (en la pestaña Seguridad). Esto restringe el acceso únicamente a los hosts especificados.

Atributos del widget

Este código de inserción básico mostrará el widget con la configuración predeterminada definida en el panel del agente. El widget admite varios atributos HTML para personalizarlo aún más:

<elevenlabs-convai
  agent-id="agent_id"              // Required: Your agent ID
  signed-url="signed_url"          // Alternative to agent-id
  server-location="us"             // Optional: "us" or default
  variant="expanded"               // Optional: Widget display mode
  dismissible="true"               // Optional: Allow the user to minimize the widget
></elevenlabs-convai>
<elevenlabs-convai
  avatar-image-url="https://..." // Optional: Custom avatar image
  avatar-orb-color-1="#6DB035" // Optional: Orb gradient color 1
  avatar-orb-color-2="#F5CABB" // Optional: Orb gradient color 2
></elevenlabs-convai>
<elevenlabs-convai
  action-text="Need assistance?" // Optional: CTA button text
  start-call-text="Begin conversation" // Optional: Start call button
  end-call-text="End call" // Optional: End call button
  expand-text="Open chat" // Optional: Expand widget text
  listening-text="Listening..." // Optional: Listening state
  speaking-text="Assistant speaking" // Optional: Speaking state
></elevenlabs-convai>

El widget renderiza Markdown en las respuestas del agente. De forma predeterminada, los enlaces se muestran como texto sin formato para evitar el phishing.

<elevenlabs-convai
  markdown-link-allowed-hosts="example.com"  // Domains where links are clickable (use "*" for all)
  markdown-link-include-www="true"           // Also allow www variants (default: true)
  markdown-link-allow-http="true"            // Allow http:// links (default: true)
  syntax-highlight-theme="dark"              // Code block theme: "dark", "light", or "auto"
></elevenlabs-convai>

Configuración en tiempo de ejecución

Puedes usar otros dos atributos HTML para personalizar el comportamiento del agente en tiempo de ejecución. Estas dos funciones pueden utilizarse juntas, por separado o no utilizarse.

Variables dinámicas

Las variables dinámicas te permiten insertar valores de tiempo de ejecución en los mensajes, prompts del sistema y herramientas de tu agente.

<elevenlabs-convai
  agent-id="agent_7101k5zvyjhmfg983brhmhkd98n6"
  dynamic-variables='{"user_name": "John", "account_type": "premium"}'
></elevenlabs-convai>

Debes pasar al widget todas las variables dinámicas que requiera el agente.

Consulta más información en nuestra guía de variables dinámicas.

Anulaciones

Las anulaciones permiten personalizar por completo el comportamiento de tu agente en tiempo de ejecución:

<elevenlabs-convai
  agent-id="agent_7101k5zvyjhmfg983brhmhkd98n6"
  override-language="es"
  override-prompt="Custom system prompt for this user"
  override-first-message="Hi! How can I help you today?"
  override-voice-id="axXgspJ2msm3clMCkdW3"
></elevenlabs-convai>

Puedes habilitar anulaciones para campos específicos y son totalmente opcionales.

Consulta más información en nuestra guía de anulaciones.

Personalización visual

Personaliza la apariencia del widget, el contenido de texto, la selección de idioma y mucho más.

Abre tu agente en el panel y ve a la pestaña Widget para personalizar la apariencia, el avatar, el texto, los términos, la compatibilidad con idiomas y mucho más.

Personalización del widget

Personaliza los colores y las formas del widget para que encajen con la identidad de tu marca.

Apariencia del widget

Implementación avanzada

Para una personalización más avanzada, deberías utilizar los SDK de ElevenAgents con tipado seguro en una aplicación de Next.js, React o Python.

Herramientas de cliente

Las herramientas de cliente te permiten ampliar la funcionalidad del widget añadiendo detectores de eventos. Esto permite que el widget realice acciones como:

  • Redirigir al usuario a una página específica
  • Enviar un correo electrónico a tu equipo de soporte
  • Redirigir al usuario a una URL externa

Para ver ejemplos de estas herramientas en acción, inicia una llamada con el agente en la esquina inferior derecha de esta página. El código fuente está disponible en GitHub como referencia.

Crear una herramienta de cliente

Para crear tu primera herramienta de cliente, sigue la guía de herramientas de cliente.

Configuración de la herramienta de cliente

Ejemplo de implementación

A continuación tienes un ejemplo de cómo gestionar la herramienta redirectToExternalURL activada por el widget en tu código JavaScript:

index.js
document.addEventListener("DOMContentLoaded", () => {
  const widget = document.querySelector("elevenlabs-convai");
  if (widget) {
    // Listen for the widget's "call" event to trigger client-side tools
    widget.addEventListener("elevenlabs-convai:call", (event) => {
      event.detail.config.clientTools = {
        // Note: To use this example, the client tool called "redirectToExternalURL" (case-sensitive) must have been created with the configuration defined above.
        redirectToExternalURL: ({ url }) => {
          window.open(url, "_blank", "noopener,noreferrer");
        },
      };
    });
  }
});

Explora nuestros SDK con tipado seguro para implementaciones con React, Next.js y Python.