Installer l'agent vocal IA Netcoder sur votre site Web

Guide d'installation • Agent vocal

L'agent vocal Netcoder est un widget léger qui s'ajoute à n'importe quel site Web avec une seule balise HTML. Vos visiteurs parlent à voix haute à votre agent IA, directement dans leur navigateur, sans téléphone et sans rien installer : ils cliquent, permettent le micro et parlent comme au téléphone. L'agent répond de vive voix, et la conversation s'affiche à l'écran à mesure.

1. Installation

Ajoutez la balise de script suivante juste avant la balise </body> de chaque page où l'agent vocal doit paraître. Remplacez les valeurs d'exemple par celles de votre compte (voir la section 4).

<script src="https://cdn.netcoder.com/voicebot.v1.3.js"
        data-backend-url="wss://relay.netcoder.ca/voice"
        data-client-key="YOUR-CLIENT-GUID"
        data-agent-key="YOUR-AGENT-GUID"
        data-language="fr"></script>

C'est tout. Un bouton de téléphone flottant apparaît dans le coin inférieur droit de la page ; la carte d'appel, le son, le style et la conversation sont fournis par le script, et rien d'autre n'est à installer sur votre serveur.

Le plus simple est de le prendre dans l'application Netcoder : ouvrez votre agent IA, puis Tester et déployer, Code d'intégration. Le code y est donné avec vos clés, prêt à copier.

Deux conditions : la page doit être servie en HTTPS, car les navigateurs ne donnent le micro qu'à une page sécurisée, et votre agent IA doit avoir un canal Web Voice, que Netcoder met en place.

2. Styles d'affichage

Le même script présente l'agent vocal de trois façons, au choix des attributs data-container et data-collapsed.

Bouton flottant (par défaut)

Sans data-container, l'agent vocal est un bouton de téléphone rond, fixé dans le coin inférieur droit, comme une bulle de clavardage. Un clic ouvre la carte d'appel au-dessus.

À côté du chatbot — quand le chatbot Netcoder est sur la même page, le bouton de téléphone se place à gauche de la bulle de clavardage plutôt que de la couvrir. Les deux scripts peuvent être dans n'importe quel ordre.
Un panneau à la fois — la carte d'appel et la fenêtre de clavardage s'ouvrent dans le même coin : ouvrir l'une ferme l'autre.
Un appel n'est jamais oublié — si le visiteur cache la carte pendant un appel, l'appel continue, et le bouton devient vert et pulse jusqu'à la fin. Fermer la carte avec son bouton × raccroche.

Carte intégrée

Avec data-container, la carte complète est dessinée dans un élément de votre page, par exemple sur une page de démonstration ou de contact. Ajoutez un élément vide là où la carte doit paraître, et désignez-le à data-container par un sélecteur CSS :

<div id="voice-demo"></div>
<script src="https://cdn.netcoder.com/voicebot.v1.3.js"
        data-backend-url="wss://relay.netcoder.ca/voice"
        data-client-key="YOUR-CLIENT-GUID"
        data-agent-key="YOUR-AGENT-GUID"
        data-language="fr"
        data-container="#voice-demo"></script>

La carte prend toute la largeur de son conteneur, jusqu'à 420 px, centrée. Si le sélecteur ne trouve rien, le script revient au bouton flottant.

Carte intégrée compacte

Ajoutez data-collapsed="true" à une carte intégrée pour qu'elle commence sur une seule ligne — le titre, l'état et un bouton d'appel plus petit — et s'ouvre en carte complète au début de l'appel. Elle convient à une barre latérale ou à une colonne étroite.

<script src="https://cdn.netcoder.com/voicebot.v1.3.js"
        ...
        data-container="#voice-contact"
        data-collapsed="true"></script>

3. Paramètres

À placer sur la balise de script.

