betool

Documentation

Chat widget web

Widget de chat embarquable sur n'importe quel site, en script JS unique.

Le chat widget est un script JS que vous embarquez sur votre site (marketing, support, app). Il ouvre une fenêtre de conversation animée par un de vos pipelines betool ; les réponses de l'agent s'affichent au fil de l'eau (streaming).

Caractéristiques

  • Un snippet à coller dans votre page. Aucune dépendance npm ; le widget vit dans un Shadow DOM, donc le CSS de votre site ne le déforme pas (et inversement).
  • Token public — régénérable à tout moment depuis l'éditeur. Pas de secret côté client.
  • Continuité par onglet — l'identifiant de conversation est conservé en sessionStorage : un rechargement de page reprend le fil, fermer l'onglet le termine. Le widget ne dépose aucun cookie.
  • 8 langues — l'interface du widget suit la langue du navigateur du visiteur.
  • Garde-fous anti-abus actifs par défaut — 20 messages par minute et par IP, 10 nouvelles sessions par minute et par IP, 4 000 caractères maximum par message (réglables ; 0 désactive une protection). Un plafond global par widget (20 fois la limite par IP) bloque aussi les inondations réparties sur plusieurs IP.

Mise en place

  1. Dans l'éditeur du modèle, configurez le nœud Start avec un récepteur Chat (widget web).
  2. À l'enregistrement, betool génère le token public et affiche le snippet d'intégration, prêt à copier :
<script src="https://platform.betool.ai/widget/v1/widget.js"></script>
<script>
  BetoolChat.init({ token: "<token-public-du-widget>" });
</script>
  1. Collez ce snippet dans la balise <body> de votre site. Le widget apparaît automatiquement, en bas à droite par défaut.

Personnalisation

Depuis la configuration du récepteur :

  • Apparence — titre affiché, couleur primaire, position (quatre coins), forme du lanceur (onglet ou bulle) et son libellé.
  • Textes — message d'accueil, texte du champ de saisie, texte de statut (ou affichage « en ligne » traduit).
  • Rendu — affichage du markdown des réponses (activé par défaut).
  • Contexte de page — transmet à chaque message l'origine et le chemin de la page courante (jamais la query string). Activé par défaut, désactivable.
  • Périmètre — restreindre les origines autorisées.

Sécurité

Le token est public par design : il ne permet que de parler au modèle qui porte ce récepteur. Si vous listez des origines autorisées, une requête venue d'une autre origine est refusée côté serveur (403) ; une liste vide (ou *) n'impose aucune restriction — à réserver au développement. Pour révoquer un token compromis : bouton régénérer à côté de l'URL publique, dans la configuration du récepteur (tous les snippets déjà en production cessent alors de fonctionner).

Limites

  • Pas de co-browsing : l'agent ne voit pas la page de l'utilisateur, seulement son origine et son chemin (si le contexte de page est activé).
  • Pas d'envoi de pièces jointes depuis le widget. Pour recevoir des fichiers, utilisez un pipeline email ou webhook.
  • Pas de reprise de conversation d'une visite à l'autre : fermer l'onglet termine le fil.