Embarquer un widget de chat sur base de connaissances avec lead capture

Transformez votre documentation en assistant sur le pas de la porte

Votre base de connaissances contient déjà les réponses que cherchent vos visiteurs. Un widget de chat embarqué met ces réponses sur votre site web comme porte d'entrée conversationnelle : les visiteurs posent des questions, le widget exécute le même pipeline RAG hybride et la même infrastructure d'agent que vos équipes internes, et les réponses arrivent avec des citations issues des workspaces que vous choisissez d'exposer. Ce tutoriel parcourt l'embed du widget, le contrôle sur ce qu'il répond, la capture des leads et la correcte configuration de CORS - du panneau d'administration à un extrait fonctionnel en quelques minutes.

L'embed en deux étapes : un loader et un iframe sandboxé

Le widget est construit autour d'un pattern d'embed orienté sécurité. Au lieu d'injecter du markup et des styles dans votre page, le widget arrive en deux étapes :

1. Le script loader. Ajoutez une seule balise script au site, pointée vers votre service widget avec l'ID du widget. Le loader est un petit fichier JavaScript qui crée un iframe dans la page hôte.
2. Le panneau iframe. L'iframe charge une application Preact autonome - compilée en bundle IIFE avec CSS inliné - qui dessine le bouton flottant, le panneau de chat et chaque interaction dans son propre document.

<script src="https://votre-simmetric-chat.com/widget/loader.js?widgetId=WIDGET_ID"></script>

Pourquoi un iframe ? Parce que l'interpolation de chaînes de contenu non fiable dans une page hôte est la voie classique du XSS. Faire tourner l'interface du widget dans un iframe sandboxé à origine opaque élimine entièrement cette classe de risque : le contenu du chat n'est jamais exécuté dans le contexte de votre page. Les anciennes routes d'embed par interpolation de chaînes ont été retirées du produit exactement pour cette raison, donc le pattern en deux étapes n'est pas une option parmi d'autres - c'est l'embed.

La communication entre iframe et page passe par un petit protocole postMessage versionné (types de message simmetric:*) qui gère le ballet d'ouverture/fermeture du FAB, le recoloriage du FAB et les handshakes du storage de session. Les deux côtés valident chaque message entrant contre l'exact contentWindow attendu, de sorte que les messages contrefaits entre iframes différents sont ignorés.

Créer le widget et le pointer vers la connaissance

Tout commence dans le panneau d'administration :

1. Créez un widget depuis Paramètres → Widgets. La création est contrainte à la licence (widget_enabled) et respecte la limite numérique de widgets du palier.
2. Rattachez le widget à un ou plusieurs workspaces. La liste blanche des workspaces remplace atomiquement tous les rattachements précédents, donc stratifier l'accès à la base de connaissances est une affaire de quels workspaces attacher.
3. Configurez le branding : couleur primaire, nom du bot, logos, position (en bas à droite ou en bas à gauche). Les déploiements de palier Community reçoivent des valeurs par défaut sensées quand les champs sont vides ; la personnalisation complète et le white-labeling sont des flags enterprise.
4. Copiez l'extrait d'embed dans le HTML de votre site.

Comme les widgets sont définis par workspace, la connaissance à laquelle un widget peut puiser est exactement l'union des bases de connaissances des workspaces rattachés - rien de plus. Un widget de support peut voir le workspace de la documentation publique sans jamais toucher aux données des projets internes.

Le model pin des réponses : résolu côté serveur

Un ajout récent compte pour le contrôle qualité : la configuration de chaque widget peut sélectionner un provider et un modèle LLM spécifiques qui servent les réponses de chat de ce widget. Le pin est conservé sur la ligne du widget et résolu côté serveur à chaque requête de chat - il n'est jamais fourni par le client, par le proxy du widget ou par le navigateur du visiteur. Un modèle épinglé a priorité sur le défaut du workspace, et les widgets sans pin gardent la chaîne de résolution standard. En pratique : votre widget marketing peut tourner sur l'exact modèle que vous avez vérifié pour les réponses publiques, indépendamment de ce que quiconque manipule côté client.

Une capture de leads qui respecte les visiteurs

