Actions côté client dans le navigateur du visiteur

Exécutez une action dans le navigateur du visiteur : un gestionnaire JavaScript enregistré via IntoChatActions ou un appel qui utilise sa session.

Une action côté client s'exécute sur la page où votre agent est intégré, et non sur les serveurs d'intoCHAT. Elle sert à atteindre ce que seul le navigateur du visiteur peut atteindre : un point de terminaison de votre site qui s'appuie sur la session de connexion du visiteur, ou des données et fonctions présentes sur la page.

Quel type choisir

Vous voulez appeler	Utilisez
Une API publique, ou qui exige votre clé secrète	Une action API côté serveur
Un point de terminaison de votre domaine qui utilise les cookies du visiteur	Une action côté client, sans code supplémentaire
Un élément de la page, comme le panier en JavaScript ou une fenêtre à ouvrir	Une action côté client avec un gestionnaire enregistré
Rien : vous voulez seulement que le visiteur ouvre l'une de vos pages	Un bouton personnalisé

Configuration

Dans l'onglet Actions, créez l'action comme décrit dans Actions API personnalisées : URL, entrées et When to use.
À l'étape 3. When the AI should use it, sélectionnez Client-side action.
Enregistrez l'action.

Déroulement d'un appel

Quand l'agent appelle une action côté client, le widget de chat transmet l'appel au script d'intégration de votre page :

Si votre page a enregistré un gestionnaire sous le nom de l'action, il s'exécute et sa valeur de retour est transmise à l'agent.
Sinon, votre page appelle l'URL de l'action depuis votre propre domaine, avec les cookies du visiteur.

Chaque appel dispose de 20 secondes. Au-delà, il est signalé à l'agent comme un échec. L'action a quand même besoin d'une URL publique valide, même si vous n'utilisez qu'un gestionnaire ; si un gestionnaire est enregistré, cette URL n'est pas appelée.

Enregistrer un gestionnaire

Le nom du gestionnaire est le nom de l'action dans lequel tout caractère autre que lettres, chiffres, _ et - est remplacé par _ : « Get cart » devient Get_cart. L'éditeur affiche le nom exact dans son exemple de code.

window.IntoChatActions est disponible dès que le script du snippet s'est exécuté, avant même le chargement du widget de chat. Les gestionnaires sont recherchés au moment où l'agent appelle l'action : les enregistrer avant ou après que le widget est prêt revient au même. Ajoutez un script n'importe où après le snippet :

<script src="https://www.intochat.ai/api/embed.js" data-chatbot-id="YOUR_AGENT_ID"></script>
<script>
  window.IntoChatActions.register("Get_cart", async function (args) {
    // args : les entrées remplies par l'agent.
    // Renvoyez une valeur sérialisable en JSON. L'agent la voit.
    return { items: window.myStore.cart.items };
  });
</script>

Du code susceptible de s'exécuter avant le snippet peut plutôt ajouter des paires [name, handler] à window.IntoChatActionsQueue ; le script d'intégration les enregistre à son chargement. La plupart des pages n'en ont pas besoin. Avec plusieurs agents sur une même page, tous partagent les mêmes gestionnaires.

Le gestionnaire reçoit dans args les entrées remplies par l'agent. S'il lève une erreur, le message est transmis à l'agent comme un appel échoué. IntoChatActions.unregister(name) retire un gestionnaire et IntoChatActions.registered() liste les noms enregistrés.

Tester

Send test request dans l'éditeur s'exécute depuis les serveurs d'intoCHAT. Le test vérifie que l'URL répond et montre la forme de la réponse, mais il ne voit ni les sessions de vos visiteurs ni les gestionnaires de votre page. Dans le Playground, aucune page de votre site n'entoure le chat : le widget appelle donc l'URL lui-même, sans les cookies ni les gestionnaires de votre site. Testez gestionnaires et points de terminaison liés à la session sur une page de votre site où le widget est installé.