Passer à la navigation
DéployerWeb

Personnalisation du widget

Découvrez comment personnaliser l’apparence du widget pour l’adapter à votre marque et le comportement de l’agent depuis le HTML.

Les widgets permettent d’intégrer instantanément ElevenAgents à tout site web. Personnalisez votre widget depuis l’interface utilisateur ou via nos SDK ElevenAgents, typés de manière sûre, afin de contrôler entièrement son style et son 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.

Vous pouvez également récupérer la configuration du widget d’un agent et son lien partageable depuis Claude ou un autre client MCP, via le serveur MCP hébergé.

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.

La multimodalité est entièrement prise en charge dans nos SDK client. Retrouvez plus d’informations ici.

Options d’interface du widget

Modes disponibles :

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

Pour en savoir plus sur l’utilisation du mode chat (texte uniquement) via nos SDK, consultez notre guide du mode chat.

Par défaut, le widget est en mode voix uniquement. Activez le bouton de saisie de texte pour autoriser les interactions multimodales, ou la prise en charge du mode texte uniquement pour des conversations entièrement textuelles initiées par texte.

Intégrer le widget

Les widgets nécessitent actuellement des agents publics dont l’authentification est désactivée. Assurez-vous que cette option est désactivée dans l’onglet Avancé des paramètres de votre agent.

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 :

Code d’intégration du 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>

Pour renforcer la sécurité, définissez les domaines autorisés dans la liste d’autorisation de votre agent (située dans l’onglet Sécurité). Cela limite l’accès aux seuls hôtes spécifiés.

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>

Le widget affiche le Markdown dans les réponses de l’agent. Par défaut, les liens s’affichent en texte brut afin d’éviter le 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>

Configuration à l’exécution

Deux attributs HTML supplémentaires permettent de personnaliser le comportement de l’agent à l’exécution. Ces deux fonctionnalités peuvent être utilisées ensemble, séparément ou pas du tout.

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.

Retrouvez plus d’informations dans notre guide des variables dynamiques.

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.

Retrouvez plus d’informations dans notre guide des remplacements.

Personnalisation visuelle

Personnalisez l’apparence du widget, son contenu textuel, le choix de la langue et bien plus encore.

Ouvrez votre agent dans le Dashboard, puis accédez à l’onglet Widget pour personnaliser l’apparence, l’avatar, le texte, les conditions, la prise en charge des langues et bien plus encore.

Personnalisation du widget

Personnalisez les couleurs et les formes du widget pour les adapter à votre identité de marque.

Apparence du widget

Contenu enrichi

Le contenu enrichi permet à l’agent de répondre avec des composants interactifs en complément de ses messages. Configurez-le dans le Dashboard, sous Canaux → Widget → Contenu enrichi.

Paramètres de contenu enrichi du widget

Le contenu enrichi s’affiche dans les conversations textuelles et dans les conversations vocales lorsque l’option Transcription en temps réel de la conversation est activée sous Interface. Il est uniquement disponible dans le widget intégré.

Les réponses rapides sont des boutons que les utilisateurs peuvent sélectionner au lieu de saisir du texte. Lorsqu’un utilisateur en sélectionne une, son libellé est envoyé comme prochain message de l’utilisateur.

Réponses rapides

Suggérées par l’agent

L’agent suggère jusqu’à trois réponses pendant la conversation, par exemple pour confirmer un choix ou proposer les prochaines étapes.

Réponses du premier message

Ajoutez jusqu’à trois réponses sous Réponses du premier message pour les afficher avec le premier message de l’agent, afin que les utilisateurs puissent démarrer la conversation en un clic. Faites-les glisser pour modifier leur ordre.

Ces réponses sont fixes : elles s’affichent avec chaque premier message, et l’agent ne les choisit pas. Elles sont traduites avec vos autres préréglages de langue.

Comment l’agent utilise le contenu enrichi

À l’exception des réponses du premier message, l’agent décide à chaque tour d’afficher ou non des réponses rapides ou un carrousel. Une réponse qui ne nécessite pas de composant reste en texte brut. Pour déterminer quand et comment ils s’affichent, décrivez-le dans le prompt système de l’agent.

Les réponses rapides et le carrousel sont activés par défaut pour les nouveaux agents. Pour les agents créés avant la disponibilité du contenu enrichi, activez-les dans les paramètres du widget.

Implémentation avancée

Pour une personnalisation plus avancée, utilisez les SDK ElevenAgents, typés de manière sûre, avec une application Next.js, React ou Python.

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 d’assistance
  • Rediriger l’utilisateur vers une URL externe

Pour voir des exemples de ces outils en action, démarrez un appel avec l’agent dans le coin inférieur droit 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.

Configuration de l’outil client

Exemple d’implémentation

Voici un exemple montrant comment gérer l’outil redirectToExternalURL déclenché par le widget dans votre code 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");
        },
      };
    });
  }
});

Découvrez nos SDK, typés de manière sûre, pour des implémentations React, Next.js et Python.