Manual · desarrolladores

Datos personales para visitantes con sesión iniciada

Deja que tu asistente responda preguntas como "¿para qué he hecho una reserva?" o "¿cuál es el estado de mi pedido?" — consultando tu propia API en nombre del visitante que ha iniciado sesión en tu sitio.

El enfoque es deliberadamente sencillo y seguro: tu web le dice al chatbot quién ha iniciado sesión, pero de forma firmada, de modo que un visitante nunca pueda hacerse pasar por otro. Lo tienes funcionando en un cuarto de hora.

Paso 1 — Activa la verificación y genera un secreto

Abre tu bot en el portal, ve a la pestaña Acciones y activa "Datos personales de visitantes con sesión iniciada". Haz clic en Generar para obtener un secreto compartido y guarda.

• Guarda el secreto como una contraseña — en una variable de entorno o en tu almacén de secretos, nunca en el código de tu front-end.
• ¿Sospechas que se ha filtrado? Genera un secreto nuevo; las firmas antiguas dejan de ser válidas al instante.

Paso 2 — Calcula la firma en tu servidor

Para el visitante con sesión iniciada, calcula HMAC-SHA256(geheim, gebruikers-id) y pasa el resultado como texto hexadecimal. Esto se hace siempre en el lado del servidor: el secreto no debe llegar al navegador.

<?php
// El secreto está a salvo en tu servidor (del portal). Nunca en el navegador.
$secret   = getenv('CODEBROUWERIJ_CHATBOT_SECRET');
$userId   = (string) $currentUser->id;

// Firma el identificador de usuario.
$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');

// En el lado del servidor, en tu ruta con sesión iniciada:
const secret   = process.env.CODEBROUWERIJ_CHATBOT_SECRET;
const userId   = String(req.user.id);
const userHash = crypto.createHmac('sha256', secret).update(userId).digest('hex');

// Pasa userId + userHash a tu vista y renderiza allí:
// <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

# Por ejemplo, como context-processor o en tu vista:
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}

# En tu plantilla:
# <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

Paso 3 — Coloca el widget en tus páginas con sesión iniciada

En las páginas donde el visitante ha iniciado sesión, renderizas el widget con data-user-id y data-user-hash. En las páginas públicas simplemente omites esos atributos; allí el chatbot funciona de forma anónima.

• data-user-id — el identificador de usuario de tu sistema (se verifica).
• data-user-hash — la firma del paso 2.
• data-user-email / data-user-name — opcionales, puramente informativos para un saludo personal.

Paso 4 — Configura una acción

Añade en el portal (pestaña Acciones) una acción, por ejemplo get_reservations. Le dices al asistente qué hace la acción y qué API puede invocar. En la URL, las cabeceras o el cuerpo usas marcadores de posición que nosotros rellenamos en el lado del servidor a partir del visitante verificado:

• {{user.id}} — el identificador de usuario verificado
• {{user.email}} — la dirección de correo electrónico, si se ha facilitado
• {{user.token}} — un token que, en su caso, se haya pasado (véase más abajo)
• {{naam}} — un parámetro que el propio asistente rellena (p. ej., un número de pedido)

Un ejemplo de URL para "mis reservas":

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

Importante: tu propia API debe comprobar por sí misma que los datos solicitados pertenecen realmente a este usuario. Nosotros aportamos la identidad verificada; la autorización sigue siendo cosa tuya, así queda doblemente bajo llave.

Alternativa: pasar un token

¿Prefieres pasar un token existente (por ejemplo, un JWT de vida corta que tu API ya pueda validar)? Pon entonces data-user-token en el widget. Nosotros enviamos ese token a tu API (por ejemplo, como Authorization: Bearer {{user.token}}), que deduce de él al usuario. Usa una vida corta y la audiencia correcta.

La seguridad en resumen

• El secreto está solo en tu servidor. No lo pongas nunca en HTML, JavaScript ni en un repositorio público.
• La firma se calcula por visitante en el lado del servidor, no en el navegador.
• Comparamos la firma en tiempo constante y rechazamos las acciones personales en cuanto no es correcta o falta.
• Las acciones se ejecutan en nuestro servidor con un tiempo de espera corto y un bloqueo de direcciones internas; tus claves de API quedan fuera del alcance del visitante.
• Las acciones personales están disponibles a partir del plan Crew.