Votre site remplit les User Channel Variables que le widget transmet à votre chatbot : un email, un numéro client, un numéro de commande. Comme elles sont écrites dans la page, un visiteur peut les modifier dans son navigateur avant qu'elles n'arrivent au chatbot. Rien dans email=jane@exemple.fr ne distingue une vraie valeur d'une valeur modifiée.

Quand votre chatbot s'appuie sur ces variables pour identifier le visiteur ou pour appeler vos API en son nom, vous pouvez exiger une signature sur les variables de votre choix. Votre serveur calcule la signature à partir de la valeur et d'une clé secrète partagée avec ViaSay, et votre page l'envoie à côté de la valeur. ViaSay la vérifie à chaque message : une valeur qui ne correspond pas n'arrive jamais jusqu'à votre chatbot.

📘 Où la trouver

La signature est disponible sur les canaux widget. Allez dans Integrate → Channels, ouvrez votre widget, puis l'onglet Security. L'onglet est visible par les utilisateurs qui ont le rôle Manager ou Platform Administrator.

Quand sécuriser une variable

Sécurisez toute variable à laquelle votre chatbot fait confiance :

• Identité : un email, un numéro client ou un numéro de téléphone qui sert à reconnaître le visiteur.

• Paramètres d'API : un identifiant transmis à un appel d'API pour récupérer des commandes, des réservations ou des informations de compte.

• Handover : un email ou un numéro de téléphone qui sert à retrouver le compte du client quand la conversation passe à un agent.

Une variable qui sert seulement à personnaliser la conversation, comme la catégorie de la page ou le produit consulté, n'a pas besoin de signature : une valeur modifiée ne change que ce que voit le visiteur.

Ce que votre page envoie

Chaque variable sécurisée est accompagnée d'un attribut supplémentaire qui porte le même nom suivi de _signature. Ici, la page envoie un email signé :

<script>
  var widget = document.createElement("destygo-webchat");
  widget.setAttribute('token', "<your channel token>");
  widget.setAttribute('email', "jane@exemple.fr");
  widget.setAttribute('email_signature', "77e12a4f8d86c8feae63e2cfcd8290876fbfc8c3884ef5dc946831a4f68fdabb");
  document.body.appendChild(widget);
</script>

La signature est le HMAC-SHA256 de la valeur, calculé avec la clé secrète partagée et écrit en hexadécimal minuscule. Les attributs _signature ne servent qu'à la vérification : ils n'arrivent jamais jusqu'à votre chatbot, vos analytics ou vos historiques de conversation.

Votre page continue d'envoyer les variables exactement comme avant. Le seul ajout est une ligne _signature par variable sécurisée.

Calculer la signature sur votre serveur

Votre serveur sait déjà qui est connecté : il calcule la signature au moment où il génère la page, avec la clé que vous enregistrez dans l'onglet Security.

Node.js

const crypto = require('crypto');

// The key saved in the Security tab, read from your server's configuration.
const SECRET = process.env.VIASAY_SIGNATURE_SECRET;

function sign(value) {
  return crypto.createHmac('sha256', SECRET).update(value, 'utf8').digest('hex');
}

sign('jane@exemple.fr'); // 77e12a4f8d86c8feae63e2cfcd8290876fbfc8c3884ef5dc946831a4f68fdabb

Python

import hashlib
import hmac
import os

# The key saved in the Security tab, read from your server's configuration.
SECRET = os.environ["VIASAY_SIGNATURE_SECRET"]

def sign(value: str) -> str:
    return hmac.new(SECRET.encode("utf-8"), value.encode("utf-8"), hashlib.sha256).hexdigest()

sign("jane@exemple.fr")  # 77e12a4f8d86c8feae63e2cfcd8290876fbfc8c3884ef5dc946831a4f68fdabb

PHP

<?php
// The key saved in the Security tab, read from your server's configuration.
$secret = getenv('VIASAY_SIGNATURE_SECRET');

