API JavaScript : piloter ton agent

Avec l'API JavaScript, tu pilotes ton agent LeadWin depuis ton propre site web. Tes propres boutons ouvrent le chat directement sur le formulaire de contact ou sur la réservation, et ton mode sombre comme ton sélecteur de langue font basculer l'agent en même temps. La page du tableau de bord est un guide avec des exemples de code à copier : elle ne modifie aucun réglage.

En un coup d'œil

• Tu trouves la page dans le tableau de bord LeadWin sous Apparence → API.
• L'API est incluse dans chaque abonnement, y compris Free. Les écrans qu'elle peut ouvrir dépendent toutefois de ton abonnement, voir le comparatif des abonnements.
• Elle nécessite le code de l'installation sur ton site web. Tu ne reçois ce code qu'une fois le contrat de sous-traitance conclu. Avec une inscription sur leadwin.ai, c'est déjà le cas, si tu viens de Feedbax, comme prestataire ou client, tu l'acceptes sous Confidentialité.
• Les boutons avec l'attribut data-leadwin-open fonctionnent sans JavaScript de ta part, dans n'importe quel CMS.
• Chaque appel ne s'applique qu'au visiteur concerné et ne modifie jamais tes réglages dans le tableau de bord.
• La page est visible pour les propriétaires et les administrateurs. Tu attribues les rôles dans l'espace Équipe.

Comment ça marche

Le code de l'installation charge la fonction LeadWin sur ton site web. Tu l'appelles avec une commande et une valeur, par exemple LeadWin('open', 'lead'). Les majuscules et minuscules de la commande n'ont pas d'importance. LeadWin ignore une commande inconnue, et l'API ne provoque jamais d'erreur dans ta page.

Ton agent LeadWin ne se charge qu'une fois ta page entièrement chargée. Si ton propre JavaScript l'appelle avant, le socle intercepte l'appel et le transmet dès que l'agent est prêt. À l'inverse, ton agent LeadWin ne modifie rien sur ta page. Il signale seulement quand le chat s'ouvre ou se ferme. Ce que ta page en fait, c'est toi qui le décides.

Voici les commandes disponibles :

Intégrer le socle

Tu n'as besoin du socle que si tu appelles LeadWin depuis ton propre JavaScript. Pour les boutons avec data-leadwin-open, il n'est pas nécessaire.

1. Ouvre Apparence → API et clique sur Copier le code dans la première carte. Le message Code copié le confirme.
2. Colle le code une seule fois dans la section head de ta page, au-dessus des scripts qui appellent LeadWin.
3. Laisse le code de l'installation tel quel. La position du socle par rapport à ce code n'a aucune importance.

<script>
    globalThis.LeadWin ??= (...args) =>
        (globalThis.LeadWin.q ??= []).push(args);
</script>

Ouvrir et fermer le chat

Avec open, tu déploies le chat. Si tu indiques un écran, il s'ouvre directement dessus :

• lead : le formulaire de contact. Ce que les visiteurs y saisissent arrive dans tes demandes.
• booking : la réservation. Elle doit être configurée.
• helpcenter : ton centre d'aide. Il te faut pour cela un centre d'aide actif issu de ta base de connaissances.
• profile : la vue profil de ton entreprise, issue de ton profil.

Si ton agent LeadWin ne propose pas un écran, c'est le chat qui s'ouvre. close le ferme, toggle alterne entre ouvert et fermé.

LeadWin('open');
LeadWin('open', { screen: 'lead' });
LeadWin('open', { screen: 'booking' });
LeadWin('close');
LeadWin('toggle');

Intégrer des boutons sans JavaScript

Chaque élément portant l'attribut data-leadwin-open ouvre le chat au clic. Comme valeur, tu indiques l'écran. Sans valeur, c'est le chat lui-même qui s'ouvre. Cela fonctionne dans n'importe quel CMS, y compris pour les éléments ajoutés plus tard à la page, et ne nécessite ni le socle ni JavaScript de ta part.

<button data-leadwin-open="lead">Contacter l'équipe</button>
<button data-leadwin-open>Ouvrir le chat</button>

Poser une question au nom du visiteur

Avec ask, tu ouvres le chat et poses aussitôt une question, comme si le visiteur l'avait tapée. Cela convient aux boutons qui portent toujours la même question, par exemple « Quels tarifs ? ».

• La question compte de 1 à 1 000 caractères. Si elle est vide ou plus longue, rien ne se passe.
• Elle arrive dans la conversation que le visiteur a ouverte. Avec newChat: true, elle en démarre une nouvelle.
• Si ton agent LeadWin est en train de rédiger une réponse, le clic est ignoré.
• La question est un message normal du visiteur. Une nouvelle conversation est donc décomptée de ton quota de conversations.

LeadWin('ask', 'Quels tarifs ?');
LeadWin('ask', { prompt: 'Quels tarifs ?' });
LeadWin('ask', { prompt: 'Quels tarifs ?', newChat: true });

Coupler le mode sombre

