Seu site preenche as variáveis de canal do usuário que o widget envia ao seu chatbot: um email, um número de cliente, um número de pedido. Como elas são escritas na página, um visitante pode alterá-las no navegador antes que cheguem ao chatbot. Nada em email=jane@exemple.fr diferencia um valor autêntico de um valor alterado.

Quando o seu chatbot depende dessas variáveis para identificar o visitante ou para chamar as suas APIs em nome dele, você pode exigir uma assinatura nas variáveis que escolher. Seu servidor calcula a assinatura a partir do valor e de uma chave secreta compartilhada com a ViaSay, e sua página a envia junto com o valor. A ViaSay verifica a assinatura a cada mensagem: um valor que não corresponde nunca chega ao seu chatbot.

📘 Onde encontrar

A assinatura está disponível nos canais de widget. Acesse Integrate → Channels, abra o seu widget e depois a aba Security. A aba é visível para usuários com a função Manager ou Platform Administrator.

Quando proteger uma variável

Proteja toda variável em que o seu chatbot confia:

• Identidade: um email, um número de cliente ou um número de telefone usado para reconhecer o visitante.

• Parâmetros de API: um identificador passado a uma chamada de API para buscar pedidos, reservas ou dados da conta.

• Handover: um email ou um número de telefone usado para encontrar a conta do cliente quando a conversa é transferida para um agente.

Uma variável que só personaliza a conversa, como a categoria da página ou o produto visualizado, não precisa de assinatura: um valor alterado só muda o que o visitante vê.

O que sua página envia

Cada variável protegida é enviada com um atributo extra que tem o mesmo nome seguido de _signature. Aqui, a página envia um email assinado:

<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>

A assinatura é o HMAC-SHA256 do valor, calculado com a chave secreta compartilhada e escrito em hexadecimal minúsculo. Os atributos _signature servem apenas para a verificação: eles nunca chegam ao seu chatbot, aos seus analytics nem ao seu histórico de conversas.

Sua página continua enviando as variáveis exatamente como antes. A única novidade é uma linha _signature para cada variável protegida.

Calcule a assinatura no seu servidor

Seu servidor já sabe quem está conectado: ele calcula a assinatura ao gerar a página, com a chave que você salva na aba 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 verificar sua implementação, use este par de teste. Seu código deve produzir exatamente a assinatura esperada:

🚧 Quatro regras

• Calcule a assinatura no seu servidor, nunca no navegador. Qualquer pessoa pode ler uma chave escrita no JavaScript da sua página, e ela deixa de proteger qualquer coisa.

• Assine exatamente a string que você envia, incluindo maiúsculas e espaços: Jane@Exemple.fr e jane@exemple.fr não têm a mesma assinatura. Assine o valor bruto, antes de qualquer escape HTML ou JavaScript.

• Use a chave como ela é, como texto. Não a decodifique de hexadecimal nem de Base64, mesmo que pareça hexadecimal: uma chave gerada é usada caractere por caractere.

• Use uma chave aleatória de pelo menos 32 caracteres, dedicada a esta integração. O botão Generate cria uma para você.

Configure a aba Security

A aba Security guia você em quatro etapas. Tudo o que você salva nas etapas 1 a 3 é um rascunho: seus visitantes só são verificados depois que a configuração é publicada, então você pode preparar e testar no seu ritmo.

Etapa 1: salve uma chave secreta compartilhada

Cole a chave que o seu servidor vai usar ou clique em Generate para criar uma aleatória. Uma chave gerada aparece em texto claro com um botão de cópia: copie-a agora para o seu servidor, porque ela não é mais exibida depois de salva. Em seguida, clique em Save key.

A chave é armazenada criptografada e nunca mais é exibida: a aba apenas indica que existe uma chave. Uma chave recém-salva aparece como New key, aguardando publicação: ela só é aplicada quando você publica.

Etapa 2: escolha as variáveis a proteger

Clique em Add a variable e escolha as variáveis que sua página assina. Só aparecem as variáveis de canal do usuário: se a que você precisa ainda não existe, crie-a primeiro. Suas escolhas são salvas à medida que você as faz.

Algumas regras se aplicam aos nomes das variáveis protegidas:

• No máximo 50 variáveis por widget.

