Guide · développeurs

Données personnelles pour les visiteurs connectés

Laissez votre assistant répondre à des questions comme "pour quoi ai-je réservé ?" ou "quel est le statut de ma commande ?" — en interrogeant votre propre API au nom du visiteur connecté sur votre site.

L'approche est volontairement simple et sûre : votre site web indique au chatbot qui est connecté, mais de manière signée, de sorte qu'un visiteur ne puisse jamais se faire passer pour un autre. Vous avez tout cela en place en un quart d'heure.

Étape 1 — Activez la vérification et générez un secret

Ouvrez votre bot dans le portail, allez dans l'onglet Actions et activez "Données personnelles des visiteurs connectés". Cliquez sur Générer pour obtenir un secret partagé et enregistrez.

• Conservez le secret comme un mot de passe — dans une variable d'environnement ou votre coffre à secrets, jamais dans votre code front-end.
• Vous soupçonnez qu'il a fuité ? Générez un nouveau secret ; les anciennes signatures deviennent alors immédiatement invalides.

Étape 2 — Calculez la signature sur votre serveur

Pour le visiteur connecté, calculez HMAC-SHA256(secret, identifiant-utilisateur) et transmettez le résultat sous forme de texte hexadécimal. Cela se fait toujours côté serveur — le secret ne doit pas entrer dans le navigateur.

<?php
// Le secret est en sécurité sur votre serveur (depuis le portail). Jamais dans le navigateur.
$secret   = getenv('CODEBROUWERIJ_CHATBOT_SECRET');
$userId   = (string) $currentUser->id;

// Signez l'identifiant utilisateur.
$userHash = hash_hmac('sha256', $userId, $secret);
?>
<script src="https://aqivo.chat/embed.js"
        data-bot-id="JOUW-BOT-ID"
        data-user-id="<?= htmlspecialchars($userId) ?>"
        data-user-hash="<?= $userHash ?>"
        data-user-email="<?= htmlspecialchars($currentUser->email) ?>"
        async></script>

const crypto = require('crypto');

// Côté serveur, sur votre route connectée :
const secret   = process.env.CODEBROUWERIJ_CHATBOT_SECRET;
const userId   = String(req.user.id);
const userHash = crypto.createHmac('sha256', secret).update(userId).digest('hex');

// Transmettez userId + userHash à votre vue et rendez-y :
// <script src="https://aqivo.chat/embed.js"
//   data-bot-id="JOUW-BOT-ID"
//   data-user-id="${userId}" data-user-hash="${userHash}" async></script>

@using System.Security.Cryptography
@using System.Text
@{
    var secret   = Configuration["CodebrouwerijChatbot:Secret"];
    var userId   = User.FindFirstValue(ClaimTypes.NameIdentifier);

    using var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(secret));
    var userHash   = Convert.ToHexString(
        hmac.ComputeHash(Encoding.UTF8.GetBytes(userId))).ToLowerInvariant();
}
<script src="https://aqivo.chat/embed.js"
        data-bot-id="JOUW-BOT-ID"
        data-user-id="@userId"
        data-user-hash="@userHash"
        async></script>

import hmac, hashlib
from django.conf import settings

# Par ex. comme context-processor ou dans votre vue :
def chatbot_context(request):
    secret    = settings.CODEBROUWERIJ_CHATBOT_SECRET.encode()
    user_id   = str(request.user.id)
    user_hash = hmac.new(secret, user_id.encode(), hashlib.sha256).hexdigest()
    return {"cb_user_id": user_id, "cb_user_hash": user_hash}

# Dans votre template :
# <script src="https://aqivo.chat/embed.js"
#   data-bot-id="JOUW-BOT-ID"
//   data-user-id="{{ cb_user_id }}" data-user-hash="{{ cb_user_hash }}" async></script>

0e5cda9a37bbbac18483cc531c37c0fcd29ad35ba29fe5f1a120979a3d7ead8f

Étape 3 — Placez le widget sur vos pages connectées

Sur les pages où le visiteur est connecté, vous rendez le widget avec data-user-id et data-user-hash. Sur les pages publiques, vous omettez simplement ces attributs — là, le chatbot fonctionne de manière anonyme.

• data-user-id — l'identifiant utilisateur issu de votre système (il est vérifié).
• data-user-hash — la signature de l'étape 2.
• data-user-email / data-user-name — facultatif, purement à titre informatif pour un accueil personnalisé.

Étape 4 — Configurez une action

Dans le portail (onglet Actions), ajoutez une action, par exemple get_reservations. Vous indiquez à l'assistant ce que fait l'action et quelle API il peut appeler. Dans l'URL, les en-têtes ou le corps, vous utilisez des espaces réservés que nous remplissons côté serveur à partir du visiteur vérifié :

• {{user.id}} — l'identifiant utilisateur vérifié
• {{user.email}} — l'adresse e-mail, si elle est fournie
• {{user.token}} — un éventuel token transmis (voir ci-dessous)
• {{naam}} — un paramètre que l'assistant remplit lui-même (par ex. un numéro de commande)

Un exemple d'URL pour "mes réservations" :

https://jouwsite.nl/api/me/reservations?uid={{user.id}}

Important : votre API doit elle-même vérifier que les données demandées appartiennent VRAIMENT à cet utilisateur. Nous fournissons l'identité vérifiée ; l'autorisation reste de votre côté — ainsi, c'est doublement verrouillé.

Alternative : transmettre un token

Vous préférez transmettre un token existant (par exemple un JWT à courte durée de vie que votre API peut déjà valider) ? Placez alors data-user-token sur le widget. Nous transmettons ce token à votre API (par exemple sous la forme Authorization: Bearer {{user.token}}), qui en déduit elle-même l'utilisateur. Utilisez une courte durée de vie et la bonne audience.

La sécurité en bref

• Le secret reste uniquement sur votre serveur. Ne le mettez jamais dans du HTML, du JavaScript ou un dépôt public.
• La signature est calculée par visiteur côté serveur — pas dans le navigateur.
• Nous comparons la signature en temps constant et nous refusons les actions personnelles dès qu'elle est incorrecte ou absente.
• Les actions s'exécutent sur notre serveur avec un court délai d'expiration et un blocage des adresses internes ; vos clés d'API restent hors de portée du visiteur.
• Les actions personnelles sont disponibles à partir de l'abonnement Crew.