Tu sitio web rellena las variables de canal de usuario que el widget envía a tu chatbot: un email, un número de cliente, un número de pedido. Como se escriben en la página, un visitante puede modificarlas en su navegador antes de que lleguen al chatbot. Nada en email=jane@exemple.fr distingue un valor auténtico de uno modificado.

Cuando tu chatbot se basa en estas variables para identificar al visitante o para llamar a tus API en su nombre, puedes exigir una firma en las variables que elijas. Tu servidor calcula la firma a partir del valor y de una clave secreta compartida con ViaSay, y tu página la envía junto al valor. ViaSay la comprueba en cada mensaje: un valor que no coincide nunca llega a tu chatbot.

📘 Dónde encontrarla

La firma está disponible en los canales de widget. Ve a Integrate → Channels, abre tu widget y luego la pestaña Security. La pestaña es visible para los usuarios con el rol Manager o Platform Administrator.

Cuándo proteger una variable

Protege toda variable en la que tu chatbot confía:

• Identidad: un email, un número de cliente o un número de teléfono que sirve para reconocer al visitante.

• Parámetros de API: un identificador que se pasa a una llamada de API para obtener pedidos, reservas o datos de la cuenta.

• Handover: un email o un número de teléfono que sirve para encontrar la cuenta del cliente cuando la conversación pasa a un agente.

Una variable que solo personaliza la conversación, como la categoría de la página o el producto que se está viendo, no necesita firma: un valor modificado solo cambia lo que ve el visitante.

Qué envía tu página

Cada variable protegida viaja con un atributo adicional que lleva el mismo nombre seguido de _signature. Aquí la página envía un email firmado:

<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 firma es el HMAC-SHA256 del valor, calculado con la clave secreta compartida y escrito en hexadecimal en minúsculas. Los atributos _signature solo sirven para la comprobación: nunca llegan a tu chatbot, a tus analytics ni a tu historial de conversaciones.

Tu página sigue enviando las variables exactamente como antes. Lo único nuevo es una línea _signature por cada variable protegida.

Calcula la firma en tu servidor

Tu servidor ya sabe quién ha iniciado sesión: calcula la firma cuando genera la página, con la clave que guardas en la pestaña 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)));
    }
}

Para comprobar tu implementación, usa este par de prueba. Tu código debe producir exactamente la firma esperada:

🚧 Cuatro reglas

• Calcula la firma en tu servidor, nunca en el navegador. Cualquiera puede leer una clave escrita en el JavaScript de tu página, y entonces ya no protege nada.

• Firma exactamente la cadena que envías, incluidas mayúsculas y espacios: Jane@Exemple.fr y jane@exemple.fr no tienen la misma firma. Firma el valor en bruto, antes de cualquier escape HTML o JavaScript.

• Usa la clave tal cual, como texto. No la decodifiques desde hexadecimal ni Base64, aunque parezca hexadecimal: una clave generada se usa carácter por carácter.

• Usa una clave aleatoria de al menos 32 caracteres, dedicada a esta integración. El botón Generate crea una por ti.

Configura la pestaña Security

La pestaña Security te guía en cuatro pasos. Todo lo que guardas en los pasos 1 a 3 es un borrador: tus visitantes solo se comprueban una vez publicada la configuración, así que puedes prepararla y probarla a tu ritmo.

Paso 1: guarda una clave secreta compartida

Pega la clave que usará tu servidor o haz clic en Generate para crear una aleatoria. Una clave generada se muestra en claro con un botón de copia: cópiala ahora en tu servidor, porque no vuelve a mostrarse una vez guardada. Después haz clic en Save key.

La clave se almacena cifrada y no vuelve a mostrarse nunca: la pestaña solo indica que existe una clave. Una clave recién guardada aparece como New key, pendiente de publicación: solo se aplica cuando publicas.

Paso 2: elige las variables que quieres proteger

Haz clic en Add a variable y elige las variables que firma tu página. Solo aparecen las variables de canal de usuario: si la que necesitas aún no existe, créala primero. Tus elecciones se guardan sobre la marcha.

Los nombres de las variables protegidas siguen algunas reglas:

• Hasta 50 variables por widget.

• Un nombre no puede terminar en _signature: protege email, y tu página envía email_signature.

