Se você tem o Messenger instalado no seu site para users logados, é essencial protegê-lo e evitar que agentes mal-intencionados personifiquem seus users ou enviem dados não autorizados.
Para melhorar a segurança e flexibilidade para nossos clientes, introduzimos JSON Web Tokens (JWTs) como uma forma mais segura e escalável de autenticar users no Messenger.
Se você está usando atualmente Identity Verification (IDV) para verificar users, mudar para JWTs lhe dará:
Maior controle sobre autenticação – Gerencie a expiração e revogação da sessão você mesmo, em vez de depender de configurações fixas.
Segurança reforçada – JWTs permitem tokens assinados e com tempo limitado, reduzindo o risco de ataques de repetição.
Melhoria na segurança dos dados – Defina exatamente quais atributos do user podem ser atualizados, reduzindo a exposição de dados sensíveis.
Preparação para o futuro – JWTs são a substituição recomendada para IDV, garantindo que seu sistema de autenticação esteja alinhado com as melhores práticas.
Quem deve migrar?
Esta migração é relevante para todos os clientes que usam IDV atualmente, especialmente se você:
✅ Precisa de melhor controle sobre expiração de sessão e revogação de token
✅ Quer impor atualizações seguras e específicas de atributos do user
✅ Lida com dados sensíveis de clientes e requer autenticação mais forte
✅ Está planejando melhorias de segurança a longo prazo no seu workspace
Embora o IDV continue funcionando por enquanto, JWTs oferecem uma abordagem mais moderna e segura que está alinhada com as melhores práticas de autenticação. Este guia irá orientá-lo passo a passo no processo de migração.
O que acontece com o histórico de conversas do Messenger se eu não usar JWTs?
Se seu canal do Messenger não tiver a Segurança do Messenger com JWTs configurada, seus customers podem ver apenas seu próprio histórico de conversas dos últimos 14 dias no Messenger. Esse limite foi introduzido em abril de 2026 como medida de segurança.
Para restaurar a visibilidade completa do histórico de conversas para seus customers, configure a Segurança do Messenger com JWTs seguindo os passos de migração abaixo. Uma vez que os JWTs estejam ativos em uma plataforma, o limite de 14 dias é removido para essa plataforma.
Conversas com mais de 14 dias ficam ocultas para os customers no Messenger, não deletadas. Elas permanecem visíveis para seus colegas na Inbox. Para mais detalhes, veja Visibilidade do histórico de conversas do user.
Principais diferenças entre Identity Verification e Segurança do Messenger com JWTs
| Identity Verification | Segurança do Messenger com JWTs |
Método de verificação | Hash assinado HMAC-SHA256 | Token JWT assinado HMAC-SHA256 |
Suporta expiração? | Não | Sim |
Suporta atualizações seguras de dados? | Não | Sim |
Recomendado para | Verificação básica de identidade no Messenger | Autenticação segura com melhor controle de sessão e manipulação segura de dados |
Passos para migração
Passo 1: Atualize sua integração para gerar JWTs em vez de hashes
Pare de gerar assinaturas HMAC-SHA256 (também chamadas de user_hashes) para Identity Verification.
[opcional] Gere uma nova chave secreta para seu Messenger, escolhendo para quais plataformas deseja aplicá-la
Gere um JWT usando sua chave secreta.
Se Identity Verification já estiver habilitado para seu workspace (indicado pelas configurações do Messenger dizendo "securely installed"), o Intercom aceitará apenas requisições contendo um user hash válido ou um JWT válido.
Se desejar verificar se sua implementação de JWT funciona como esperado antes de mudar, recomendamos fazer a integração primeiro no seu workspace de teste.
Nota: workspaces de teste e de produção têm chaves secretas do Messenger diferentes e, portanto, gerarão user hashes e JSON web tokens diferentes.
Aqui está um exemplo de configuração de código do lado do servidor para Node.js:
const jwt = require("jsonwebtoken");
const payload = {
user_id: "USER_ID_HERE", // Required
email: "EMAIL_ADDRESS_HERE", // Optional
data_attribute: "YOUR_DATA", // Optional
exp: Math.floor(Date.now() / 1000) + 3600 // Expires in 1hr
};
const secret = process.env.MESSENGER_SECRET_KEY || "YOUR_MESSENGER_SECRET_KEY"; // Secure key storage
const intercomUserJwt = jwt.sign(payload, secret, { algorithm: "HS256" });O que colocar no payload do seu JWT:
user_idpara identificar o user. Este é um campo obrigatório.Um timestamp opcional (
exp) para expiraçãoQuaisquer outros atributos de dados que você queira enviar com segurança para seus users
Para instruções detalhadas sobre como gerar JWTs para seu workspace, veja nosso artigo principal no help center ou visite suas configurações de segurança.
Passo 1a: Uma nota sobre atributos de dados
Se você está enviando atualmente atributos de dados sobre seus users pelo Messenger, você deve atualizar sua integração para enviar esses atributos com segurança dentro do JWT do user. Para isso, adicione quaisquer atributos ao seu payload e garanta que quaisquer requisições inseguras do Messenger sejam bloqueadas.
No exemplo de código acima, nosso payload assina o user_id e o email. Também inclui uma expiração, que também deve ir para o payload.
Para esses atributos, agora devemos desabilitar atualizações inseguras do Messenger para esses atributos. Isso significa que eles só podem ser atualizados via um JWT válido e nunca sem ele.
Recomendamos que você ative essa opção para qualquer atributo que esteja enviando no seu JWT. Você pode ver os atributos do seu workspace em Configurações > Dados > Pessoas
Nota: Essa opção de atualização de atributo não impede que você colete dados diretamente de leads com um bot. Esses dados vêm diretamente do user.
Passo 2: Atualize seu snippet frontend para enviar JWTs para users
Em vez de passar uma assinatura HMAC para IDV, passe o JWT nas configurações do Messenger como intercom_user_jwt
Para Web (JavaScript SDK):
window.Intercom("boot", {
api_base: "https://api-iam.intercom.io",
app_id: "<YOUR_APP_ID_HERE",
intercom_user_jwt: "<YOUR_USER_JWT_HERE>"
};React: Se você está usando o React SDK, api_base não é necessário na chamada de boot como é para o snippet JavaScript vanilla mostrado acima — o React SDK lida com isso internamente. Inclua api_base apenas se estiver usando o snippet JavaScript simples.
Como mencionado na seção anterior, agora estamos enviando nossos atributos de dados dentro do JWT e eles foram removidos do snippet.
Para instruções detalhadas sobre como gerar JWTs para seu workspace, veja nosso artigo principal no help center ou visite suas configurações de segurança. Para instruções móveis, veja nossa documentação para desenvolvedores para iOS e Android.
Impondo JWTs em todas as requisições
Obter um JWT válido aceito em requisições individuais é um passo separado de exigir um em todas as requisições. Para exigir um JWT válido para toda requisição do Messenger daqui para frente, você também precisa ativar Enforce Messenger Security em Configurações > Messenger > Segurança. Até que essa opção esteja ativada, a autenticação JWT pode funcionar corretamente sem ser aplicada em todo o workspace.
Solução de problemas
Existem logs detalhados de falhas e ferramentas de depuração de token em suas configurações de segurança para ajudar na migração para JWTs.
Por que recebo um erro 403 Forbidden após migrar para JWTs?
Um erro 403 "Forbidden request" após migrar para Segurança do Messenger com JWTs, mesmo que seu JWT seja válido, acontece quando a API do Messenger para web está desativada no seu workspace. Enquanto estiver desativada, o Messenger rejeita todos os users logados e aceita apenas visitantes anônimos, independentemente de o user_id do JWT corresponder ao external_id do contato.
Para corrigir o erro 403, acesse Configurações > Canais > Messenger > Instalar, selecione For users with logins e ative a opção Enable the Messenger API to continue installation para web. Depois, inicie o Messenger novamente com seu JWT.
Perguntas frequentes
O que acontece se eu não migrar?
Identity Verification continuará funcionando por enquanto, mas JWTs oferecem segurança mais forte e melhor controle.
Como revogo uma sessão JWT?
Você pode definir uma expiração curta (exp) ou rotacionar chaves de assinatura para invalidar tokens antigos.
Posso usar Identity Verification e JWTs juntos?
Uma vez que a autenticação JWT esteja habilitada para uma plataforma, Identity Verification não é mais necessária. No entanto, você pode usar JWTs e Identity Verification independentemente na web, iOS e Android, pois todos são configurados individualmente.