telmini
Commencer
Parcourir la documentationWidget web
Guides

Widget web

Ajoutez le chat telmini à votre site web avec une seule balise script, identifiez les visiteurs connectés et ajustez son apparence.

Les noms techniques comme window.SingChat font partie du widget et de l’API. Conservez-les tels quels dans votre code.

Le widget web est un seul script, widget.js, servi depuis cs.askais.com. Il ajoute un bouton de chat à vos pages et affiche la fenêtre de chat dans un Shadow DOM : les styles de votre site et ceux du widget restent séparés.

L’ajouter à votre site

Collez ce code avant </body> sur chaque page où le chat doit apparaître. Votre App ID se trouve dans Paramètres → Boîtes de réception.

<script src="https://cs.askais.com/widget.js"
  data-app-id="YOUR_APP_ID"
  data-base-url="https://cs.askais.com"
  async></script>

data-base-url est obligatoire sur votre propre site : sans lui, le widget cherche son serveur sur votre domaine au lieu de cs.askais.com.

⚠️ Chargez widget.js depuis cs.askais.com

Ne téléchargez pas widget.js et ne l’intégrez pas à votre propre code. Chargé depuis cs.askais.com, il exécute toujours la version actuelle ; une copie reste figée et passe à côté de chaque correctif et de chaque nouvelle fonctionnalité.

Attributs du script

Tout se règle avec des attributs data- sur la balise script :

  • data-app-id — Obligatoire. L’App ID de votre boîte de réception.
  • data-base-url — Obligatoire sur votre site. Toujours https://cs.askais.com.
  • data-locale — Facultatif. Impose la langue du widget, par exemple ja ou zh-Hant. Sans cet attribut, le widget suit la langue de l’appareil du visiteur, puis le lang de votre page.
  • data-external-id — Votre ID pour un utilisateur connecté.
  • data-email — L’e-mail de l’utilisateur, affiché à votre équipe.
  • data-name — Le nom de l’utilisateur, affiché à votre équipe.
  • data-avatar-url — Lien vers la photo de profil de l’utilisateur.
  • data-hmac — Signature d’identité, voir plus bas.
  • data-attrs — Informations supplémentaires en JSON, par exemple {"plan":"Pro"}, affichées à votre équipe dans le profil du visiteur. Un JSON invalide est ignoré.

data-embed, data-platform, data-app-version et data-device-model sont définis par la page de chat intégré à l’app. Voir Chat intégré à l’app (WebView).

Visiteurs connectés

Pour un utilisateur connecté, ajoutez ses informations à la balise script. Votre équipe voit à qui elle parle, et le chat suit l’utilisateur sur ses autres appareils :

<script src="https://cs.askais.com/widget.js"
  data-app-id="YOUR_APP_ID"
  data-base-url="https://cs.askais.com"
  data-external-id="user_123"
  data-email="[email protected]"
  data-name="Ada Lovelace"
  data-attrs='{"plan":"Pro"}'
  data-hmac="SIGNATURE_FROM_YOUR_SERVER"
  async></script>

Sans data-external-id, le widget attribue à chaque navigateur son propre ID anonyme, conservé dans le stockage local du navigateur : l’historique du chat survit donc aux rechargements de page dans ce navigateur. Si la boîte de réception a un formulaire de pré-discussion, les visiteurs anonymes le remplissent avant le début du chat.

Identité vérifiée (HMAC)

  • hmac est le HMAC-SHA256 de l’externalId, avec la clé secrète de la boîte de réception comme clé, écrit en hexadécimal minuscule.
  • Calculez-le sur votre serveur. La clé secrète ne va jamais dans une page ou une app.
  • La clé secrète s’affiche une fois à la création de la boîte de réception, puis de nouveau quand vous la renouvelez dans Paramètres → Boîtes de réception (menu ⋮ de la boîte → Renouveler la clé secrète). Utilisez la clé entière, préfixe sk_ compris. La renouveler rend invalides toutes les anciennes signatures.
  • Envoyez toujours data-external-id avec data-hmac, et signez exactement cette valeur. Le widget envoie toujours un ID externe (il en génère un anonyme si vous n’en passez pas) : une signature calculée sur l’e-mail seul ne vérifie donc personne.
  • Une signature fausse ou absente n’empêche jamais la conversation : le visiteur peut toujours vous écrire, mais il est considéré comme non vérifié. Les informations non vérifiées sont acceptées telles que la page les fournit, donc toute personne capable de modifier la page pourrait se faire passer pour quelqu’un d’autre, sauf si vous activez Exiger la vérification d’identité : les visiteurs non vérifiés sont alors traités comme anonymes et ne voient pas leurs conversations précédentes.

Exemple pour Node.js :

import { createHmac } from "node:crypto";

// Runs on your server. INBOX_SECRET_KEY never leaves it.
const hmac = createHmac("sha256", INBOX_SECRET_KEY)
  .update(user.id) // the exact value you pass as data-external-id
  .digest("hex");

Démarrer le widget depuis JavaScript

Pour démarrer le widget vous-même, par exemple une fois que votre page sait qui est l’utilisateur, chargez le script sans data-app-id et appelez window.SingChat.start() une fois qu’il est chargé :

<script src="https://cs.askais.com/widget.js"></script>
<script>
  window.SingChat.start({
    appId: "YOUR_APP_ID",
    baseUrl: "https://cs.askais.com",
    // optional, for a signed-in user:
    externalId: "user_123",
    email: "[email protected]",
    name: "Ada Lovelace",
    hmac: "SIGNATURE_FROM_YOUR_SERVER",
  });
</script>

start() est la seule méthode fournie par le script. Il n’existe aucune méthode pour ouvrir ou fermer le widget, ni pour écouter ses événements ; les visiteurs l’ouvrent depuis le bouton de chat.

Apparence et comportement

  • Paramètres → Boîtes de réception, puis dépliez une boîte de réception : couleur principale et couleur du texte, position (en bas à droite ou en bas à gauche), taille de la bulle, fond clair ou sombre, titre et sous-titre de la fenêtre, avec un aperçu en direct.
  • Formulaire de pré-discussion (au même endroit) : demandez aux visiteurs anonymes leur e-mail, leur nom, leur téléphone ou leur entreprise avant le début du chat.
  • Origines autorisées (au même endroit) : les sites web autorisés à charger le widget de cette boîte de réception. Une liste vide autorise n’importe quel site.
  • Marque du widget (au même endroit) : la ligne « Powered by » en bas du chat. Votre forfait détermine si vous pouvez la masquer ou y afficher votre propre nom.
  • Le message d’accueil de l’IA se règle dans Agent IA, les bulles de FAQ cliquables dans Paramètres → FAQ, et les articles dans Help Center.

Sécurité

  • L’App ID est public : il peut figurer sans risque dans votre HTML.
  • La clé secrète de la boîte de réception doit rester sur votre serveur.
  • Utilisez l’identité vérifiée (HMAC) dès que la page sait qui est l’utilisateur.
  • Limitez les origines autorisées à vos propres domaines pour que le widget ne puisse pas être chargé sur d’autres sites.
PrécédentServeur MCP (agents IA)SuivantBase de connaissances (RAG)