Si ton site web bascule entre clair et sombre, theme fait basculer ton agent LeadWin en même temps. Cela ne fonctionne que si, sous Apparence, le thème est réglé sur API. Jusqu'au premier appel, ton agent LeadWin affiche alors le thème clair. L'appel ne s'applique qu'au visiteur qui le déclenche. Avec auto, tu le réinitialises.

LeadWin('theme', 'dark');
LeadWin('theme', 'light');
LeadWin('theme', 'auto');

Coupler la langue

Lors d'un changement de page normal, ton agent LeadWin relit de toute façon l'indication de langue de ta page. Tu n'as besoin de la commande language que si les visiteurs changent de langue sans rechargement de la page. Elle accepte de, en, fr et nl, y compris sous forme de code régional comme de-DE. Seules les langues activées sous Langue sont prises en compte. Si le chat est ouvert, il se recharge dans la nouvelle langue et la conversation continue. Avec auto, tu rends la décision à l'indication de langue de ta page.

LeadWin('language', 'en');
LeadWin('language', 'auto');

Réagir à l'ouverture

Quand le chat s'ouvre ou se ferme, ton agent LeadWin déclenche l'événement leadwin:panel sur ta page. event.detail.open contient true ou false. L'événement n'est déclenché que lors d'un vrai changement, pas à chaque commande. Il remonte dans le document, tu peux donc aussi l'écouter sur window. Tu peux ainsi, par exemple, masquer une barre fixe ou mettre une vidéo en pause tant que le chat est ouvert.

document.addEventListener('leadwin:panel', (event) =>
    document.body.classList.toggle('leadwin-open', event.detail.open));

Autres commandes et attributs

Ces possibilités ne figurent pas sur la page du tableau de bord, mais fonctionnent de la même façon :

• LeadWin('article', 'cle') : ouvre le chat directement sur un article de ton centre d'aide. Comme clé, tu utilises le slug de l'adresse de l'article ou son GUID. Lettres, chiffres, trait d'union et tiret bas sont autorisés, 300 caractères au maximum.
• LeadWin('consent', 'granted') : transmet la décision de ta bannière de cookies. Le lien avec le consentement est expliqué dans Confidentialité.
• data-lang : sur le code de l'installation, cet attribut définit la langue de la page, par exemple data-lang="en". Il prime sur l'attribut lang de la balise html.
• data-title : sur le code de l'installation, cet attribut définit comment les lecteurs d'écran annoncent le launcher. Sans valeur, il s'appelle Chat.

Tu places ces deux attributs dans la balise script d'ouverture qui contient déjà data-key.

Ce que comprend ton abonnement

L'API JavaScript est incluse dans chaque abonnement, de Free à Scale. Ce qu'une commande peut ouvrir dépend de ce que comprend ton abonnement : la réservation est disponible à partir de Basic, ton propre centre d'aide à partir de Pro. Le thème API est inclus dans chaque abonnement. Avec Feedbax Business, les limites de Basic s'appliquent, avec Premium celles de Pro et avec Enterprise celles de Scale. Pour en savoir plus, consulte LeadWin dans l'abonnement Feedbax.

Questions fréquentes

Comment mon bouton Contact peut-il ouvrir le formulaire LeadWin ?

Ajoute l'attribut data-leadwin-open="lead" au bouton. Tu n'as besoin d'aucun JavaScript de ta part pour cela.

Un bouton peut-il ouvrir directement la réservation ?

Oui, avec data-leadwin-open="booking" ou LeadWin('open', { screen: 'booking' }). La réservation doit être configurée, sinon c'est le chat qui s'ouvre.

Mon site web a un mode sombre. Comment le chat peut-il suivre ?

Règle le thème sur API sous Apparence et appelle LeadWin('theme', 'dark') ou LeadWin('theme', 'light') dès que ton site web bascule.

LeadWin('theme', 'dark') ne fait rien. Pourquoi ?

Le thème n'est pas réglé sur API. La commande ne fonctionne que dans ce cas.

Ai-je besoin du socle ?

Seulement si ton propre JavaScript appelle LeadWin, éventuellement avant que ton agent LeadWin soit chargé. Pas pour les boutons avec data-leadwin-open.

Puis-je réagir quand le chat s'ouvre ?

Oui. Écoute l'événement leadwin:panel et lis event.detail.open.

Puis-je envoyer une question au nom du visiteur ?

Oui, avec LeadWin('ask', 'Ta question') et jusqu'à 1 000 caractères. La question arrive dans la conversation ouverte, sauf si tu indiques newChat: true.

LeadWin('language', 'fr') fonctionne-t-il si le français n'est pas activé ?

Non. La commande n'accepte que les langues activées sous Langue.

Articles associés

• Installation : intégrer le code sur ton site web
• Apparence : logo, couleurs, launcher et thème
• Langue : les langues dans lesquelles ton agent LeadWin s'affiche
• Confidentialité : consentement, politique de confidentialité et contrat de sous-traitance