Verificação de identidade de clientes conectados

Para que serve

Quem mais precisa disso é um chat dentro de um painel de clientes, de uma área de membros ou do seu app. Lá os seus clientes já estão conectados. Pedir de novo o nome e o e-mail não faz sentido, e a sua equipe quer saber com certeza quem está escrevendo. Com a verificação de identidade:

• O cliente conversa com o nome e o e-mail reais. O formulário antes do chat e a pergunta do e-mail são pulados.
• Cada visita, em qualquer dispositivo, cai no mesmo contato, então a sua equipe vê na hora as conversas anteriores, as notas e os atributos.
• Na conversa e na página do contato, um sinal de verificado ao lado do nome mostra que a identidade foi verificada. Passe o mouse por cima para ver Usuário verificado.
• Ninguém consegue se passar por um dos seus clientes. O widget só aceita uma identidade com uma assinatura do seu servidor, e só o seu servidor conhece a chave. O Deskwoot confere a assinatura sem nenhum acesso aos seus sistemas.

Passo 1: Crie a sua chave secreta

1. Acesse Configurações > Caixas de entrada e abra a sua caixa de entrada de chat ao vivo.
2. Em Instalação e privacidade, clique em Reconhecer clientes conectados.
3. Em Chave secreta, clique em Criar chave. O Deskwoot cria a chave e a mostra na hora.
4. Clique em Copiar e guarde a chave no seu servidor, por exemplo numa variável de ambiente chamada DESKWOOT_IDENTITY_SECRET.

A partir daí, a linha mostra Configurado. Você pode voltar quando quiser: Mostrar exibe a chave de novo e Copiar copia a chave. Cada caixa de entrada de chat ao vivo tem a sua própria chave, e uma assinatura feita com ela só vale para o widget dessa caixa de entrada.

A chave fica só no seu servidor. Nunca a coloque em código que roda no navegador e nunca calcule a assinatura lá. Quem tiver a chave pode se passar por qualquer um dos seus clientes.

Passo 2: Assine o id de usuário no seu servidor

Para cada cliente conectado, o seu servidor calcula um HMAC SHA256 do id de usuário com a chave secreta e o escreve em hexadecimal. Esse valor é o identifierHash. Use um id de usuário que nunca muda, como o id do seu banco de dados, e use a chave exatamente como o Deskwoot a mostra, como texto.

Node.js:

import crypto from "crypto";

const identifierHash = crypto
  .createHmac("sha256", process.env.DESKWOOT_IDENTITY_SECRET)
  .update(userId)          // your stable user id, as a string
  .digest("hex");

Python:

import hashlib, hmac, os

identifier_hash = hmac.new(
    os.environ["DESKWOOT_IDENTITY_SECRET"].encode(),
    user_id.encode(),
    hashlib.sha256,
).hexdigest()

PHP:

$identifierHash = hash_hmac("sha256", $userId, getenv("DESKWOOT_IDENTITY_SECRET"));

O resultado sempre tem 64 caracteres. O painel do Deskwoot também mostra o exemplo em Node.js, em Passo 1: no seu servidor.

Passo 3: Passe o usuário para o widget

No código do widget da sua página, adicione um objeto user a window.deskwootSettings. O seu servidor preenche os valores quando monta a página para um cliente conectado.

window.deskwootSettings = {
  widgetToken: "YOUR_WIDGET_TOKEN",
  user: {
    identifier: "user_4711",            // your stable user id
    identifierHash: "<HMAC-SHA256 of identifier, computed on your server>",
    email: "jane@example.com",          // optional
    name: "Jane Doe"                    // optional
  }
};

• identifier: o id estável do seu usuário, como texto. É o único campo assinado, então envie exatamente o texto que você assinou. Um número também vai entre aspas, como "4711". Até 128 caracteres.
• identifierHash: a assinatura do passo 2.
• email e name: opcionais. Aparecem no contato no Deskwoot.
• attributes: dados opcionais como um plano, veja "Envie mais dados com atributos" mais abaixo.

Para visitantes que não estão conectados, deixe user de fora: eles conversam como visitantes anônimos, como antes. O painel do Deskwoot mostra esse código com o seu próprio token do widget, em Passo 2: na sua página. Se o widget ainda não está no seu site, comece por Incorporando o widget.

Quando o seu app faz login depois que a página carrega

Num app que faz o login do cliente sem carregar uma página nova, chame window.deskwoot.identify(user) com o mesmo objeto assim que o seu servidor o assinar. Isso atualiza o visitante atual sem recarregar.