• Um nome não pode terminar em _signature: proteja email, e sua página envia email_signature.

• Nomes reservados pelo widget, como token ou id, não podem ser protegidos.

Etapa 3: verifique suas assinaturas

Antes de publicar, verifique se o que o seu servidor produz corresponde ao que a ViaSay espera. Três formas de testar, da mais rápida à mais completa:

Clique em Run test. O resultado mostra, variável por variável, o que a ViaSay concluiria em uma mensagem real.

Quando uma variável falha, o resultado explica o motivo e o que corrigir:

Etapa 4: publique

Quando o teste for bem-sucedido, clique em Publish, no canto superior direito da página do canal. O banner no topo da aba indica em que ponto da configuração você está.

Publish fica bloqueado até que sua última alteração tenha passado em um teste. Se você mudar a chave ou as variáveis depois de um teste, execute outro.

Depois da publicação, a etapa 4 mostra que as assinaturas são exigidas dos seus visitantes, desde quando e em quais variáveis:

O que acontece a cada mensagem

Depois que a configuração é publicada, cada mensagem do widget é verificada, e o seu chatbot sempre tem o que a sua página certifica naquele momento:

👍 Preveja o caso vazio nos seus fluxos

Uma variável protegida pode chegar vazia a qualquer momento. Antes de usá-la, por exemplo em uma chamada de API, verifique se ela tem um valor e preveja outro caminho quando estiver vazia: pedir ao visitante que faça login ou continuar sem a conta dele.

No handover

Quando a conversa é transferida para um agente pelo Freshchat ou pelo ViaFlow, só um email, um número de telefone ou um identificador de contato que chegou com uma assinatura válida é usado para encontrar a conta do cliente. Um valor que o visitante digitou na conversa ou alterou na página nunca é vinculado a uma conta existente: ninguém consegue abrir o cadastro de outro cliente digitando o email dele.

Troque a chave

Troque a chave regularmente, ou imediatamente se ela puder ter sido exposta. A chave anterior continua aceita depois da publicação, então seus servidores podem passar para a nova chave sem interromper seus visitantes.

1. Clique em Replace key, cole ou gere a nova chave e salve-a. Ela aparece como New key, aguardando publicação. Seus visitantes continuam sendo verificados com a chave atual.

2. Execute um teste com a nova chave na etapa 3.

3. Publique. A nova chave passa a ser a chave atual, e a antiga passa a ser a Previous key: as duas são aceitas.

4. Atualize seus servidores para que assinem com a nova chave.

5. Quando todas as suas páginas assinarem com a nova chave, clique em Remove ao lado da chave anterior.

🚧 Troque seus servidores depois de publicar, não antes

Até você publicar, só a chave atual é aceita: uma página assinada com a nova chave deixaria seus visitantes anônimos. Se a chave antiga foi exposta, publique imediatamente e remova a chave anterior assim que seus servidores usarem a nova.

Altere as variáveis protegidas

Você pode adicionar ou remover variáveis protegidas a qualquer momento. Enquanto você não publicar, a alteração continua como rascunho: seus visitantes continuam sendo verificados com as variáveis publicadas. Execute um teste e publique para aplicá-la.

Pare de exigir as assinaturas

Clique em Stop enforcing na etapa 4. As assinaturas deixam de ser verificadas imediatamente, e as variáveis enviadas pela sua página voltam a ser aceitas sem assinatura. Sua chave e suas variáveis são mantidas: você pode publicar de novo a qualquer momento sem precisar informar nada novamente.

Solução de problemas

Um visitante conectado é tratado como anônimo. Verifique se cada página que carrega o widget para um visitante conectado envia os valores assinados. Uma página que carrega o widget sem eles deixa o visitante anônimo a partir da mensagem seguinte.

O teste mostra "Signature does not match". Compare com o par de teste acima: se o seu código não produz 77e12a4f…68fdabb, o problema está no código de assinatura. Caso contrário, verifique se o seu servidor usa a chave salva na etapa 1 e se assina o valor exatamente como a página o envia.

Publish está desativado. Sua última alteração ainda não passou em um teste. Execute um teste na etapa 3.

Não coloque em cache páginas que contêm uma assinatura. Uma assinatura prova a quem pertence o valor: uma página em cache servida a outro visitante daria a ele a identidade do primeiro.