Widgets de site web
Intégrez votre agent vocal sur n'importe quel site web pour que les visiteurs puissent démarrer une conversation vocale directement depuis le navigateur. L'onglet Widgets fournit des codes d'intégration, des options de personnalisation et des paramètres de sécurité par domaine.
Le widget de rappel fonctionne très différemment des widgets de cette page — au lieu de démarrer un appel vocal dans le navigateur, il collecte le numéro de téléphone du visiteur et fait rappeler celui-ci par votre agent. Consultez la page dédiée Widget de rappel.
Types de widgets
Hanc.AI propose quatre types de widgets in-browser, plus un widget de rappel distinct pour les rappels téléphoniques :
| Widget | Nom de la balise | Description | Idéal pour |
|---|---|---|---|
| Widget flottant | hanc-ai-floating-call | Bouton orbe qui flotte au-dessus de votre page | Appel à l'action toujours visible |
| Widget pilule | hanc-ai-pill-call | Bouton compact en forme de pilule placé en ligne dans votre contenu | Encombrement minimal à l'intérieur d'une mise en page existante |
| Widget pilule flottant | hanc-ai-pill-floating-call | Même forme de pilule compacte que Pilule, mais flotte avec la page comme le widget flottant | Lorsque vous voulez une esthétique de pilule qui suit le visiteur lorsqu'il fait défiler la page |
| Widget en ligne | hanc-ai-inline-call | Bouton d'appel pleine taille intégré dans le contenu de la page | Sections dédiées « Parlez-nous » |
| Widget de rappel | hanc-ai-callback | Formulaire de numéro de téléphone ; l'agent rappelle le visiteur | Pages de génération de leads, landing pages à forte intention — voir Widget de rappel |
Attributs communs
Tous les types de widgets prennent en charge ces attributs de base :
| Attribut | Requis | Description | Par défaut |
|---|---|---|---|
agent-id | Oui | Identifiant unique de votre agent | — |
voice-service-url | Non | Remplacer l'URL du service vocal | Détecté automatiquement |
api-base-url | Non | Remplacer l'URL de base de l'API | Détecté automatiquement |
Attributs d'affichage
| Attribut | Description | Valeurs | Par défaut |
|---|---|---|---|
position | Position du widget sur la page | bottom-right, bottom-left, top-right, top-left, static | bottom-right |
size | Taille du widget en pixels | Nombre | 120 |
theme | Nom du thème de couleur | Voir Thèmes de couleur | default |
Attributs de texte des boutons
| Attribut | Description | Par défaut |
|---|---|---|
button-start-text | Texte affiché sur le bouton au repos | "Call" |
button-connecting-text | Texte affiché pendant la connexion | "Connecting..." |
button-end-text | Texte affiché pendant un appel actif | — |
Attributs des conditions
| Attribut | Description | Par défaut |
|---|---|---|
terms-enabled | Activer la boîte de dialogue de consentement avant l'appel | false |
terms-content | Texte de consentement au format Markdown | "" |
terms-url | Lien vers votre page Conditions générales | "https://hanc.ai/terms" |
privacy-url | Lien vers votre page Politique de confidentialité | "https://hanc.ai/privacy" |
Les attributs de conditions définis sur l'élément HTML sont remplacés par les paramètres de widget de l'agent récupérés depuis l'API, sauf si skip-fetch est réglé sur true.
Attributs sonores
| Attribut | Description | Par défaut |
|---|---|---|
sound-enabled | Activer les sons de début/fin d'appel | true |
sound-volume | Volume des effets sonores | 0.25 |
sound-preset | Identifiant du preset sonore | "1" |
Thèmes de couleur
Personnalisez l'apparence du widget avec 11 thèmes de couleur intégrés :
| Thème | Valeur |
|---|---|
| Default | default |
| Purple | purple |
| Blue | blue |
| Cyan | cyan |
| Emerald | emerald |
| Amber | amber |
| Tangerine | tangerine |
| Rose | rose |
| Ember | ember |
| Black | black |
| White | white |
Chaque thème possède des variantes sombre et claire. Définissez le thème via l'attribut theme dans le code d'intégration, ou configurez-le dans les paramètres de widget de l'agent.
Exemples d'intégration
Widget flottant
<hanc-ai-floating-call agent-id="YOUR_AGENT_ID"></hanc-ai-floating-call>
<script src="https://unpkg.com/hanc-webrtc-widgets" async type="text/javascript"></script>
Widget flottant avec thème et position
<hanc-ai-floating-call
agent-id="YOUR_AGENT_ID"
theme="emerald"
position="bottom-left"
size="140"
></hanc-ai-floating-call>
<script src="https://unpkg.com/hanc-webrtc-widgets" async type="text/javascript"></script>
Widget pilule
<hanc-ai-pill-call agent-id="YOUR_AGENT_ID"></hanc-ai-pill-call>
<script src="https://unpkg.com/hanc-webrtc-widgets" async type="text/javascript"></script>
Widget en ligne
<hanc-ai-inline-call agent-id="YOUR_AGENT_ID"></hanc-ai-inline-call>
<script src="https://unpkg.com/hanc-webrtc-widgets" async type="text/javascript"></script>
L'URL du script ci-dessus charge toujours la dernière version publiée du widget — votre site bénéficie automatiquement des améliorations, et @latest est la valeur par défaut lorsqu'aucune version n'est spécifiée. Si vous devez verrouiller une version fixe, épinglez-la explicitement en ajoutant la version souhaitée, par ex. https://unpkg.com/hanc-webrtc-widgets@X.Y.Z.
Événements du widget
Les widgets émettent des événements que vous pouvez écouter en JavaScript :
| Événement | Description |
|---|---|
status-changed | Déclenché lorsque le statut de l'appel change |
connecting | L'appel est en cours d'établissement |
connected | L'appel est actif |
idle | Aucun appel actif |
error | Une erreur s'est produite |
audio-track | Piste audio distante reçue (pour la visualisation) |
local-audio-track | Piste audio du microphone local (pour la visualisation) |
microphone-enabled | Le microphone a été activé |
microphone-disabled | Le microphone a été désactivé |
call-start | Déclenché lorsqu'un appel démarre avec succès |
call-end | Déclenché lorsque l'appel se termine |
Exemple : écouter les événements
const widget = document.querySelector('hanc-ai-floating-call');
widget.addEventListener('call-start', () => {
console.log('Call started');
});
widget.addEventListener('call-end', () => {
console.log('Call ended');
});
Laisser l'agent ouvrir des pages
Pendant un appel depuis le navigateur, l'agent peut demander à votre site d'ouvrir une page — « laissez-moi vous montrer les tarifs » — et le visiteur le voit sans interrompre la conversation.
C'est votre page qui décide. L'agent envoie une requête, votre code choisit ce qu'elle signifie. Ouvrir une URL, changer d'onglet, défiler jusqu'à une section et déplier un accordéon sont autant de réponses valables.
Il faut trois étapes, et aucune ne suffit seule.
Étape 1 — Indiquez à l'agent quelles pages existent
L'agent ne voit pas le plan de votre site. Il ne demande que des chemins que vous lui avez donnés : listez-les dans le prompt de l'agent ou dans la base de connaissances.
Pages de notre site :
/pricing — offres et tarifs
/contact — formulaire de contact et téléphone
/product/crm — le CRM
Sans cette étape, l'agent n'a rien à demander et n'essaie même pas.
Étape 2 — Traitez la requête sur votre page
Ajoutez ceci une fois, n'importe où après le script du widget. L'événement remonte la page, document est donc un bon endroit :
<script>
document.addEventListener('agent-command', (event) => {
const { type, payload } = event.detail;
if (type === 'navigate') {
// SPA : router sans recharger — l'appel continue.
router.push(payload.path);
// Site classique : ouvrir un second onglet, celui-ci (et l'appel) reste vivant.
// window.open(payload.path, '_blank');
event.preventDefault(); // ← c'est ce qui dit à l'agent « c'est fait »
}
});
</script>
L'appel vit dans cette page. window.location.href = … décharge le document et la conversation part avec lui : le visiteur est coupé en pleine phrase. Si vous avez un routeur, naviguez côté client ; sinon, ouvrez la page dans un nouvel onglet. Il n'y a pas de reconnexion : rien ne survit à un rechargement.
preventDefault() n'est pas facultatifC'est le seul moyen de dire « je m'en suis chargé ». Sans lui, l'agent apprend que le site ne prend pas en charge la navigation : il cesse d'essayer pour le reste de l'appel et revient à décrire où cliquer. Rien n'apparaît dans la console — la page a simplement l'air d'avoir ignoré la requête, et c'est le cas.
Étape 3 — Essayez
Appelez votre agent depuis le site et demandez-lui une page par son nom. Deux choses doivent se produire : la page s'ouvre, et l'agent dit quelque chose comme « voici les tarifs » plutôt que « vous les trouverez dans le menu ».
Répondre à l'agent avec des données
Certaines commandes sont des questions, pas des instructions. Elles arrivent de la même façon, mais on y répond avec respond() :
| Commande | Ce que demande l'agent | Ce que vous renvoyez |
|---|---|---|
navigate | « ouvre ce chemin » | rien — preventDefault() suffit |
page_context | « que regarde le visiteur ? » | ce qui est utile : chemin, titre, produit |
cart_state | « qu'y a-t-il dans son panier ? » | articles, totaux, devise |
<script>
document.addEventListener('agent-command', (event) => {
const { type, respond } = event.detail;
if (type === 'page_context') {
event.preventDefault();
respond({ path: location.pathname, title: document.title });
}
});
</script>
Après preventDefault(), vous disposez d'environ une seconde : un await passe, un appel d'API lent non. Répondez avec ce que vous avez déjà.
Ce que l'agent peut et ne peut pas demander
- Uniquement des chemins de votre propre site. Un chemin doit commencer par
/. Tout ce qui pourrait quitter votre domaine —//evil.com,https://…, antislashs — est refusé avant d'atteindre votre page. Un agent ne peut pas envoyer vos visiteurs ailleurs. - Uniquement les appels depuis le navigateur. Lors d'un appel téléphonique, il n'y a pas de page à ouvrir : ces commandes n'y existent pas.
- Un refus suffit. Si votre page ne confirme pas la première requête, l'agent cesse de demander pour le reste de l'appel. Il ne réessaiera pas et — surtout — il ne dira pas au visiteur qu'il a ouvert quelque chose qu'il n'a pas ouvert.
Journalisez chaque commande avant de filtrer : document.addEventListener('agent-command', e => console.log(e.detail)). Si vous voyez navigate dans la console, l'agent a fait sa part et il manque preventDefault() ou votre handler. Si vous ne voyez rien, personne n'a dit à l'agent que ce chemin existe — retour à l'étape 1.
Prérequis techniques
Les widgets nécessitent que le navigateur du visiteur prenne en charge :
- WebGL 2.0 — pour le rendu
- Web Audio API — pour le traitement audio
- WebRTC — pour la communication vocale en temps réel
Tous les navigateurs modernes (Chrome, Firefox, Safari, Edge) prennent en charge ces technologies.
Restrictions de domaine
Contrôlez quels sites web peuvent intégrer le widget de votre agent.
Domaines toujours autorisés
Les domaines suivants sont toujours autorisés, quelle que soit la configuration :
hanc.ai(et sous-domaines)hanc.me(et sous-domaines)localhost
Autoriser tous les domaines
Par défaut, votre widget peut être intégré sur n'importe quel site web. Activez « Autoriser tous les domaines » dans les paramètres du widget pour restreindre cela.
Restreindre à des domaines spécifiques
Lorsque c'est restreint, ajoutez chaque domaine qui doit être autorisé :
- Saisissez les noms de domaine sans
https://(par ex.example.com) - Les sous-domaines nécessitent des entrées distinctes (par ex.
www.example.com,shop.example.com) - Les ports peuvent être spécifiés (par ex.
localhost:3000) - Un maximum de 50 domaines peut être mis en liste blanche
Pour les agents en production, restreignez les widgets à vos propres domaines afin d'empêcher toute intégration non autorisée.
Conditions générales
Activez une boîte de dialogue de consentement avant que les appelants puissent démarrer une conversation.
Configuration
| Paramètre | Description |
|---|---|
| Activer les conditions | Activer/désactiver la boîte de dialogue des conditions |
| Contenu des conditions | Texte de consentement au format Markdown affiché aux utilisateurs (max 5 000 caractères) |
| URL des conditions | Lien vers votre page complète Conditions générales |
| URL de confidentialité | Lien vers votre page Politique de confidentialité |
Lorsque c'est activé :
- Les utilisateurs voient une boîte de dialogue de consentement avant de démarrer un appel
- Ils doivent cliquer sur « Accepter » pour continuer
- Le consentement est stocké localement dans le navigateur
- Le bouton Réinitialiser le consentement efface le consentement stocké pour les tests
Mise en forme du contenu
Le contenu des conditions prend en charge la mise en forme Markdown :
- Utilisez
####pour les titres - Utilisez
**gras**pour l'emphase - Utilisez des sauts de ligne pour la lisibilité
Voir aussi
- Widget de rappel — Rappels téléphoniques pour les visiteurs qui préfèrent ne pas parler dans le navigateur
- Vue d'ensemble des agents vocaux
- Paramètres — Paramètres de l'agent, y compris la configuration du widget
- Intégrations — Clés API et configuration des numéros de téléphone