Attribut	Obligatoire	Description	Par défaut
`data-backend-url`	Oui	Adresse du relais Netcoder : `wss://relay.netcoder.ca/voice`
`data-client-key`	Oui	Votre clé client
`data-agent-key`	Oui	La clé de votre agent IA, qui doit avoir un canal Web Voice
`data-language`		`en` ou `fr` : la carte, ce qui est entendu et la voix	`en`
`data-title`		Nom affiché sur la carte	Assistant Netcoder
`data-subtitle`		Ligne sous le titre
`data-welcome`		Première phrase de l'agent, 300 caractères au plus	Celle de la langue
`data-accent-color`		Couleur principale	`#D97955`
`data-accent-text-color`		Couleur du texte sur la couleur principale	`#FFFFFF`
`data-container`		Sélecteur CSS de l'élément où dessiner la carte	Bouton flottant
`data-collapsed`		`true` : une carte intégrée commence sur une ligne
`data-debug`		`true` : trace l'appel dans la console du navigateur

4. Obtenir vos clés

La clé client et la clé de l'agent sont des GUID qui identifient votre compte et l'agent IA qui répond, par exemple 3f2a7b10-9c4d-4e21-8a6f-1b2c3d4e5f60. Les deux sont dans l'application Netcoder, sur la page de votre agent IA, sous Tester et déployer, Code d'intégration, chacune avec un bouton pour la copier. L'agent vocal et le chatbot partagent les mêmes clés : le même agent répond aux deux, avec les mêmes connaissances et les mêmes règles.

Si une clé manque ou est mal formée, la carte affiche « Configuration invalide : data-client-key et data-agent-key doivent être des GUID. » quand le visiteur lance l'appel, et le serveur n'est pas contacté. Si les clés sont valides mais inconnues, ou si l'agent n'a pas de canal Web Voice, l'appel ne passe pas : vérifiez les valeurs dans l'application.

5. Langue et voix

L'attribut data-language fixe la langue de la carte (état, boutons, messages), celle dans laquelle la parole est transcrite, celle dans laquelle l'agent répond, et la voix avec laquelle il parle :

en — anglais (par défaut).
fr — français.

N'utilisez que ces deux valeurs. Sur un site bilingue, donnez à chaque page sa langue, et accordez-y data-title et data-welcome.

La voix de l'agent se choisit dans l'application Netcoder, dans la section Voix de la page de votre agent IA, après avoir écouté chaque voix en français et en anglais : un français québécois, de France ou international, un anglais canadien, américain ou britannique, une voix d'homme ou de femme. Rien n'est à changer dans le code de votre page.

6. Avec le chatbot

L'agent vocal est fait pour se placer à côté du chatbot Netcoder, pour que vos visiteurs choisissent entre écrire et parler. Ajoutez les deux scripts à la page ; avec les mêmes clés, le même agent répond aux deux :

<script src="https://cdn.netcoder.com/chatbot.v2.2.js"
        data-backend-url="wss://relay.netcoder.ca/chatbot"
        data-client-key="YOUR-CLIENT-GUID"
        data-agent-key="YOUR-AGENT-GUID"
        data-language="fr"></script>
<script src="https://cdn.netcoder.com/voicebot.v1.3.js"
        data-backend-url="wss://relay.netcoder.ca/voice"
        data-client-key="YOUR-CLIENT-GUID"
        data-agent-key="YOUR-AGENT-GUID"
        data-language="fr"></script>

Le bouton de téléphone se place à gauche de la bulle de clavardage, et un seul des deux panneaux est ouvert à la fois. Notez les deux adresses : /chatbot pour le chatbot, /voice pour l'agent vocal.

7. Personnaliser en CSS

Au-delà du titre et des deux couleurs, personnalisez le widget depuis votre propre feuille de style. Ses styles se chargent après les vôtres : commencez vos sélecteurs par body pour l'emporter, plutôt que d'utiliser !important.

body #ncv-launcher { bottom: 96px; }

Sélecteur	Ce que c'est
`--ncv-accent`	Variable : la couleur principale, de `data-accent-color`
`--ncv-on-accent`	Variable : le texte posé dessus, de `data-accent-text-color`
`#ncv-launcher`	Le bouton de téléphone flottant, 60 × 60 px
`#ncv-popup`	Le panneau flottant, 360 px de large ; `ncv-open` une fois ouvert
`.ncv-card`	La carte ; `data-state` donne l'état de l'appel
`.ncv-transcript`	La conversation ; `.ncv-msg` avec `.ncv-user` ou `.ncv-agent`
`.ncv-call`	Le bouton d'appel, vert, rouge pendant un appel

