Handleiding · ontwikkelaars

Persoonlijke data voor ingelogde bezoekers

Laat je assistent vragen beantwoorden als "waarvoor heb ik gereserveerd?" of "wat is de status van mijn bestelling?" — door je eigen API te bevragen namens de bezoeker die op jouw site is ingelogd.

De aanpak is bewust simpel én veilig: je website vertelt de chatbot wie er is ingelogd, maar wel ondertekend, zodat een bezoeker zich nooit voor een ander kan uitgeven. Je hebt dit in een kwartiertje staan.

Stap 1 — Zet verificatie aan en genereer een geheim

Open je bot in de portal, ga naar de tab Acties en zet "Persoonlijke data van ingelogde bezoekers" aan. Klik op Genereer voor een gedeeld geheim en sla op.

• Bewaar het geheim als een wachtwoord — in een omgevingsvariabele of je secrets-store, nooit in je front-endcode.
• Vermoed je dat het is uitgelekt? Genereer een nieuw geheim; de oude handtekeningen worden dan direct ongeldig.

Stap 2 — Bereken de handtekening op je server

Bereken voor de ingelogde bezoeker HMAC-SHA256(geheim, gebruikers-id) en geef het resultaat als hexadecimale tekst door. Dit gebeurt altijd server-side — het geheim mag de browser niet in.

<?php
// Het geheim staat veilig op je server (uit de portal). Nooit in de browser.
$secret   = getenv('SUPERBOLD_CHATBOT_SECRET');
$userId   = (string) $currentUser->id;

// Onderteken de gebruikers-id.
$userHash = hash_hmac('sha256', $userId, $secret);
?>
<script src="https://chatbot.superbold.nl/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');

// Server-side, op je ingelogde route:
const secret   = process.env.SUPERBOLD_CHATBOT_SECRET;
const userId   = String(req.user.id);
const userHash = crypto.createHmac('sha256', secret).update(userId).digest('hex');

// Geef userId + userHash door aan je view en render daar:
// <script src="https://chatbot.superbold.nl/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["SuperBoldChatbot: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://chatbot.superbold.nl/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

# Bijv. als context-processor of in je view:
def chatbot_context(request):
    secret    = settings.SUPERBOLD_CHATBOT_SECRET.encode()
    user_id   = str(request.user.id)
    user_hash = hmac.new(secret, user_id.encode(), hashlib.sha256).hexdigest()
    return {"sb_user_id": user_id, "sb_user_hash": user_hash}

# In je template:
# <script src="https://chatbot.superbold.nl/embed.js"
#   data-bot-id="JOUW-BOT-ID"
#   data-user-id="{{ sb_user_id }}" data-user-hash="{{ sb_user_hash }}" async></script>

0e5cda9a37bbbac18483cc531c37c0fcd29ad35ba29fe5f1a120979a3d7ead8f

Stap 3 — Plaats de widget op je ingelogde pagina's

Op pagina's waar de bezoeker is ingelogd, render je de widget met data-user-id en data-user-hash. Op publieke pagina's laat je die attributen gewoon weg — daar werkt de chatbot anoniem.

• data-user-id — de gebruikers-id uit jouw systeem (wordt geverifieerd).
• data-user-hash — de handtekening uit stap 2.
• data-user-email / data-user-name — optioneel, puur ter info voor een persoonlijke begroeting.

Stap 4 — Configureer een actie

Voeg in de portal (tab Acties) een actie toe, bijvoorbeeld get_reservations. Je vertelt de assistent wat de actie doet en welke API hij mag aanroepen. In de URL, headers of body gebruik je plaatshouders die wij server-side invullen vanuit de geverifieerde bezoeker:

• {{user.id}} — de geverifieerde gebruikers-id
• {{user.email}} — het e-mailadres, indien meegegeven
• {{user.token}} — een eventueel doorgegeven token (zie hieronder)
• {{naam}} — een parameter die de assistent zelf invult (bv. een bestelnummer)

Een voorbeeld-URL voor "mijn reserveringen":

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

Belangrijk: jouw API moet zelf controleren dat de opgevraagde gegevens écht bij deze gebruiker horen. Wij leveren de geverifieerde identiteit aan; de autorisatie blijft bij jou — zo zit het dubbel op slot.

Alternatief: een token doorgeven

Geef je liever een bestaand token mee (bijvoorbeeld een kort-levende JWT die je API al kan valideren)? Zet dan data-user-token op de widget. Wij sturen dat token mee naar je API (bijvoorbeeld als Authorization: Bearer {{user.token}}), die er zelf de gebruiker uit afleidt. Gebruik korte levensduur en de juiste audience.

Beveiliging in het kort

• Het geheim staat alleen op je server. Zet het nooit in HTML, JavaScript of een publieke repo.
• De handtekening wordt per bezoeker server-side berekend — niet in de browser.
• Wij vergelijken de handtekening in constante tijd en weigeren persoonlijke acties zodra die niet klopt of ontbreekt.
• Acties draaien op onze server met een korte time-out en een blokkade op interne adressen; je API-sleutels blijven buiten beeld van de bezoeker.
• Persoonlijke acties zijn beschikbaar vanaf het Crew-abonnement.