Personnalisation du widget

Les widgets permettent d’intégrer instantanément ElevenAgents à n’importe quel site web. Vous pouvez personnaliser votre widget depuis l’interface utilisateur ou via nos SDK ElevenAgents typés pour contrôler entièrement le style et le comportement. Les remplacements définis dans le SDK sont prioritaires sur la personnalisation depuis l’interface utilisateur. Notre widget est multimodal et peut traiter du texte comme de l’audio.

Configuration des modalités

Le widget prend en charge des modes de saisie flexibles adaptés à votre cas d’usage. Configurez ces options dans le Dashboard, sous Canaux → Widget → Interface.

Modes disponibles :

• Voix uniquement (par défaut) : les utilisateurs interagissent uniquement par la parole.
• Voix + texte : les utilisateurs peuvent alterner entre saisie vocale et saisie de texte pendant les conversations.
• Mode chat : les conversations démarrent en mode chat, uniquement textuel, sans fonctionnalités vocales lorsqu’elles sont initiées par un message texte.

Pour plus d’informations sur l’utilisation du mode chat, uniquement textuel, via nos SDK, consultez notre guide du mode chat.

Intégrer le widget

Ajoutez cet extrait de code à la section <body> de votre site web. Placez-le dans votre fichier principal index.html pour le rendre disponible sur l’ensemble du site :

<elevenlabs-convai agent-id="<replace-with-agent_7101k5zvyjhmfg983brhmhkd98n6>"></elevenlabs-convai>
<script
  src="https://unpkg.com/@elevenlabs/convai-widget-embed"
  async
  type="text/javascript"
></script>

Attributs du widget

Ce code d’intégration de base affiche le widget avec la configuration par défaut définie dans le Dashboard de l’agent. Le widget prend en charge différents attributs HTML pour aller plus loin dans la personnalisation :

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

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

Configuration à l’exécution

Deux attributs HTML supplémentaires permettent de personnaliser le comportement de l’agent à l’exécution. Vous pouvez utiliser ces deux fonctionnalités ensemble, séparément ou ne pas les utiliser.

Variables dynamiques

Les variables dynamiques vous permettent d’injecter des valeurs à l’exécution dans les messages, les prompts système et les outils de votre agent.

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

Toutes les variables dynamiques requises par l’agent doivent être transmises au widget.

Remplacements

Les remplacements permettent de personnaliser entièrement le comportement de votre agent à l’exécution :

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

Les remplacements peuvent être activés pour des champs spécifiques et sont entièrement facultatifs.

Personnalisation visuelle

Personnalisez l’apparence du widget, son contenu textuel, la sélection de langue et bien plus encore.

Implémentation avancée

Outils client

Les outils client vous permettent d’étendre les fonctionnalités du widget en ajoutant des écouteurs d’événements. Le widget peut ainsi effectuer des actions telles que :

• Rediriger l’utilisateur vers une page spécifique
• Envoyer un email à votre équipe de support
• Rediriger l’utilisateur vers une URL externe

Pour voir des exemples de ces outils en action, démarrez un appel avec l’agent en bas à droite de cette page. Le code source est disponible sur GitHub à titre de référence.

Créer un outil client

Pour créer votre premier outil client, suivez le guide des outils client.

Exemple d’implémentation

Voici un exemple montrant comment gérer l’outil redirectToExternalURL déclenché par le widget dans votre code JavaScript :

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");
        },
      };
    });
  }
});