Un texte blanc sur #D97955, la couleur par défaut, est sous le contraste WCAG AA de 4,5:1 : foncez la couleur, ou prenez un texte foncé comme #1B1B1B.

8. Comment ça fonctionne

Quand le visiteur lance un appel, le navigateur demande le micro. Le widget envoie ensuite le son, par un WebSocket sécurisé, au relais Netcoder, qui le transcrit pendant que le visiteur parle ; les mots paraissent sur la carte à mesure qu'ils sont reconnus. Quand le visiteur fait une pause, la phrase va à votre agent IA, et sa réponse, transformée en parole, revient en continu : l'agent commence à parler en quelques instants.

Interruptions — le visiteur peut couper la parole à l'agent à tout moment, comme au téléphone : l'agent se tait et écoute.
Durée — les appels sont limités, à cinq minutes pour l'instant. La carte montre le temps écoulé par rapport à la limite, et l'agent dit au revoir quand elle est atteinte.
Lignes occupées — le nombre d'appels simultanés est limité. Quand toutes les lignes sont prises, le visiteur est invité à réessayer dans quelques minutes.
Fin de l'appel — l'appel se termine quand le visiteur raccroche, ferme la carte flottante ou quitte la page.
Si la voix fait défaut — l'appel continue, et les réponses s'affichent en texte sur la carte.

9. Essais et dépannage

Essayez avant d'installer — dans l'application Netcoder, Tester et déployer, sur la page de votre agent IA, l'appelle tel que vos visiteurs le feront.
Le bouton n'apparaît pas — vérifiez que l'adresse du script est joignable et que le code est placé avant </body>. Après un changement du code, rechargez la page sans cache (Ctrl+Maj+R).
Accès au micro refusé — le visiteur a refusé le micro, ou l'a bloqué auparavant. La carte le dit ; il peut être permis de nouveau depuis le cadenas de la barre d'adresse.
Le micro n'est jamais demandé — la page n'est pas servie en HTTPS. Les navigateurs ne permettent le micro que sur des pages sécurisées (et sur localhost pour le développement).
« Impossible de joindre l’assistant » — le relais n'a pas pu être joint, ou a refusé l'appel. Vérifiez les clés, l'adresse WebSocket, et que l'agent a un canal Web Voice.
Rien ne se passe sur une page https:// — l'adresse doit commencer par wss:// et non ws://.
Navigateur non pris en charge — l'agent vocal demande un Chrome, Edge, Firefox ou Safari récent. Les anciens navigateurs affichent un message plutôt qu'un appel.
L'agent n'entend pas le visiteur — ajoutez ?ncv-debug à l'adresse de la page, ou data-debug="true" à la balise de script, et ouvrez la console du navigateur pendant un appel. Elle montre le micro utilisé, le niveau sonore envoyé toutes les deux secondes et chaque message du relais. Un niveau qui reste à 0.000 pendant que le visiteur parle veut dire que le navigateur utilise le mauvais micro, ou un micro en sourdine.
Tous les domaines fonctionnent — l'agent vocal s'installe sur n'importe quel site Web ; rien n'est à configurer sur votre serveur.

10. Exemple complet

Un agent vocal flottant avec toutes ses options :

<script src="https://cdn.netcoder.com/voicebot.v1.3.js"
        data-backend-url="wss://relay.netcoder.ca/voice"
        data-client-key="3f2a7b10-9c4d-4e21-8a6f-1b2c3d4e5f60"
        data-agent-key="a1b2c3d4-e5f6-4788-9a0b-1c2d3e4f5a6b"
        data-language="fr"
        data-title="Alicia"
        data-subtitle="Service à la clientèle"
        data-welcome="Bonjour, je suis Alicia. Comment puis-je vous aider?"
        data-accent-color="#D97955"
        data-accent-text-color="#FFFFFF"></script>

Besoin d'aide, ou d'un canal Web Voice pour votre agent ? Prenez rendez-vous ou écrivez-nous.