Identificação de usuários

Identificar usuários liga as sessões de chat anônimas a perfis de usuário reais.

Como funciona

Quando você chama Respondo.identify(), os campos fornecidos são anexados à conversa. Todos os campos são opcionais — passe apenas os que você tiver. Por exemplo, você pode enviar apenas userId sem e-mail nem nome. Os atendentes veem esses dados no painel de detalhes da conversa.

Parâmetros#

Propriedade	Tipo	Obrigatório	Descrição
email	string	opcional	Endereço de e-mail do usuário
name	string	opcional	Nome apresentado
userId	string	opcional	O seu ID interno de usuário ou de apresentação — mostrado tal como está no dashboard
userHash	string	opcional	Assinatura HMAC-SHA256 para verificação de identidade
metadata	object	opcional	Pares chave-valor de campos personalizados (plano, empresa, etc.)
properties	object	opcional	Propriedades de contato personalizadas definidas em Agent Settings. As chaves têm de corresponder às configurações de propriedade. Os valores são armazenados com o prefixo `cp_` e podem ser filtrados na Caixa de entrada.

Exemplo: Single Page Appjavascript

// Após fazer login com sucesso
async function onLogin(user) {
  await authenticateUser(user);

  Respondo.identify({
    email: user.email,
    name: user.fullName,
    userId: user.id,
    metadata: {
      plan: user.subscription.plan,
      company: user.company.name,
      role: user.role,
      signedUp: user.createdAt
    },
    properties: {                        // propriedades de contato personalizadas
      account_type: user.accountType,    // devem corresponder às chaves de Agent Settings
      industry: user.industry,
      contract_tier: user.tier
    }
  });
}

Com o snippet de instalação padrão, você pode chamar identify() a qualquer momento — as chamadas feitas antes de o widget.js terminar de carregar são enfileiradas pelo snippet e reproduzidas automaticamente assim que o widget é inicializado. Os dados de identidade só são descartados (com um aviso no console) se você mesmo carregar o widget.js e chamar identify() antes de alguma vez chamar init() — em configurações manuais, chame sempre init() primeiro.

Visitantes anônimos#

Se você não chamar identify(), o widget atribui automaticamente um visitor ID persistente, salvo em localStorage (chave respondoai_visitor_id). No dashboard, a conversa aparece como Guest · Web widget.

Modo	Exibição no dashboard	HMAC obrigatório
Sem `identify()`	Guest · Web widget	Não
`identify({ email, name })`	Nome + e-mail mostrados	Não — a menos que a Verificação de identidade esteja ativada; nesse caso, e-mail e nome sem assinatura são removidos silenciosamente e a sessão permanece anônima
`identify({ userId })`	userId mostrado tal como está	Não — a menos que a Verificação de identidade esteja ativada; nesse caso, é exigido um `userHash` válido ou a identidade é removida
`identify({ userId, userHash })`	Identidade de usuário verificada	Sim — verificado criptograficamente

Quando a Verificação de identidade está ativada para o canal, qualquer identify() com e-mail ou userId sem um userHash válido é removido no lado do servidor e o visitante permanece anônimo — veja Verificação de identidade (HMAC) abaixo.

O visitor ID persiste entre sessões no mesmo navegador. Nunca é enviado à Respondo como identidade autenticada — serve apenas para a continuidade de conversas anônimas.

Identificação apenas com userId (sem e-mail nem nome)#

Se a sua plataforma não tiver e-mails nem nomes de usuário — por exemplo, você tem apenas um ID interno de apresentação —, você pode passar apenas userId. Não são necessários outros campos. O dashboard mostra o userId tal como está nos detalhes da conversa.

userId + metadata (sem e-mail nem nome)javascript

// A sua plataforma só tem um ID de apresentação — é suficiente
Respondo.identify({
  userId: user.displayId,      // p. ex. "USR-4821" — mostrado no dashboard
  metadata: {                  // contexto adicional opcional
    plan: 'premium',
    region: 'eu-west'
  }
});
// Não é preciso e-mail nem nome — o widget funciona só com userId