• Los nombres reservados por el widget, como token o id, no se pueden proteger.

Paso 3: comprueba tus firmas

Antes de publicar, comprueba que lo que produce tu servidor coincide con lo que espera ViaSay. Tres formas de probar, de la más rápida a la más completa:

Haz clic en Run test. El resultado te dice, variable por variable, qué concluiría ViaSay con un mensaje real.

Cuando una variable falla, el resultado explica por qué y qué corregir:

Paso 4: publica

Cuando la prueba sea correcta, haz clic en Publish, arriba a la derecha de la página del canal. El banner de la parte superior de la pestaña te indica en qué punto de la configuración estás.

Publish permanece bloqueado hasta que tu último cambio haya superado una prueba. Si cambias la clave o las variables después de una prueba, lanza otra.

Tras publicar, el paso 4 indica que las firmas se exigen a tus visitantes, desde cuándo y en qué variables:

Qué ocurre en cada mensaje

Una vez publicada la configuración, se comprueba cada mensaje del widget, y tu chatbot siempre tiene lo que tu página certifica en ese momento:

👍 Prevé el caso vacío en tus flujos

Una variable protegida puede llegar vacía en cualquier momento. Antes de usarla, por ejemplo en una llamada de API, asegúrate de que tiene un valor y prevé otro camino cuando esté vacía: pedir al visitante que inicie sesión o continuar sin su cuenta.

En el handover

Cuando la conversación pasa a un agente a través de Freshchat o ViaFlow, solo se usa para encontrar la cuenta del cliente un email, un número de teléfono o un identificador de contacto que haya llegado con una firma válida. Un valor que el visitante escribió en la conversación o modificó en la página nunca se vincula a una cuenta existente: nadie puede abrir la ficha de otro cliente escribiendo su email.

Cambia la clave

Cambia la clave con regularidad, o de inmediato si ha podido quedar expuesta. La clave anterior sigue aceptándose después de publicar, así que tus servidores pueden pasar a la nueva clave sin interrumpir a tus visitantes.

1. Haz clic en Replace key, pega o genera la nueva clave y guárdala. Aparece como New key, pendiente de publicación. Tus visitantes se siguen comprobando con la clave actual.

2. Lanza una prueba con la nueva clave en el paso 3.

3. Publica. La nueva clave pasa a ser la clave actual, y la antigua pasa a ser la Previous key: se aceptan las dos.

4. Actualiza tus servidores para que firmen con la nueva clave.

5. Cuando todas tus páginas firmen con la nueva clave, haz clic en Remove junto a la clave anterior.

🚧 Cambia tus servidores después de publicar, no antes

Hasta que publiques, solo se acepta la clave actual: una página firmada con la nueva clave dejaría anónimos a sus visitantes. Si la clave antigua quedó expuesta, publica enseguida y elimina la clave anterior en cuanto tus servidores usen la nueva.

Cambia las variables protegidas

Puedes añadir o quitar variables protegidas en cualquier momento. Mientras no publiques, el cambio es un borrador: tus visitantes se siguen comprobando con las variables publicadas. Lanza una prueba y publica para aplicarlo.

Deja de exigir las firmas

Haz clic en Stop enforcing en el paso 4. Las firmas dejan de comprobarse de inmediato, y las variables que envía tu página vuelven a aceptarse sin firma. Tu clave y tus variables se conservan: puedes volver a publicar en cualquier momento sin introducir nada de nuevo.

Solución de problemas

Un visitante con sesión iniciada aparece como anónimo. Comprueba que cada página que carga el widget para un visitante con sesión iniciada envía los valores firmados. Una página que carga el widget sin ellos deja anónimo al visitante a partir del siguiente mensaje.

La prueba indica «Signature does not match». Compara con el par de prueba de arriba: si tu código no produce 77e12a4f…68fdabb, el problema está en el código de firma. Si lo produce, comprueba que tu servidor usa la clave guardada en el paso 1 y que firma el valor exactamente como lo envía la página.

Publish aparece en gris. Tu último cambio aún no ha superado una prueba. Lanza una prueba en el paso 3.

No guardes en caché las páginas que contienen una firma. Una firma demuestra a quién pertenece el valor: una página en caché servida a otro visitante le daría la identidad del primero.