Widget web

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 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://askais.com/widget.js"
  data-app-id="YOUR_APP_ID"
  data-base-url="https://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 askais.com.

⚠️ Chargez widget.js depuis askais.com

Ne téléchargez pas widget.js et ne l’intégrez pas à votre propre code. Chargé depuis 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://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://askais.com/widget.js"
  data-app-id="YOUR_APP_ID"
  data-base-url="https://askais.com"
  data-external-id="user_123"
  data-email="ada@example.com"
  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. La renouveler rend invalides toutes les anciennes signatures.
• Envoyez toujours data-external-id avec data-hmac. La signature est vérifiée par rapport à l’ID externe : une signature calculée sur l’e-mail seul est rejetée.
• Avec une mauvaise signature, le widget ne peut pas se connecter. Sans data-hmac, les informations sont acceptées telles que la page les fournit : toute personne capable de modifier la page pourrait se faire passer pour quelqu’un d’autre.

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://askais.com/widget.js"></script>
<script>
  window.SingChat.start({
    appId: "YOUR_APP_ID",
    baseUrl: "https://askais.com",
    // optional, for a signed-in user:
    externalId: "user_123",
    email: "ada@example.com",
    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.