function sign(string $value, string $secret): string {
    return hash_hmac('sha256', $value, $secret);
}

sign('jane@exemple.fr', $secret); // 77e12a4f8d86c8feae63e2cfcd8290876fbfc8c3884ef5dc946831a4f68fdabb

Java

import java.nio.charset.StandardCharsets;
import java.util.HexFormat;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;

public final class ViaSaySignature {
    // The key saved in the Security tab, read from your server's configuration.
    private static final String SECRET = System.getenv("VIASAY_SIGNATURE_SECRET");

    // sign("jane@exemple.fr") returns 77e12a4f8d86c8feae63e2cfcd8290876fbfc8c3884ef5dc946831a4f68fdabb
    public static String sign(String value) throws Exception {
        Mac mac = Mac.getInstance("HmacSHA256");
        mac.init(new SecretKeySpec(SECRET.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
        return HexFormat.of().formatHex(mac.doFinal(value.getBytes(StandardCharsets.UTF_8)));
    }
}

Pour vérifier votre implémentation, utilisez ce couple de test. Votre code doit produire exactement la signature attendue :

🚧 Quatre règles

• Calculez la signature sur votre serveur, jamais dans le navigateur. Une clé écrite dans le JavaScript de votre page peut être lue par n'importe qui, et ne protège alors plus rien.

• Signez exactement la chaîne que vous envoyez, majuscules et espaces compris : Jane@Exemple.fr et jane@exemple.fr n'ont pas la même signature. Signez la valeur brute, avant tout échappement HTML ou JavaScript.

• Utilisez la clé telle quelle, comme du texte. Ne la décodez pas depuis l'hexadécimal ou le Base64, même si elle ressemble à de l'hexadécimal : une clé générée s'utilise caractère par caractère.

• Utilisez une clé aléatoire d'au moins 32 caractères, réservée à cette intégration. Le bouton Generate en crée une pour vous.

Configurer l'onglet Security

L'onglet Security vous guide en quatre étapes. Tout ce que vous enregistrez aux étapes 1 à 3 est un brouillon : vos visiteurs ne sont vérifiés qu'une fois la configuration publiée, vous pouvez donc préparer et tester à votre rythme.

Étape 1 : enregistrer une clé secrète partagée

Collez la clé que votre serveur utilisera, ou cliquez sur Generate pour en créer une au hasard. Une clé générée s'affiche en clair avec un bouton de copie : copiez-la tout de suite sur votre serveur, car elle n'est plus jamais affichée une fois enregistrée. Cliquez ensuite sur Save key.

La clé est stockée chiffrée et n'est plus jamais affichée : l'onglet indique seulement qu'une clé existe. Une clé qui vient d'être enregistrée apparaît comme New key, en attente de publication : elle ne s'applique qu'au moment où vous publiez.

Étape 2 : choisir les variables à sécuriser

Cliquez sur Add a variable et choisissez les variables que votre page signe. Seules les User Channel Variables sont proposées : si celle dont vous avez besoin n'existe pas encore, créez-la d'abord. Vos choix sont enregistrés au fur et à mesure.

Quelques règles s'appliquent aux noms des variables sécurisées :

• 50 variables au maximum par widget.

• Un nom ne peut pas se terminer par _signature : sécurisez email, et votre page envoie email_signature.

• Les noms réservés par le widget, comme token ou id, ne peuvent pas être sécurisés.

Étape 3 : vérifier vos signatures

Avant de publier, vérifiez que ce que produit votre serveur correspond à ce qu'attend ViaSay. Trois façons de tester, de la plus rapide à la plus complète :

Cliquez sur Run test. Le résultat vous indique, variable par variable, ce que ViaSay conclurait sur un vrai message.

Quand une variable échoue, le résultat indique pourquoi et quoi corriger :

Étape 4 : publier

Une fois le test réussi, cliquez sur Publish en haut à droite de la page du canal. Le bandeau en haut de l'onglet vous indique où vous en êtes dans la configuration.

Publish reste bloqué tant que votre dernière modification n'a pas passé un test. Si vous changez la clé ou les variables après un test, relancez-en un.

Après la publication, l'étape 4 indique que les signatures sont exigées pour vos visiteurs, depuis quand, et sur quelles variables :

Ce qui se passe à chaque message

Une fois la configuration publiée, chaque message du widget est vérifié, et votre chatbot détient toujours ce que votre page certifie à cet instant :

👍 Prévoyez le cas vide dans vos parcours

Une variable sécurisée peut arriver vide à tout moment. Avant de l'utiliser, par exemple dans un appel d'API, assurez-vous qu'elle contient une valeur, et prévoyez un autre chemin quand elle est vide : demander au visiteur de se connecter, ou continuer sans son compte.

Au handover

Quand la conversation passe à un agent via Freshchat ou ViaFlow, seul un email, un numéro de téléphone ou un identifiant de contact arrivé avec une signature valide sert à retrouver le compte du client. Une valeur que le visiteur a tapée dans la conversation ou modifiée dans la page n'est jamais rattachée à un compte existant : personne ne peut ouvrir la fiche d'un autre client en tapant son email.

Changer de clé

Changez de clé régulièrement, ou immédiatement si elle a pu être exposée. L'ancienne clé reste acceptée après la publication : vos serveurs peuvent passer à la nouvelle clé sans interrompre vos visiteurs.

1. Cliquez sur Replace key, collez ou générez la nouvelle clé, puis enregistrez-la. Elle apparaît comme New key, en attente de publication. Vos visiteurs sont toujours vérifiés avec la clé actuelle.

2. Lancez un test avec la nouvelle clé à l'étape 3.

3. Publiez. La nouvelle clé devient la clé actuelle, et l'ancienne devient la Previous key : les deux sont acceptées.

4. Mettez à jour vos serveurs pour qu'ils signent avec la nouvelle clé.

5. Une fois que toutes vos pages signent avec la nouvelle clé, cliquez sur Remove à côté de la clé précédente.

🚧 Changez vos serveurs après la publication, pas avant

Tant que vous n'avez pas publié, seule la clé actuelle est acceptée : une page signée avec la nouvelle clé rendrait ses visiteurs anonymes. Si l'ancienne clé a été exposée, publiez tout de suite et supprimez la clé précédente dès que vos serveurs utilisent la nouvelle.

Changer les variables sécurisées

Vous pouvez ajouter ou retirer des variables sécurisées à tout moment. Tant que vous n'avez pas publié, la modification reste un brouillon : vos visiteurs sont toujours vérifiés avec les variables publiées. Lancez un test, puis publiez pour l'appliquer.

Arrêter la vérification des signatures

Cliquez sur Stop enforcing à l'étape 4. Les signatures cessent d'être vérifiées immédiatement, et les variables envoyées par votre page sont de nouveau acceptées sans signature. Votre clé et vos variables sont conservées : vous pouvez republier à tout moment sans rien ressaisir.

Dépannage

Un visiteur connecté est traité comme anonyme. Vérifiez que chaque page qui charge le widget pour un visiteur connecté envoie bien les valeurs signées. Une page qui charge le widget sans elles rend le visiteur anonyme dès le message suivant.

Le test indique « Signature does not match ». Comparez avec le couple de test ci-dessus : si votre code ne produit pas 77e12a4f…68fdabb, c'est le code de signature qui est en cause. Sinon, vérifiez que votre serveur utilise la clé enregistrée à l'étape 1, et qu'il signe la valeur exactement comme la page l'envoie.

Publish est grisé. Votre dernière modification n'a pas encore passé de test. Lancez un test à l'étape 3.

Ne mettez pas en cache les pages qui contiennent une signature. Une signature prouve à qui appartient la valeur : une page en cache servie à un autre visiteur lui donnerait l'identité du premier.