API JavaScript du chat en direct
Utilisez l'API JavaScript onWebChat pour personnaliser votre widget de chat et automatiser les flux. Vous pouvez transmettre les données du visiteur, définir la langue du widget, maximiser ou masquer le widget et plus encore.
Par exemple, vous pouvez envoyer les détails du visiteur au chat, définir la langue par page ou ouvrir le widget par programmation lorsqu'un utilisateur clique sur un bouton.
Ajoutez votre code API directement sous le script du widget de chat, comme indiqué à droite.
<script type='text/javascript'>
/* Collez ici le code d'installation du widget onWebChat disponible dans le tableau de bord. */
</script>
<script type='text/javascript'>
/* Ajoutez ci-dessous vos appels à l'API JavaScript, par exemple onWebChat.set() ou onWebChat.get() */
</script>
Définir les informations du visiteur
Vous pouvez définir les informations du visiteur avant ou pendant une session de chat. Par exemple, définir le nom aide votre équipe à identifier les contacts dans la liste des visiteurs.
Utilisez ces appels API pour définir le nom, l'e-mail, le téléphone et les notes du visiteur :
onWebChat.set("name","Sarah Chen");
onWebChat.set("email","sarah.chen@example.com");
onWebChat.set("phone","+1 555 010 0142");
onWebChat.set("notes","Returning visitor, requested an Enterprise trial");
Obtenir les informations du visiteur
Vous pouvez lire le nom, l'e-mail, le téléphone et les notes du visiteur chaque fois que ces valeurs ont été fournies via cette API JavaScript, collectées dans le formulaire pré-chat ou mises à jour par les agents dans le tableau de bord.
Vous devez appeler ces fonctions après le chargement complet du widget. Exemple :
onWebChat.set("onWebChatLoaded", function() { console.log("visitor name: " + onWebChat.get("name")); });
onWebChat.get("name");
onWebChat.get("email");
onWebChat.get("phone");
onWebChat.get("notes");
Définir la langue du widget
Vous pouvez définir la langue du widget avec le code de n'importe quelle langue activée dans votre tableau de bord.
Par exemple, utilisez "en" pour l'anglais, "es" pour l'espagnol et "fr" pour le français. Si le code indiqué ne correspond à aucune langue activée, le widget utilise votre langue par défaut. Sans cet appel, le widget utilise la langue du navigateur du visiteur, si vous avez activé cette option. Gérez vos langues activées et votre langue par défaut dans Paramètres > Widget > Langues.
Codes de langue disponibles :
onWebChat.set("language","es");
Définir l'apparence du widget
Vous pouvez contrôler la visibilité du widget et son état ouvert ou fermé :
Utilisez le paramètre max avec 0 pour minimiser ou 1 pour maximiser le widget.
Pour masquer complètement le widget, utilisez le paramètre show avec la valeur 0. Utilisez 1 pour l'afficher à nouveau.
onWebChat.set("max",1);
onWebChat.set("show",0);
Définir la taille du widget
Sur une page précise, vous pouvez afficher le widget dans l'une des trois tailles proposées dans Paramètres > Widget > Paramètres du widget, sans modifier la taille enregistrée dans votre compte.
Utilisez le paramètre size avec la valeur "standard" (la taille Petit du tableau de bord), "large" ou "xlarge" (Très grand). C'est utile sur les pages où l'espace est limité, ou sur une page de destination où vous voulez un widget plus grand.
Important : placez cet appel juste en dessous du script du widget, avant son chargement. Le widget est construit une seule fois, au chargement, donc une taille définie après est ignorée.
onWebChat.set("size","standard");
onWebChat.set("size","large");
onWebChat.set("size","xlarge");
Modifier les textes du widget
Vous pouvez remplacer les textes du widget sur une page précise, par exemple un message d'accueil différent sur votre page de tarifs. Les nouveaux textes sont utilisés uniquement sur cette page et ne sont pas enregistrés dans votre tableau de bord.
Utilisez le paramètre texts avec un objet contenant les champs à modifier, par exemple max_title, max_subtitle, min_online, min_offline, off_title, off_subtitle, off_msg ou prechat_msg.
Un texte donné sous forme de chaîne est utilisé dans toutes les langues de votre widget. Pour ne modifier qu'une seule langue, passez un objet avec les codes de langue, comme dans le deuxième exemple.
Vous pouvez l'appeler sous le script du widget, avant son chargement, ou à tout moment ensuite : le widget est redessiné avec les nouveaux textes.
onWebChat.set("texts",{
max_title: "Need help?",
max_subtitle: "We usually reply in a minute"
});
onWebChat.set("texts",{
min_online: { en: "Chat with us", es: "Chatea con nosotros" }
});
Définir les couleurs du widget
Sur une page précise, vous pouvez donner à l'en-tête du widget une couleur lorsque votre chat est en ligne et une autre lorsqu'il est hors ligne. Utilisez les paramètres onlineColor et offlineColor avec n'importe quelle couleur CSS, par exemple "#2e7d32".
Ces couleurs ne s'appliquent qu'à cette page et ne modifient pas la couleur enregistrée dans Paramètres > Widget > Paramètres du widget. Vous pouvez les définir avant le chargement du widget ou à tout moment ensuite. La couleur hors ligne est aussi utilisée pour le bouton Envoyer du formulaire hors ligne.
onWebChat.set("onlineColor","#2e7d32");
onWebChat.set("offlineColor","#757575");
Définir les informations de page
Vous pouvez remplacer l'URL et le titre de la page actuelle transmis au tableau de bord onWebChat :
Utilisez le paramètre pageUrl pour définir une URL personnalisée. C'est particulièrement utile pour les applications monopages (SPA) ou le routage personnalisé, lorsque l'URL du navigateur ne change pas.
Utilisez le paramètre pageTitle pour définir un titre personnalisé que les agents verront à la place du titre de la page du navigateur.
onWebChat.set("pageUrl","https://www.example.com/checkout/step-2");
onWebChat.set("pageTitle","Checkout: shipping details");
Obtenir le statut du widget
Cette fonction renvoie "online" ou "offline" selon la disponibilité actuelle de votre chat.
Veillez à appeler cette fonction après le chargement complet du widget. Exemple :
onWebChat.set("onWebChatLoaded", function() { console.log("chat status: " + onWebChat.get("status")); });
onWebChat.get("status");
Obtenir le statut de connexion
Renvoie true si le widget de chat a une connexion socket active avec le serveur, et false dans le cas contraire.
onWebChat.get("isConnected");
Obtenir l'état ouvert/fermé du widget
Renvoie true si le widget de chat est actuellement maximisé (ouvert), ou false s'il est minimisé (fermé).
onWebChat.get("isMaximized");
Obtenir l'ID du dialogue
Renvoie l'ID du dialogue actif en cours, ou 0 s'il n'y a aucune session de chat active. Il s'agit du même ID que chat_id dans les données envoyées par les webhooks : il est donc utile pour les intégrations qui doivent relier une session de chat à un CRM ou à un système de tickets.
onWebChat.get("dialogId");
Envoyer un message
Vous pouvez envoyer un message de chat au nom du visiteur par programmation. C'est utile pour créer des parcours d'aide contextuels, par exemple envoyer automatiquement « J'ai besoin d'aide pour ma commande » lorsqu'un visiteur clique sur un bouton précis.
Le message apparaît dans le chat exactement comme si le visiteur l'avait tapé, et la fenêtre de chat s'ouvre. Le widget doit être entièrement chargé et connecté avant que vous puissiez envoyer un message. Pour éviter les abus, le widget envoie au plus 3 messages par seconde, 8 par minute et 30 par heure de cette façon.
onWebChat.set("sendMessage","I need help with my order");
Définir le département
Vous pouvez présélectionner un département pour le visiteur selon la page qu'il consulte. Par exemple, vous pouvez diriger automatiquement les visiteurs de votre page de tarifs vers le département « Ventes », et ceux de votre page d'aide vers « Support ».
Vous pouvez passer soit le nom du département (chaîne de caractères), soit son ID (nombre). Si vous utilisez le nom, il doit correspondre exactement à l'un des départements configurés dans votre tableau de bord.
Vous trouverez l'ID du département dans votre tableau de bord : allez dans Paramètres > Équipe > Départements et cliquez sur un département. L'ID s'affiche à côté du nom du département.
Vous n'avez pas besoin d'activer l'option départements dans le formulaire pré-chat : définir le département avec l'API JavaScript fonctionne de manière autonome.
Si aucun agent du département sélectionné n'est en ligne, le message est distribué à tous les agents connectés. Si le chatbot IA est activé, il ne répond pas tant qu'un agent du département est en ligne, et il répond au visiteur quand aucun ne l'est.
Pour plus d'informations sur les départements, consultez notre guide des départements.
onWebChat.set("department","Sales");
onWebChat.set("department",1333);
Fonctions de rappel (callbacks)
Vous pouvez exécuter des fonctions de rappel lorsque certains événements du chat se produisent :
onClick s'exécute quand un visiteur clique sur le widget de chat.
onMaximize s'exécute quand le widget est maximisé (ouvert).
onMinimize s'exécute quand le widget est minimisé (fermé).
onTrigger s'exécute quand un déclencheur d'engagement ou d'intention de sortie se déclenche, même lorsque le widget est masqué avec show réglé sur 0.
onStartWriting s'exécute quand le visiteur commence à taper un message (une fois par session de navigation).
onNewMessage s'exécute quand un nouveau message est envoyé ou reçu. La fonction reçoit deux arguments : le texte du message et l'expéditeur ("visitor", "agent" ou "bot").
onEndChat s'exécute quand la session de chat se termine. La fonction reçoit un argument indiquant qui l'a terminée ("visitor", "agent" ou "bot").
onChatStatusChange s'exécute quand le statut du widget de chat change. La fonction reçoit un argument indiquant le nouveau statut ("online" ou "offline").
onWebChatLoaded s'exécute dès que le widget de chat a fini de se charger.
onWebChat.set("onClick",function(){ alert('chat widget is clicked'); });
onWebChat.set("onMaximize",function(){ alert('chat maximized'); });
onWebChat.set("onMinimize",function(){ alert('chat minimized'); });
onWebChat.set("onTrigger",function(){ alert('trigger activated'); });
onWebChat.set("onStartWriting",function(){ alert('visitor is writing'); });
onWebChat.set("onNewMessage",function(msg, by){
console.log('new message by ' + by + ': ' + msg);
});
onWebChat.set("onEndChat",function(endedBy){
console.log('chat ended by ' + endedBy);
});
onWebChat.set("onChatStatusChange",function(status){
console.log('agents are now ' + status);
});
onWebChat.set("onWebChatLoaded",function(){ alert('chat widget is loaded'); });