Como habilitar a validação de identidade no Chatwoot

A validação de identidade ajuda a garantir que as conversas entre seus clientes e os agentes de suporte permaneçam privadas. Ela também impede que alguém se passe por outra pessoa (impersonation) usando o identificador de outro cliente no widget de chat do seu site.

O funcionamento é simples: em vez de confiar apenas no identificador enviado pelo navegador, o Chatwoot passa a exigir também um HMAC — um código de autenticação assinado com uma chave secreta que só você e o Chatwoot conhecem. Sem esse hash, o identificador é recusado, e ninguém consegue forjar a identidade de um cliente.

Onde obter a chave HMAC

A chave usada para gerar o HMAC é diferente para cada caixa de entrada de chat no site (web widget). Para copiá-la:

1. Vá em Configurações → Caixas de Entrada e abra a caixa de entrada do chat no site.
2. Abra a aba Configurações e, em seguida, a seção Configuração.
3. Localize Validação de Identidade e clique em Copiar para copiar a chave secreta exibida ali.
4. Ative Exigir validação de identidade para todas as conversas. Sem essa opção, o hash pode ser verificado quando enviado, mas não é obrigatório para todos os usuários.

Guarde esse token com segurança no seu backend — ele é a chave secreta do HMAC e nunca deve ficar exposta no código do navegador.

Gerar o identifier_hash

Com o token em mãos, gere o identifier_hash no seu servidor calculando o HMAC-SHA256 da mensagem (o identificador único do usuário) usando a chave (o token copiado acima). Substitua <webwidget-hmac-token> pelo token e <identifier> pelo mesmo identificador único que você vai passar ao setUser.

PHP

<?php

$key = '<webwidget-hmac-token>';

$message = '<identifier>';

$identifier_hash = hash_hmac('sha256', $message, $key);

?>

Javascript (Node.js)

const crypto = require('crypto');

const key = '<webwidget-hmac-token>';

const message = '<identifier>';

const hash = crypto.createHmac('sha256', key).update(message).digest('hex');

Ruby

require 'openssl'

require 'base64'

key = '<webwidget-hmac-token>'

message = '<identifier>'

identifier_hash = OpenSSL::HMAC.hexdigest('sha256', key, message)

Elixir

key = '<webwidget-hmac-token>'

message = '<identifier>'

signature = :crypto.mac(:hmac, :sha256, key, message)

identifier_hash = Base.encode16(signature, case: :lower)

Golang

import (
	"crypto/hmac"
	"crypto/sha256"
	"encoding/hex"
)

func identifierHash(secret, identifier string) string {
	mac := hmac.New(sha256.New, []byte(secret))
	mac.Write([]byte(identifier))
	return hex.EncodeToString(mac.Sum(nil))
}

Python

import hashlib

import hmac

secret = '<webwidget-hmac-token>'.encode('utf-8')
identifier = '<identifier>'.encode('utf-8')
identifier_hash = hmac.new(secret, identifier, hashlib.sha256).hexdigest()

Passar o identifier_hash no setUser

Depois de calcular o hash no seu backend, envie-o para a página e informe-o ao widget pelo método setUser. O primeiro argumento é o identificador único do usuário (o mesmo valor usado como message acima), e o campo identifier_hash recebe o hash gerado:

window.$chatwoot.setUser("<identificador-único>", {
  name: "Nome do Usuário",
  email: "[email protected]",
  identifier_hash: "<hash-gerado-no-backend>"
});

Com a validação de identidade ativada, o widget só aceita o usuário se o identifier_hash conferir com o identificador — por isso o cálculo deve sempre acontecer no servidor, nunca no navegador, para que o token HMAC não seja exposto.

Para conhecer os demais campos aceitos pelo setUser e outras opções do SDK, veja Como enviar informações adicionais de usuário para o Chatwoot com SDK.