window.deskwoot.identify({
  identifier: "user_4711",
  identifierHash: "<HMAC-SHA256 of identifier, computed on your server>",
  email: "jane@example.com",
  name: "Jane Doe"
});

Se o cliente já estiver conectado quando a página carrega, defina user em window.deskwootSettings antes do código do widget. Assim o chat continua aberto a cada recarregamento. Com identify() depois do carregamento, cada recarregamento começa com o chat vazio, que volta assim que o cliente é verificado.

Envie mais dados com atributos

Com attributes você pode enviar uma lista simples de dados, como { plan: "Pro" } ou o id de uma empresa. Eles aparecem no contato para a sua equipe.

A assinatura cobre só o id de usuário, então um visitante poderia alterar esses atributos no navegador. Por isso o bot de IA nunca lê atributos sem assinatura. Para que a IA responda com base neles, assine-os também no seu servidor e envie attributesHash e attributesIssuedAt (a hora unix em segundos em que você os assinou) junto. Além disso, a IA só os lê quando pode consultar contatos. Assine de novo a cada carregamento de página: o Deskwoot usa um conjunto assinado por até 24 horas. Assine só o que o cliente pode ver, porque a IA pode dizer a ele o que um atributo assinado diz.

O formato exato, com código para Node.js e Python e um vetor de teste para conferir o seu código, está na documentação do widget.

Sem verificação de identidade, ou quando a assinatura está errada

• Sem user nas configurações: o visitante conversa de forma anônima, e o formulário antes do chat e a pergunta do e-mail aparecem como você configurou em Antes do chat.
• Assinatura errada: o Deskwoot recusa a identidade. O chat continua funcionando, mas o cliente conversa como visitante anônimo e vê o formulário antes do chat, se você usa um. O cliente não vê nenhuma mensagem de erro. O mesmo acontece quando a caixa de entrada ainda não tem chave, quando o id de usuário não é exatamente o texto que você assinou, quando ele tem mais de 128 caracteres ou quando o e-mail não é válido.
• Chave nova: quando você clica em Criar uma nova chave e confirma com Sim, criar nova chave, a chave antiga para de funcionar na hora. Até você colocar a nova no seu servidor, os clientes conectados não são reconhecidos.
• Atributos assinados: um attributesHash errado faz recusar a identidade inteira, como uma assinatura errada, e o mesmo vale para um conjunto assinado acima dos limites (30 chaves, chaves de até 64 caracteres, valores de até 1024 caracteres). Já um conjunto assinado com mais de 24 horas não: o cliente continua verificado, mas esses atributos são ignorados.

Para achar a causa, abra as ferramentas de desenvolvedor do seu navegador, vá até a aba de rede e veja a resposta da requisição para /api/widget/identity/verify. invalid_identifier_hash quer dizer que a assinatura não bate com o id de usuário, e identity_verification_not_configured quer dizer que a caixa de entrada ainda não tem chave.

Perguntas frequentes

Preciso da verificação de identidade para o chat funcionar?

Não. Ela é opcional. Sem ela, todos conversam como visitantes anônimos e preenchem o formulário antes do chat, se você usa um. A verificação de identidade só acrescenta o reconhecimento dos clientes conectados.

Posso colocar a chave secreta no JavaScript da minha página?

Não. Tudo o que está no navegador pode ser lido por qualquer pessoa, e quem tiver a chave pode se passar por qualquer um dos seus clientes. Mantenha a chave no seu servidor e envie para a página só a assinatura pronta.

O que devo usar como id de usuário?

Um id que nunca muda para esse cliente, como o id do usuário no seu banco de dados. O Deskwoot encontra o contato por esse id a cada visita, então um id novo significa um contato novo. Um e-mail funciona pior, porque as pessoas trocam de e-mail.

O Deskwoot associa um cliente verificado pelo e-mail?

Não. O Deskwoot associa um cliente verificado só pelo id de usuário que você assinou. O e-mail e o nome não são assinados, então o Deskwoot nunca liga um visitante a um contato existente por causa deles. Se outro contato já tem esse e-mail, o contato verificado é salvo sem ele.

Uma chave vale para todas as minhas caixas de entrada?

Não. Cada caixa de entrada de chat ao vivo tem a sua própria chave, e uma assinatura feita com ela só funciona para o widget dessa caixa de entrada. Se você tem o widget de 2 caixas de entrada nos seus sites, crie uma chave em cada uma e assine com a chave da caixa de entrada cujo widget está naquela página.

Onde a minha equipe vê que um cliente está verificado?

Num sinal de verificado ao lado do nome do cliente, na conversa e na página do contato. Passe o mouse por cima para ver Usuário verificado.