Intégrer le widget webchat

Utilisez ce guide pour ajouter le widget de chat nAIxus à un site web. Le widget s'affiche dans une bulle flottante, isolée du reste de la page (Shadow DOM), et converse avec le flow lié à un canal Webchat.

Résultat attendu : la bulle de chat apparaît sur votre site, les messages des visiteurs exécutent le flow, et le flow reçoit le contexte de la page.

Avant de commencer

• Un canal Webchat créé dans la console et sélectionné dans le nœud Channel Trigger d'un flow.
• La clé publique du canal (nx_pub_…). Elle est conçue pour être visible dans la page : elle n'identifie que le canal.
• Les origines autorisées du canal incluent chaque origine où le widget s'affiche (https://www.example.com, ou un motif à joker comme https://*.example.com). Depuis une origine absente de la liste, le widget reçoit 403 et ne se charge pas.
• Deux adresses fournies par l'exploitant de votre plateforme nAIxus :
  • l'hôte du widget, qui sert le fichier widget.js ;
  • l'origine de l'API Core, qui reçoit les requêtes du widget.

Étape 1 - Ajouter le script

Collez ce code juste avant la balise </body> des pages concernées :

<script src="https://<hôte-du-widget>/widget.js"></script>
<script>
  window.Naixus.init({
    widgetId: 'nx_pub_xxxxxxxx',
    apiUrl: 'https://<origine-api-core>',
  });
</script>

• widgetId est la clé publique du canal.
• apiUrl est obligatoire : sans lui, le widget vise une adresse par défaut qui ne correspond pas à votre déploiement, et le suivi du livechat en temps réel ne fonctionne pas.

La page de configuration du canal (onglet Web Chat de la console) affiche ce même extrait dans son panneau d'aide, mais avec une clé et des adresses à remplacer : la console ne génère pas encore cet extrait pré-rempli avec vos vraies valeurs.

Étape 2 - Autoriser le widget dans votre CSP

Si votre site définit une Content Security Policy, autorisez au minimum :

Étape 3 - Ajuster l'affichage (optionnel)

window.Naixus.init accepte aussi :

Le thème, les textes (i18n), les fonctionnalités et les suggestions de départ se configurent sur le canal dans la console ; ces réglages l'emportent sur les valeurs passées à init.

Le script expose aussi window.Naixus.open(), window.Naixus.close() et window.Naixus.destroy() pour piloter le widget depuis votre page, par exemple depuis un bouton « Contactez-nous ».

Étape 4 - Transmettre le contexte de la page

À chaque message, le widget envoie l'URL, le titre, le référent et la langue de la page. Le flow les reçoit sans configuration : {{page_url}}, {{page_title}}, {{page_referrer}}, {{page_locale}}.

Pour transmettre vos propres valeurs (offre, identifiant de panier, utilisateur connecté…) :

1. Dans la console, déclarez-les dans les variables de contexte du canal.

2. Passez-les dans metadata :

   <script>
     window.Naixus.init({
       widgetId: 'nx_pub_xxxxxxxx',
       apiUrl: 'https://<origine-api-core>',
       metadata: { plan: 'pro', cart_id: '48219' },
     });
   </script>

Chaque variable déclarée devient une variable de flow ({{plan}}, {{cart_id}}). Les clés non déclarées sont ignorées, une valeur invalide fait ignorer tout l'objet, et metadata est limité à 50 clés par message.

Le navigateur ne peut jamais écraser les clés réservées à l'exécution : user_message, channel_id, channel_type, session_id, conversation_id, origin, messages, user_metadata, payload, channel, flow_version, ni le nom du champ fichier du canal (docs par défaut). Évitez ces noms pour vos variables de contexte : la console les accepte à la déclaration, mais ils sont ensuite ignorés silencieusement à l'exécution, sans avertissement. Ces valeurs viennent du navigateur : ne les utilisez pas comme preuve d'identité.

Étape 5 - Vérifier l'intégration

1. Ouvrez la page : la bulle apparaît dans le coin choisi.
2. Envoyez un message : la réponse du flow s'affiche progressivement.
3. Rechargez la page : la conversation est conservée.
4. En cas d'échec, ouvrez la console du navigateur :
   • 403 sur /public/widget/config : l'origine de la page n'est pas dans les origines autorisées du canal ;
   • erreur CORS ou CSP : voir l'étape 2 ;
   • 400 No flow configured for this channel : aucun Channel Trigger ne sélectionne le canal ;
   • 429 : la limite de débit de la clé est atteinte (voir ci-dessous).

À savoir avant la mise en production

• Stockage local. Le widget conserve un identifiant de session aléatoire dans le localStorage du navigateur (clé naixus_session_<clé>) pour retrouver la conversation après un rechargement. Intégrez-le à votre politique de consentement si nécessaire. L'action « nouvelle conversation » en génère un nouveau.
• Limites du canal et par IP. Tous les visiteurs partagent la limite du canal Webchat (3000 requêtes par minute par défaut). Les requêtes publiques ont aussi une limite par IP (60 par minute par défaut) ; l'exploitant peut modifier les deux dans la section Limites du canal. Une limite préliminaire par IP protège également les routes publiques.
• Pièces jointes. Si l'envoi de fichiers est activé sur le canal, le widget affiche un sélecteur et applique les limites du canal ; les fichiers sont exposés au flow sous le nom de champ configuré ({{docs}} par défaut).
• Livechat. Lorsqu'un flow transfère la conversation à un conseiller, le widget passe automatiquement en livechat et signale la présence du visiteur, sans intégration supplémentaire.
• Nœud Question. Les questions posées par le flow s'affichent dans le widget, avec leurs suggestions éventuelles ; la réponse du visiteur reprend l'exécution.
• Fichiers générés. Le widget ne permet pas encore de télécharger un fichier produit par le flow, comme une présentation Create PPTX.

Référence

Pour les routes appelées par le widget et leurs erreurs, voir la référence de l'API du widget.