Saltar a la navegación
DesplegarWeb

Personalización del widget

Descubre cómo personalizar el aspecto del widget para que encaje con tu marca y adaptar el comportamiento del agente desde HTML.

Los widgets permiten integrar ElevenAgents al instante en cualquier sitio web. Puedes personalizar el widget desde la interfaz o mediante nuestros SDK de ElevenAgents con tipado seguro para tener control total sobre el estilo y el comportamiento. Las modificaciones mediante el 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 y el enlace compartible de un agente desde Claude u otro cliente MCP a través del servidor MCP alojado.

Configuración de modalidad

El widget admite modos de entrada flexibles que se adaptan 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 solo mediante la voz.
  • Voz + texto: usuarios pueden alternar entre la entrada por voz y texto durante las conversaciones.
  • Modo chat: las conversaciones comienzan en modo 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 chat (solo texto) mediante nuestros SDK, consulta nuestra guía del modo chat.

De forma predeterminada, el widget usa el modo de solo voz. Activa el selector de entrada de texto para permitir interacciones multimodales, o activa la compatibilidad con 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 para insertar el 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 (situada 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 diversos atributos HTML para una mayor personalización:

<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. Los enlaces se muestran como texto sin formato de manera predeterminada 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

Se pueden usar dos atributos HTML más para personalizar el comportamiento del agente en tiempo de ejecución. Estas dos funciones se pueden usar juntas, por separado o no usar en absoluto.

Variables dinámicas

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

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

Todas las variables dinámicas que necesite el agente deben pasarse en el widget.

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

Modificaciones

Las modificaciones 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>

Las modificaciones se pueden activar para campos específicos y son totalmente opcionales.

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

Personalización visual

Personaliza el aspecto 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 el aspecto, avatar, texto, condiciones, compatibilidad de 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.

Aspecto del widget

Contenido enriquecido

El contenido enriquecido permite que el agente responda con componentes interactivos junto a sus mensajes. Configúralo en el panel, en Canales → Widget → Contenido enriquecido.

Configuración de contenido enriquecido del widget

El contenido enriquecido se muestra en conversaciones de texto y en conversaciones de voz cuando está activada la opción Transcripción en tiempo real de la conversación en Interfaz. Solo está disponible en el widget insertado.

Las respuestas rápidas son botones que usuarios pueden pulsar en lugar de escribir. Cuando un usuario pulsa uno, su etiqueta se envía como su siguiente mensaje.

Respuestas rápidas

Sugeridas por el agente

El agente sugiere hasta tres respuestas durante la conversación, por ejemplo, para confirmar una elección u ofrecer los siguientes pasos.

Respuestas del primer mensaje

Añade hasta tres respuestas en Respuestas del primer mensaje para mostrarlas junto al primer mensaje del agente, de modo que usuarios puedan iniciar la conversación con un toque. Arrástralas para cambiar el orden.

Estas respuestas son fijas: aparecen con cada primer mensaje y el agente no las elige. Se traducen junto con tus otros ajustes preestablecidos de idioma.

Cómo usa el agente el contenido enriquecido

Excepto las respuestas del primer mensaje, el agente decide en cada turno si mostrar respuestas rápidas o un carrusel. Una respuesta que no necesite un componente se mantiene como texto sin formato. Para determinar cuándo y cómo aparecen, descríbelo en el prompt de sistema del agente.

Las respuestas rápidas y el carrusel están activados de forma predeterminada para los agentes nuevos. Para agentes creados antes de que el contenido enriquecido estuviera disponible, actívalos en la configuración del widget.

Implementación avanzada

Para una personalización más avanzada, debes usar 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 situado 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 se muestra 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.