La capture de leads du widget est conçue pour la réalité d'un formulaire public : les abus se concentrent là où les données sont collectées, donc l'endpoint des leads est volontairement limité à 3 requêtes par heure par source (avec la limite rendue visible à l'utilisateur). Le flux :

• Le visiteur voit une barrière de consentement sur les informations personnelles avant de chatter - une reconnaissance explicite de la façon dont les données sont traitées, pas un lien vers une politique caché en bas de page.
• Une carte lead collecte les coordonnées pendant ou après la conversation, et les envois arrivent dans la boîte des leads du widget dans le panneau d'administration, avec export CSV pour votre pipeline.
• Les sessions sont anonymes par choix de conception : le serveur crée une session avec un token à 256 bits et une expiration de 24 heures, et chaque requête ultérieure est validée contre elle. Les limites par session (20 messages par heure, 5 conversations par jour) renvoient un 429 avec un indice retryAfter en cas de dépassement, et l'interface affiche un avertissement de rate limit plutôt que d'échouer en silence.

Les rate limits font partie de l'histoire de confiance, pas un ajout après coup : une surface de chat publique devrait dégrader gracieusement sous charge ou abus, et le limiteur des leads est la barrière la plus stricte des trois limiteurs côté widget.

CORS : fermé par défaut par conception

Le trafic des widgets traverse les origines par définition, donc CORS fait partie de la surface de sécurité plutôt que d'être un ajout après coup. Chaque widget porte sa propre liste allowedOrigins, modifiable depuis le panneau d'administration. À l'exécution, un middleware CORS dynamique valide l'en-tête Origin de chaque requête contre la liste de ce widget - les requêtes d'origines non autorisées sont rejetées au preflight, et le middleware échoue en mode fermé : si la vérification d'origine ne peut pas consulter la base de données, l'accès est refusé plutôt qu'accordé.

Configurez-le en une seule passe :

• Ajoutez les origines de votre site (schéma et hôte, sans jeux avec la barre oblique finale) aux origines autorisées du widget.
• Rappelez-vous que les variantes de sous-domaine comptent comme des origines distinctes - exemple.com et www.exemple.com sont deux entrées.
• Utilisez des origines https:// en production ; le service widget parle les mêmes règles d'URL que le reste de la stack.

Tout le reste - l'URL du loader, l'iframe, le bootstrap de la session, le stream SSE du chat - utilise le même hôte sur lequel vous déployez le service widget, donc il y a exactement un endroit où la confiance d'origine est décidée : la liste autorisée du widget.

Ce qui tourne où

Une carte d'orientation rapide, parce que le widget touche trois processus :

• Serveur principal - CRUD et branding des widgets, rattachement des workspaces, l'API interne que le service widget appelle avec sa clé API, et endpoints lead/analytics pour les administrateurs. Tout le routeur interne renvoie 402 quand la fonctionnalité widget est éteinte.
• Service widget - la surface publique d'embed : loader JS, HTML de l'iframe, création des sessions, livraison de la configuration en cache, le proxy SSE du chat vers le serveur principal et l'endpoint des leads. Il s'authentifie auprès du serveur principal avec une WIDGET_API_KEY et porte ses propres limiteurs de fréquence.
• L'iframe - le client Preact IIFE avec le cycle de vie du chat : création de la session, streaming SSE token par token, affichage des citations, questions suggérées et barrières de consentement.

Le proxy du chat relaie le même format d'événements que l'API de streaming interne - messages d'état, annonces de plan, tokens en streaming, citations et événements terminaux done/error - pour que tout ce que votre équipe voit dans un chat de workspace, vos visiteurs l'expérimentent dans le widget.

Checklist de lancement

• Widget créé, fonctionnalité de licence active, workspaces rattachés
• Branding configuré ; flag white-label si le widget ne doit pas porter la marque du produit
• Model pin des réponses défini sur la ligne du widget (résolu côté serveur)
• Origines autorisées couvrant chaque site et sous-domaine qui l'embarquera
• Lead capture vérifié de bout en bout : barrière de consentement, envoi, boîte admin, export CSV
• Rate limits compris : 3 leads par heure, 20 messages par heure par session, 5 conversations par jour

À partir de là, le widget est un drop-in : une balise script, une liste autorisée, une base de connaissances à laquelle vous vous fiez déjà. Quand vos visiteurs posent des questions, ils obtiennent des réponses fondées exactement sur les workspaces que vous avez choisis - avec une pipeline de lead capture qui est courtoise avec les humains et sévère avec les bots.

Lire le guide complet dans la doc →