NexaChat AjudaAbrir o painel

Ajuda › Integrar o NexaChat ao seu sistema

Integrar o NexaChat ao seu sistema

Este guia é para quem vai embutir o chat no portal da própria empresa ou de um cliente e usar a API e os webhooks. Nos exemplos, SEU-DOMINIO é o endereço da sua instalação do NexaChat (o mesmo que você usa para entrar no painel).

1. Instalar o widget#

Em Canais › Chat do site copie o código e cole antes do </body> do seu portal:

<script src="https://SEU-DOMINIO/embed/v1.js" data-key="CHAVE_DO_CANAL" async></script>

2. Endereços permitidos#

Em Canais › Chat do site › Domínios autorizados cadastre cada site que vai exibir o chat: produção, homologação, etc.

O servidor confere o endereço em todas as chamadas do widget e a página do chat só aceita ser embutida nesses endereços. Em um site que não está na lista o botão do chat nem aparece (o console do navegador explica o motivo). Se a chave estiver errada, o chat não pode ser embutido em lugar nenhum.

3. Quem é o cliente? Identidade assinada#

Por padrão, quem abre o chat digita nome, e-mail e telefone. Isso é “não verificado”: serve só para a equipe se localizar e nunca dá acesso a dados do ERP nem ao histórico de outra pessoa.

Para dizer ao chat quem é o cliente logado, o servidor do seu sistema assina um token curto e o passa ao widget.

  1. Em Canais › Chat do site › Identidade do cliente, clique em Gerar segredo. O valor (nxis_…) aparece uma única vez: guarde só no servidor.
  2. A cada página que mostra o chat para um cliente logado, gere um token JWT HS256 com estes campos:
CampoPara quê
subO id do cliente no seu sistema (obrigatório).
name, phone, emailDados do cliente, já verificados por você.
documentCPF/CNPJ (opcional). Se vier, vincula o cliente ao ERP da empresa.
iat, expEmissão e validade em segundos. Máximo de 10 minutos entre os dois.
jtiUm identificador único por token: cada token vale uma vez.
  1. Passe o token ao widget:
<script src="https://SEU-DOMINIO/embed/v1.js" data-key="CHAVE" data-user-token="TOKEN_GERADO_NO_SERVIDOR" async></script>

ou, em páginas dinâmicas, NexaChat.identify(token).

O que acontece: o NexaChat confere a assinatura, o prazo e o reuso, liga a conversa ao contato pelo sub (cria ou atualiza) e marca como “identificado pelo parceiro”. Token inválido, vencido ou reaproveitado: o chat segue anônimo e o motivo aparece em Identidade do cliente › Últimas tentativas.

Exemplos para gerar o token#

Node.js (sem bibliotecas):

const crypto = require('crypto');
function tokenNexaChat(cliente, segredo) {
  const b = (o) => Buffer.from(JSON.stringify(o)).toString('base64url');
  const agora = Math.floor(Date.now() / 1000);
  const head = b({ alg: 'HS256', typ: 'JWT' });
  const body = b({ sub: String(cliente.id), name: cliente.nome, email: cliente.email, phone: cliente.telefone,
                   iat: agora, exp: agora + 300, jti: crypto.randomUUID() });
  const sig = crypto.createHmac('sha256', segredo).update(head + '.' + body).digest('base64url');
  return head + '.' + body + '.' + sig;
}

PHP:

function tokenNexaChat($cliente, $segredo) {
  $b = fn($o) => rtrim(strtr(base64_encode(json_encode($o)), '+/', '-_'), '=');
  $agora = time();
  $head = $b(['alg' => 'HS256', 'typ' => 'JWT']);
  $body = $b(['sub' => (string)$cliente['id'], 'name' => $cliente['nome'], 'email' => $cliente['email'],
              'phone' => $cliente['telefone'], 'iat' => $agora, 'exp' => $agora + 300, 'jti' => bin2hex(random_bytes(16))]);
  $sig = rtrim(strtr(base64_encode(hash_hmac('sha256', "$head.$body", $segredo, true)), '+/', '-_'), '=');
  return "$head.$body.$sig";
}

Python:

import base64, hashlib, hmac, json, time, uuid

def token_nexachat(cliente, segredo):
    b = lambda o: base64.urlsafe_b64encode(json.dumps(o, separators=(',', ':')).encode()).rstrip(b'=').decode()
    agora = int(time.time())
    head = b({'alg': 'HS256', 'typ': 'JWT'})
    body = b({'sub': str(cliente['id']), 'name': cliente['nome'], 'email': cliente['email'],
              'phone': cliente['telefone'], 'iat': agora, 'exp': agora + 300, 'jti': str(uuid.uuid4())})
    sig = base64.urlsafe_b64encode(hmac.new(segredo.encode(), f'{head}.{body}'.encode(), hashlib.sha256).digest()).rstrip(b'=').decode()
    return f'{head}.{body}.{sig}'

Trocar ou revogar o segredo#

4. A API do widget em JavaScript#

NexaChat.open();  NexaChat.close();  NexaChat.toggle();
NexaChat.identify(token);       // identifica (ou troca) o cliente
NexaChat.logout();              // limpa a sessão do chat
NexaChat.on('ready' | 'open' | 'close' | 'message' | 'unread', function (dados) { ... });

5. API REST, tokens e escopos#

6. Webhooks e a validação da assinatura#

Cadastre em Integrações › Enviar avisos (Webhooks). Cada aviso é um POST com o cabeçalho X-NexaChat-Event e X-NexaChat-Signature (sha256= + HMAC-SHA256 do corpo bruto com o segredo do webhook). Valide antes de interpretar o JSON:

// Node.js
const esperado = 'sha256=' + crypto.createHmac('sha256', segredo).update(corpoBruto).digest('hex');
const ok = crypto.timingSafeEqual(Buffer.from(esperado), Buffer.from(req.headers['x-nexachat-signature']));

7. Ambiente de teste (sandbox)#

Em Integrações › Entrada (API) o dono da empresa cria a empresa de teste: a mesma API e o mesmo widget, mas ERP de demonstração, nada enviado a clientes reais, dados que você apaga com um clique e que não entram em relatórios nem em cobrança. As chaves de API de lá começam com nxk_test_ e o login é o seu e-mail com +teste (ex.: voce+teste@empresa.com). Trocar entre teste e produção é só trocar a chave e o endereço permitido.

8. Versões, avisos e disponibilidade#

9. Privacidade#

Se o chat fica no portal da sua empresa, o aviso de privacidade do seu site precisa citá-lo. Há um texto pronto em Aviso de privacidade para o chat do seu site.

← Sugestão de resposta por IAAviso de privacidade para o chat do seu site →