API du widget — Documentation Telybot

Pour les développeurs, ou toute personne souhaitant que le chat s'ouvre depuis son propre bouton.

Installation

<script src="https://telybot.com/widget.js"
        data-key="kb_live_your_key_here" async></script>

La balise de script n'a besoin que de src et data-key. Tout le reste — couleurs, position, message d'accueil, langue — provient de votre tableau de bord, si bien que vous n'avez jamais à redéployer votre site pour les modifier.

Le widget s'affiche dans la langue définie dans Installer → Langue parlée par votre bot : son bouton, ses champs et ses notices, ainsi que le sens de la mise en page (l'arabe et l'ourdou s'écrivent de droite à gauche). Les textes arrivent avec la configuration du widget, il n'y a donc pas de seconde requête ni rien à traduire de votre côté.

Modes

Flottant (par défaut). Un bouton de lancement dans le coin, ouvrant un panneau de discussion.

Intégré. Placez un conteneur vide sur la page et le chat s'y affichera à la place :

<div data-keyda-bot style="height:520px"></div>

Le conteneur a besoin d'une hauteur. En mode intégré, le chat est toujours visible, il n'y a donc rien à ouvrir ou à fermer.

API JavaScript

Disponible sur window.KeydaBot une fois le script chargé :

Appeler	Fonctionnalités
`KeydaBot.open()`	Ouvre le panneau de chat
`KeydaBot.close()`	Le ferme
`KeydaBot.toggle()`	Ouvre ou ferme
`KeydaBot.expand()`	Rend le panneau aussi haut que la fenêtre et jusqu'à 760px de large
`KeydaBot.shrink()`	Retour à la carte standard
`KeydaBot.isOpen`	`true` quand le chat est visible
`KeydaBot.isExpanded`	`true` pendant que le panneau est déployé
`KeydaBot.clientId`	L'identifiant client utilisé par cette page

Exemple — ouvrez le chat depuis votre propre bouton « Discutez avec nous » :

<button onclick="KeydaBot.open()">Chat with us</button>

Le script se charge de manière asynchrone, donc window.KeydaBot peut ne pas exister immédiatement après le chargement de la page. Attachez les gestionnaires à un clic plutôt que de les appeler pendant l'analyse de la page.

Comment il se comporte sur votre page

Le panneau s'ouvre au-dessus du bouton de lancement, qui reste à sa place et devient la commande de fermeture. Appuyer à nouveau dessus, sur la croix ✕ dans l'en-tête, ou appuyer sur Échap ferme le chat.
Un visiteur peut agrandir le panneau depuis l'en-tête — il s'étend à la hauteur de la fenêtre jusqu'à 760px de large — et ce choix est mémorisé dans son navigateur. Sur mobile, le panneau occupe déjà tout l'écran, cette option n'est donc pas affichée.
Votre paramètre taille du logo modifie le logo, pas le bouton : le lanceur conserve sa taille et le logo s'agrandit à l'intérieur. Taille du bouton (Installer → Apparence) redimensionne le bouton lui-même — petit, moyen ou grand — quelle que soit sa forme.
Quatre formes de bouton : une pilule avec votre libellé, une bulle ronde, un carré arrondi, et une bulle de discussion avec une pointe. La pointe se trouve du côté de votre page.
Tout est rendu à l'intérieur d'un shadow root, ainsi votre CSS ne peut pas casser le widget et le CSS du widget ne peut pas affecter votre site.
Le panneau ne se charge que lorsqu'un visiteur l'ouvre, il ne ralentit donc pas votre page.
La discussion s’ouvre sur votre message de bienvenue et jusqu’à quatre questions suggérées sous forme de boutons — rédigez les vôtres dans Installer → Questions suggérées, ou gardez celles par défaut. Rien d’autre n’est dit tant que le visiteur n’en touche pas une ou n’écrit pas, et les fiches de votre catalogue n’apparaissent que lorsqu’il pose une question sur les prix ou les articles.
Avec Indiquer qu’il s’agit d’un assistant IA activé, l’en-tête affiche « Assistant IA » sous le nom de votre bot sur chaque écran.
Une discussion dure aussi longtemps que l’onglet du navigateur du visiteur. Passer d’une page à l’autre de votre site la conserve, et rouvrir le panneau restaure le fil — fichiers compris, ainsi qu’une question du parcours de bienvenue qui attendait encore une réponse. Fermer l’onglet y met fin, et sa visite suivante ouvre une nouvelle discussion. Une réponse de votre équipe parvient quand même à un visiteur qui a demandé une personne, dans sa discussion suivante, pendant deux semaines.
Les discussions venant du même navigateur sont reliées dans Discussions (« Visiteur · 3 discussions »), pour que vous puissiez lire côte à côte les conversations d’un même visiteur. Le lien est un identifiant aléatoire conservé dans le navigateur du visiteur ; il n’est pas créé quand son navigateur demande à ne pas être suivi.
Le trombone dans le champ de saisie permet à un visiteur de joindre jusqu'à trois photos ou documents à un message (tailles et types dans Limites et sécurité). Les photos sont redimensionnées dans le navigateur avant l'envoi, si bien qu'une photo de 12 mégapixels quitte la page à quelques centaines de kilo-octets. Désactivez les fichiers sous Installer et le bouton disparaît.
Un parcours de bienvenue se déroule comme des bulles ordinaires : les choix deviennent des boutons sous la bulle, un bouton Ignorer apparaît quand une étape est facultative, et le texte indicatif du champ de saisie devient la question. Un parcours terminé est mémorisé dans le navigateur du visiteur pendant 30 jours.
Si l'assistant est injoignable, le widget affiche un court message et ne provoque jamais d'erreur sur votre page.

Dans les SDK d'application

Le même chat fonctionne dans chaque SDK, donc les pièces jointes et les parcours de bienvenue arrivent dans votre application sans nouvelle version — à une exception près. Ouvrir un sélecteur de fichiers depuis une web view est le rôle de l'application hôte. Les packages iOS, React Native et Ionic le font déjà ; Android et Flutter nécessitent le SDK 0.1.4 ou ultérieur. Sur les versions plus anciennes, le widget reconnaît l'environnement et masque le trombone plutôt que d'afficher un bouton inactif.

Sur iOS, la feuille système propose Take Photo dès que les images sont acceptées, et la sélectionner fait planter une application sans NSCameraUsageDescription dans son Info.plist. Ajoutez cette clé avant de publier une version contenant le chat.