SDK JavaScript : piloter le widget de chat depuis votre page

Le script d'intégration ajoute window.IntoChat à votre page. Grâce à lui, votre propre JavaScript peut ouvrir et fermer la bulle de chat, indiquer à l'agent qui est le visiteur connecté, changer la langue du widget et réagir à ce qui se passe dans le chat.

Avant de commencer

Le SDK est fourni avec la balise script. Il n'y a rien d'autre à installer :

<script src="https://www.intochat.ai/api/embed.js" data-chatbot-id="YOUR_AGENT_ID"></script>
<script>
  window.IntoChat.on("reply", function (event) {
    console.log("The agent replied:", event.text);
  });
</script>

window.IntoChat existe dès que le script s'est exécuté, avant même le chargement de la fenêtre de chat. Les appels faits tôt attendent que la bulle et la fenêtre de chat soient prêtes : vous pouvez donc appeler n'importe quelle méthode juste après le snippet.

Le SDK ne fonctionne qu'avec la bulle de chat ajoutée par le script. Une iframe dans la page ou un lien direct n'a aucun script sur la page avec lequel communiquer.

Méthodes

open, close et toggle

<button type="button" onclick="IntoChat.open()">Chat with us</button>

Ouvrir le chat de cette façon compte comme une utilisation du chat par le visiteur : les messages d'accueil au-dessus de la bulle et l'ouverture automatique ne s'affichent donc plus ensuite pendant cette visite.

IntoChat.open() fonctionne aussi pour les visiteurs qui ne voient pas la bulle à cause de Afficher le chat à une partie des visiteurs. Ce déploiement progressif ne masque que la bulle et ses invitations : un bouton « Discutez avec nous » sur votre page ouvre donc toujours le chat pour tout le monde. Pour ces visiteurs, la fenêtre de chat se charge à sa première ouverture. Avec Center Stage, open() ouvre la fenêtre centrée, et close() la ferme comme la touche Échap.

identify

IntoChat.identify({
  userId: "4711",                  // required: the user's id on your site
  userHash: "9f2c…",               // required: computed on your server
  name: "Ada Lovelace",            // optional
  email: "ada@example.com",        // optional
  metadata: { plan: "pro", seats: 3 } // optional
});

identify est le mécanisme de la vérification d'identité. userHash est le HMAC-SHA256 de userId, avec le secret d'identité de votre agent comme clé, calculé sur votre serveur : personne ne peut donc se faire passer pour un autre utilisateur. Sans userHash valide, le visiteur reste simplement non vérifié.

identify renvoie true quand les données respectent ces règles, et false (avec un avertissement dans la console du navigateur) dans le cas contraire. La validité de la signature n'est vérifiée que par le serveur d'intoCHAT, quand le visiteur envoie un message.

Appelez identify à chaque chargement de page tant que le visiteur est connecté. Identifier un autre utilisateur que le dernier sur ce navigateur démarre automatiquement un nouveau chat : une personne ne voit donc jamais la conversation d'une autre. Un visiteur qui a discuté avant de se connecter garde ce chat.

reset

IntoChat.reset();

Appelez-la quand le visiteur se déconnecte. Elle oublie l'identité et démarre un nouveau chat vide. La liste des chats précédents sur ce navigateur est aussi vidée ; les conversations elles-mêmes restent dans votre tableau de bord.

setLanguage

IntoChat.setLanguage("de");

Affiche les textes propres au widget (boutons, libellés, avis) en anglais (en), allemand (de), français (fr), italien (it) ou espagnol (es). Un code régional comme de-CH compte comme de. Tout autre code renvoie false. Elle remplace l'attribut lang de votre page : elle n'a donc aucun effet si vous avez choisi une langue de widget fixe dans l'onglet Appearance. Elle ne change ni vos messages d'accueil ni la langue dans laquelle l'agent répond.

on et off

function onReply(event) {
  analytics.track("chat_reply", { agent: event.chatbotId });
}

IntoChat.on("reply", onReply);
// later
IntoChat.off("reply", onReply);

on renvoie aussi une fonction qui retire l'écouteur. Un écouteur qui lève une erreur n'empêche pas les autres de s'exécuter ; l'erreur est consignée dans la console.

Événements

Chaque callback reçoit un objet. Il contient toujours chatbotId, l'agent d'où vient l'événement.

IntoChat.on("live_chat", function (event) {
  if (event.status === "active") document.title = "A team member is chatting with you";
});

Les événements lead et booking ne se déclenchent pas dans un chat temporaire, car ces fonctions n'y sont pas proposées. Des coordonnées que le visiteur saisit dans le chat, au lieu d'utiliser le formulaire, ne déclenchent pas lead.

Appeler le SDK avant le chargement du script

Si votre code peut s'exécuter avant le snippet, ajoutez les appels à window.IntoChatQueue. Chaque entrée est le nom de la méthode suivi de ses arguments :

<script>
  window.IntoChatQueue = window.IntoChatQueue || [];
  window.IntoChatQueue.push(["identify", { userId: "4711", userHash: "9f2c…" }]);
  window.IntoChatQueue.push(["on", "lead", function () { console.log("New lead"); }]);
</script>
<script src="https://www.intochat.ai/api/embed.js" data-chatbot-id="YOUR_AGENT_ID"></script>

Le script applique la file à son chargement. Les ajouts ultérieurs s'exécutent immédiatement.

Plusieurs agents sur une même page

Avec les snippets de plusieurs agents sur une même page, chaque appel s'applique à toutes leurs bulles, et le chatbotId de chaque événement indique de quel agent il vient. Chaque agent a son propre secret d'identité : un userHash ne vérifie donc le visiteur que pour l'agent dont le secret l'a signé.

Lien avec IntoChatActions

window.IntoChatActions est distinct et fonctionne exactement comme avant : il exécute les actions côté client quand l'agent les appelle. IntoChat sert à votre propre code pour piloter le widget. Les deux peuvent être utilisés ensemble. Quand le visiteur est vérifié, un gestionnaire d'action côté client le reçoit aussi dans context.user :

IntoChatActions.register("Get_cart", async function (args, context) {
  // context.user: { id, name, email, metadata }, only for a verified visitor
  return { items: window.myStore.cart.items };
});

Sécurité

La fenêtre de chat s'exécute sur le domaine d'intoCHAT. Le script de votre page n'échange des messages qu'avec sa propre fenêtre de chat, et seulement tant que cette fenêtre affiche intoCHAT : les autres frames de votre page ne peuvent ni recevoir l'identité du visiteur, ni envoyer de faux événements, ni déclencher d'actions. Les événements transportent ce que le visiteur a saisi et les réponses de l'agent : traitez-les comme toute autre donnée de visiteur sur votre page.