> This is a page from the ElevenLabs documentation. For a complete page index, fetch https://elevenlabs.io/docs/llms.txt. For the full documentation in a single file, fetch https://elevenlabs.io/docs/llms-full.txt.
# Personnalisation du widget
Les **widgets** permettent d’intégrer instantanément ElevenAgents à tout site web. Personnalisez votre widget depuis l’interface utilisateur ou via nos [SDK ElevenAgents](/docs/fr/eleven-api/resources/libraries), 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.
> **Note**
>
> 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é](/docs/fr/eleven-agents/operate/hosted-mcp).
## 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**.
> **Note**
>
> La multimodalité est entièrement prise en charge dans nos SDK client. Retrouvez plus d’informations
> [ici](/docs/fr/eleven-api/resources/libraries).
**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](/docs/fr/eleven-agents/guides/chat-mode).
> **Note**
>
> 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
> **Note**
>
> 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 `` 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`**
```html title="Code d’intégration du widget"
```
> **Info**
>
> 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 :
#### Configuration principale
```html
```
#### Personnalisation visuelle
```html
```
#### Personnalisation du texte
```html
```
#### Rendu Markdown
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.
```html
```
## 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.
```html
```
Toutes les variables dynamiques requises par l’agent doivent être transmises au widget.
> **Info**
>
> Retrouvez plus d’informations dans notre [guide des variables dynamiques](/docs/fr/eleven-agents/customization/personalization/dynamic-variables).
### Remplacements
Les remplacements permettent de personnaliser entièrement le comportement de votre agent à l’exécution :
```html
```
Les remplacements peuvent être activés pour des champs spécifiques et sont entièrement facultatifs.
> **Info**
>
> Retrouvez plus d’informations dans notre [guide des remplacements](/docs/fr/eleven-agents/customization/personalization/overrides).
## Personnalisation visuelle
Personnalisez l’apparence du widget, son contenu textuel, le choix de la langue et bien plus encore.
#### Mettre à jour depuis le Dashboard
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.
#### Mettre à jour via la CLI
#### Récupérer la configuration de l’agent
```bash
elevenlabs agents pull --agent ""
```
#### Modifier \`agent_configs/\.json\`
Définissez les champs sous `platform_settings.widget`. Par exemple, pour modifier les couleurs de l’orbe et le mode de feedback :
```json
{
"platform_settings": {
"widget": {
"variant": "full",
"placement": "bottom-right",
"avatar": {
"type": "orb",
"color_1": "#6DB035",
"color_2": "#F5CABB"
},
"feedback_mode": "during",
"bg_color": "#ffffff",
"text_color": "#000000",
"btn_color": "#000000",
"btn_text_color": "#ffffff"
}
}
}
```
#### Envoyer vos modifications
```bash
elevenlabs agents push --agent ""
```
#### Mettre à jour via l’API
```python
from elevenlabs import ElevenLabs
elevenlabs = ElevenLabs()
elevenlabs.conversational_ai.agents.update(
agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6",
platform_settings={
"widget": {
"variant": "full",
"placement": "bottom-right",
"avatar": {
"type": "orb",
"color_1": "#6DB035",
"color_2": "#F5CABB",
},
"feedback_mode": "during",
},
},
)
```
```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";
const elevenlabs = new ElevenLabsClient();
await elevenlabs.conversationalAi.agents.update("agent_7101k5zvyjhmfg983brhmhkd98n6", {
platformSettings: {
widget: {
variant: "full",
placement: "bottom-right",
avatar: {
type: "orb",
color1: "#6DB035",
color2: "#F5CABB",
},
feedbackMode: "during",
},
},
});
```
#### Apparence
Personnalisez les couleurs et les formes du widget pour les adapter à votre identité de marque.
#### Feedback
Recueillez les retours des utilisateurs pour améliorer les performances de l’agent. Ils peuvent servir à affiner la base de connaissances et le prompt système de votre agent.
**Modes de collecte**
* **Aucun** : désactive entièrement la collecte de feedback.
* **Pendant la conversation** : prend en charge le feedback en temps réel pendant les conversations. Des métadonnées supplémentaires, telles que la réponse de l’agent ayant déclenché le feedback, sont collectées pour mieux identifier les lacunes.
* **Après la conversation** : affiche une seule demande de feedback après la conversation.
> **Note**
>
> Envoyez du feedback par programmation via l’[API](/docs/fr/eleven-agents/api-reference/conversations/create) lorsque vous utilisez des implémentations SDK personnalisées.
#### Avatar
Configurez l’orbe vocal ou fournissez votre propre avatar.
**Options disponibles**
* **Orbe** : choisissez deux couleurs de dégradé (par exemple, #6DB035 et #F5CABB).
* **Lien/image** : utilisez une image d’avatar personnalisée.
#### Texte affiché
Personnalisez tous les éléments textuels affichés dans le widget, par exemple pour modifier les libellés des boutons.
#### Conditions
Affichez des conditions générales personnalisées avant la conversation.
**Options disponibles**
* **Contenu des conditions** : utilisez Markdown pour mettre en forme le texte de votre politique.
* **Clé de stockage local** : une clé (par exemple, "terms_accepted") pour éviter de solliciter les utilisateurs qui reviennent.
**Utilisation**
Les conditions sont affichées aux utilisateurs dans une fenêtre modale avant le début de l’appel :
Les conditions peuvent être rédigées en Markdown, ce qui vous permet de :
* Ajouter des liens vers des politiques externes
* Mettre en forme le texte avec des titres et des listes
* Inclure des éléments d’emphase et de style
Pour obtenir de l’aide sur Markdown, consultez le [guide d’aide CommonMark](https://commonmark.org/help/).
> **Info**
>
> Une fois les conditions acceptées, le statut est stocké localement et l’utilisateur ne sera plus sollicité lors des
> visites suivantes.
#### Langue
Activez la prise en charge de plusieurs langues dans le widget.
> **Note**
>
> Pour activer la sélection de la langue, vous devez d’abord [ajouter des langues supplémentaires](/docs/fr/eleven-agents/customization/voice/customization/language) à votre agent.
#### Désactivation du son
Autorisez les utilisateurs à couper leur audio dans le widget.
Pour ajouter le bouton de désactivation du son, activez cette option dans la carte `interface` des paramètres `widget` de l’agent.
#### Page partageable
Personnalisez la page de destination publique de votre widget (lien partageable).
**Options disponibles**
* **Description** : rédigez un court paragraphe expliquant l’objectif de l’appel.
## 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**.
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é.
#### Réponses rapides
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.
**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](/docs/fr/eleven-agents/customization/voice/customization/language).
#### Carrousel
L’agent affiche jusqu’à cinq éléments sous forme de cartes défilables, par exemple des résultats de recherche ou des recommandations de produits.
**Contenu des cartes**
Chaque carte comporte un titre et peut inclure un sous-titre, une image, une description et jusqu’à trois boutons. Lorsqu’un utilisateur sélectionne le bouton d’une carte, son libellé est envoyé avec le titre de l’élément comme prochain message de l’utilisateur.
**Déclencher le carrousel**
Le carrousel fonctionne uniquement lorsque l’agent a de véritables éléments à afficher. Il génère des cartes à partir des résultats renvoyés par un [outil](/docs/fr/eleven-agents/customization/tools) ou fournis par la [base de connaissances](/docs/fr/eleven-agents/customization/knowledge-base), et n’invente ni éléments, ni prix, ni images. Un agent sans outil ni base de connaissances renvoyant des éléments affichera rarement un carrousel.
Dans votre prompt, indiquez à l’agent :
* **Quand afficher un carrousel**, par exemple lorsque l’utilisateur demande à parcourir ou comparer des produits.
* **Ce que contient chaque champ**, par exemple le nom du produit comme titre et le prix comme sous-titre.
* **Quels boutons ajouter et quelle action effectuer lorsqu’un bouton est sélectionné.** Demandez uniquement des boutons sur lesquels l’agent peut agir. Un bouton **Ajouter au panier** nécessite un outil qui ajoute l’article au panier, sinon sa sélection ne mène nulle part.
Ajoutez des instructions comme celles-ci au prompt système et remplacez les noms d’outils entre crochets par vos propres outils :
**`Exemple de prompt`**
```markdown title="Exemple de prompt"
# Product carousel
When the user asks to browse, search or compare products, call [your product search tool] and show the results as a carousel.
- Title: the product name
- Subtitle: the price
- Description: a one-sentence summary
- Image: the product image URL from the search results
Give each card "View product" and "Add to cart" buttons. When the user picks "Add to cart" on a card, call [your add to cart tool] with that product.
```
**Dépannage**
* **Aucun carrousel ne s’affiche** : vérifiez qu’un outil ou la base de connaissances a renvoyé des éléments que l’agent peut afficher et que votre prompt indique quand utiliser un carrousel.
* **Une carte ne contient aucune image** : les images des cartes s’affichent uniquement si l’URL de l’image est apparue plus tôt dans la conversation, par exemple dans le résultat d’un outil, et si elle est servie via HTTPS. Assurez-vous que votre outil renvoie des URL d’images.
### 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](/docs/fr/eleven-agents/best-practices/prompting-guide) 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
> **Note**
>
> Pour une personnalisation plus avancée, utilisez les [SDK ElevenAgents](/docs/fr/eleven-api/resources/libraries), 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](https://github.com/elevenlabs/elevenlabs-dx/blob/main/fern/assets/scripts/widget.js) à titre de référence.
#### Créer un outil client
Pour créer votre premier outil client, suivez le [guide des outils client](/docs/fr/eleven-agents/customization/tools/client-tools).
#### Exemple : créer l’outil \`redirectToExternalURL\`
#### 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`**
```javascript title="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");
},
};
});
}
});
```
> **Info**
>
> Découvrez nos [SDK](/docs/fr/eleven-api/resources/libraries), typés de manière sûre, pour des implémentations React, Next.js et Python.