Para impedir a falsificação do userId, combine-o com userHash (ver Verificação de identidade abaixo). Sem HMAC, qualquer pessoa pode passar qualquer userId a partir da consola do navegador.

Google Tag Manager / identify() diferido#

Ao incorporar através do GTM, os dados do usuário podem não estar disponíveis no carregamento da página. Duas abordagens:

Opção A: localStorageKey (sem necessidade de JS)javascript

// Se a sua plataforma já escrever o ID de usuário em localStorage:
Respondo.init({
  agentId: 'YOUR_AGENT_ID',
  localStorageKey: 'myapp_user_id'  // lê localStorage.getItem('myapp_user_id') automaticamente
});
// Não é preciso chamar identify() — o widget detecta o userId sozinho

Opção B: identify() diferido via dataLayerjavascript

// 1. Inicializar o widget imediatamente (tag do GTM)
Respondo.init({ agentId: 'YOUR_AGENT_ID' });

// 2. Mais tarde, quando os dados do usuário surgirem (p. ex. do dataLayer ou da seu app):
var waitForUser = setInterval(function() {
  var uid = localStorage.getItem('myapp_user_id');
  if (uid && window.Respondo && typeof window.Respondo.identify === 'function') {
    clearInterval(waitForUser);
    Respondo.identify({ userId: uid });
  }
}, 500);

localStorageKey só é usado se ainda não houver um userId definido através de identify(). As chamadas explícitas a identify() têm sempre prioridade.

Verificação de identidade (HMAC)#

Sem verificação, qualquer pessoa poderia fazer-se passar por um usuário ao passar um userId ou email falso. A Verificação de identidade usa HMAC-SHA256 para provar criptograficamente que a identidade do usuário foi definida pelo seu servidor e não por código do lado do cliente.

Como funciona#

Ative a Verificação de identidade nas configurações do seu canal — receberá uma chave secreta.
No seu servidor, calcule HMAC-SHA256(secret, userId) — o segredo é a chave, o userId é a mensagem — e envie o resultado para o frontend. Se você identifica usuários apenas por e-mail (sem userId), assine o e-mail: o payload assinado é o userId quando definido, caso contrário o e-mail. Se passar ambos, assine o userId; ele tem prioridade.
Passe o hash como userHash em Respondo.identify().
O Respondo verifica o hash no lado do servidor. Se for inválido, a identidade é removida e o usuário é tratado como anônimo.

Nunca exponha a sua chave secreta no código do frontend. O HMAC deve ser calculado no seu backend.

Depois que a verificação for ativada, toda chamada a identify() que carregue userId ou email deve incluir um userHash válido — caso contrário, os campos de identidade são removidos e o visitante é tratado como anônimo.

Exemplos no lado do servidor#

Node.jsjavascript

const crypto = require('crypto');

const SECRET = process.env.RESPONDO_IDENTITY_SECRET;

function generateUserHash(userId) {
  return crypto
    .createHmac('sha256', SECRET)
    .update(userId)
    .digest('hex');
}

// No seu endpoint de API:
app.get('/api/respondo-hash', (req, res) => {
  const hash = generateUserHash(req.user.id);
  res.json({ userHash: hash });
});

Pythonpython

import hmac, hashlib, os

SECRET = os.environ['RESPONDO_IDENTITY_SECRET']

def generate_user_hash(user_id: str) -> str:
    return hmac.new(
        SECRET.encode(),
        user_id.encode(),
        hashlib.sha256
    ).hexdigest()

# Na sua view / endpoint:
user_hash = generate_user_hash(request.user.id)

Gogo

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

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

Utilização no frontend#

Com Verificação de identidadejavascript

// Obtenha o hash a partir do SEU servidor
const { userHash } = await fetch('/api/respondo-hash').then(r => r.json());

Respondo.identify({
  email: user.email,
  name: user.name,
  userId: user.id,
  userHash: userHash  // assinatura HMAC-SHA256
});