Manual · programadores

Dados pessoais para visitantes autenticados

Deixa o teu assistente responder a perguntas como "para o que é que reservei?" ou "qual é o estado da minha encomenda?" — consultando a tua própria API em nome do visitante que está autenticado no teu site.

A abordagem é deliberadamente simples e segura: o teu site diz ao chatbot quem está autenticado, mas de forma assinada, para que um visitante nunca se possa fazer passar por outro. Tens isto a funcionar num quarto de hora.

Passo 1 — Ativa a verificação e gera um segredo

Abre o teu bot no portal, vai ao separador Ações e ativa "Dados pessoais de visitantes autenticados". Clica em Gerar para um segredo partilhado e guarda.

• Guarda o segredo como uma palavra-passe — numa variável de ambiente ou no teu secrets-store, nunca no código do teu front-end.
• Suspeitas que tenha vazado? Gera um novo segredo; as assinaturas antigas ficam então imediatamente inválidas.

Passo 2 — Calcula a assinatura no teu servidor

Calcula para o visitante autenticado HMAC-SHA256(geheim, gebruikers-id) e passa o resultado como texto hexadecimal. Isto acontece sempre do lado do servidor — o segredo não pode entrar no navegador.

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

// Onderteken de gebruikers-id.
$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');

// Server-side, op je ingelogde route:
const secret   = process.env.CODEBROUWERIJ_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://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

# Bijv. als context-processor of in je view:
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}

# In je 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

Passo 3 — Coloca o widget nas tuas páginas autenticadas

Nas páginas onde o visitante está autenticado, renderizas o widget com data-user-id e data-user-hash. Nas páginas públicas omites simplesmente esses atributos — aí o chatbot funciona de forma anónima.

• data-user-id — o id de utilizador do teu sistema (é verificado).
• data-user-hash — a assinatura do passo 2.
• data-user-email / data-user-name — opcional, puramente informativo para uma saudação pessoal.

Passo 4 — Configura uma ação

Adiciona no portal (separador Ações) uma ação, por exemplo get_reservations. Dizes ao assistente o que a ação faz e que API pode invocar. No URL, nos cabeçalhos ou no corpo usas marcadores de posição que nós preenchemos do lado do servidor a partir do visitante verificado:

• {{user.id}} — o id de utilizador verificado
• {{user.email}} — o endereço de e-mail, se fornecido
• {{user.token}} — um eventual token transmitido (ver abaixo)
• {{naam}} — um parâmetro que o próprio assistente preenche (p. ex. um número de encomenda)

Um URL de exemplo para "as minhas reservas":

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

Importante: a tua API tem de verificar ela própria que os dados solicitados pertencem mesmo a este utilizador. Nós fornecemos a identidade verificada; a autorização fica do teu lado — assim fica com dupla tranca.

Alternativa: transmitir um token

Preferes transmitir um token existente (por exemplo, um JWT de curta duração que a tua API já consegue validar)? Então coloca data-user-token no widget. Nós enviamos esse token para a tua API (por exemplo, como Authorization: Bearer {{user.token}}), que deduz dele o próprio utilizador. Usa uma duração curta e a audience correta.

Segurança em resumo

• O segredo fica apenas no teu servidor. Nunca o coloques em HTML, JavaScript ou num repositório público.
• A assinatura é calculada por visitante do lado do servidor — não no navegador.
• Nós comparamos a assinatura em tempo constante e recusamos ações pessoais assim que ela não está correta ou está ausente.
• As ações correm no nosso servidor com um tempo-limite curto e um bloqueio de endereços internos; as tuas chaves de API ficam fora da vista do visitante.
• As ações pessoais estão disponíveis a partir do plano Crew.