Intégrer un widget sur votre site

Vous pouvez mettre le produit sur votre propre site web avec une <script> tag. Il existe deux widgets, et celui que vous choisissez dépend de la nécessité d’avoir une conversation ou d’exécuter une action spécifique.

	Widget de chat	Widget de workflow
Ce qu’un visiteur obtient	Une conversation avec un assistant	Un workflow, avec ses entrées
Formulaires interactifs	Oui	Non — il affiche uniquement les résultats
Script	chat-widget.js	workflow-widget.js

Les deux sont autonomes : pas de framework sur votre page, pas de feuille de style à inclure, et rien à construire.

Ajouter le widget de chat

<script src="https://app.example.com/chat-widget.js"></script>
<script>
  sapajaChat('init', {
    templateId: 'your-template-id',
    token: 'your-embed-token',
  });
</script>

Vous obtenez l’identifiant du modèle et son jeton à partir de l’espace de travail qui possède le modèle de chat. Le jeton autorise le widget et est lié à une liste de sites qui peuvent l’utiliser — un jeton utilisé depuis un domaine qui n’est pas sur cette liste est refusé, donc un jeton copié ne fonctionne pas ailleurs.

Ce que voient les visiteurs

Les réponses ne sont pas du texte brut. Le widget rend les mêmes surfaces enrichies que le chat intégré à l’application — cartes, tableaux, statistiques, badges, graphiques et images — ainsi un résultat arrive sous une forme lisible plutôt qu’un tas de JSON.

Le widget de chat rend également de véritables formulaires. Lorsque l’assistant a besoin de détails avant de pouvoir exécuter quelque chose, le visiteur obtient des champs avec étiquettes et un bouton de soumission au lieu d’être invité à taper des valeurs dans une phrase. Quelques comportements à connaître :

• Une soumission incomplète revient sous la forme d’un formulaire corrigé, avec les champs manquants marqués, plutôt que par une erreur.
• Si une soumission ne peut pas nous atteindre, le formulaire reste modifiable et propose une nouvelle tentative — il ne reporte jamais faussement le succès.
• Un formulaire soumis reste visible mais gelé, marqué comme soumis, afin que le visiteur puisse voir ce qu’il a envoyé.

Le widget de workflow affiche les résultats mais n’a pas de formulaires ; il collecte ce dont il a besoin à l’avance.

La langue de votre visiteur

Le widget parle la langue de votre visiteur, pas la vôtre. Il détermine laquelle utiliser dans cet ordre : la langue que vous configurez, puis le navigateur du visiteur, puis l’anglais.

sapajaChat('init', { templateId: '…', token: '…', locale: 'fr' });

Supporté : en, fr, es, th, zh et zh-HK. Les balises de navigateur ordinaires fonctionnent — fr-CA devient Français, zh-TW devient Chinois traditionnel. Tout ce qui n’est pas reconnu tombe en anglais plutôt que de faillit.

Cela couvre les propres contrôles du widget et tout ce que l’assistant génère : lignes de statut, messages de complétion, étiquettes de cartes de résultats et les réponses elles-mêmes. Cela s’applique par message, donc un visiteur qui change de langue en plein conversation reçoit la nouvelle à partir de son prochain message. Le contenu déjà envoyé n’est jamais retraduit — une carte de résultat reste dans la langue dans laquelle elle a été créée.

Si une conversation commence un travail de longue durée, la langue suit, donc le message de complétion arrive dans la langue que le visiteur utilisait même si cela se produit des heures plus tard.

Une exception : le texte écrit par qui a créé le workflow — descriptions de champ, invites de clarification et affichages personnalisés — apparaît tel qu’ils l’ont écrit. C’est un contenu authentifié plutôt qu’un contenu produit, donc il n’est pas traduit.

Créer votre propre client à la place

Vous n’êtes pas obligé d’utiliser les widgets. Les points de terminaison d’intégration sont documentés dans la référence de l’API REST, et ils prennent la même valeur locale à chaque appel — envoyez-la et vous obtenez le même comportement, omettez-la et vous obtenez l’anglais.

Si quelque chose n’apparaît pas

• Pas de bouton de microphone. La voix nécessite une connexion sécurisée. Sur une page servie via HTTP en clair, le navigateur ne donnera pas accès au microphone, donc le contrôle n’est pas montré. Servez votre page via HTTPS.
• Un composant ne s’affiche pas. Le widget rend uniquement les types de composants connus et abandonne silencieusement tout le reste, donc un affichage qu’il ne peut pas comprendre est sauté plutôt que montré de manière cassée.
• Le widget cesse de fonctionner. Si l’espace de travail qui possède l’intégration n’a plus d’abonnement actif, le widget décline poliment plutôt que de montrer un message de facturation à vos visiteurs.