JSON web tokens (JWTs) impedem terceiros de personificar seus users logados e ver suas conversas. Recomendamos fortemente que todos os clientes Fin apliquem autenticação JWT.

Se você tem o Fin Messenger instalado em seu site para users logados, é essencial protegê-lo e impedir que agentes mal-intencionados personifiquem seus users ou enviem dados não autorizados.

Em um Messenger que não é seguro, alguém poderia interagir com seu Fin Messenger e falsificar a identidade de outro user, fornecendo um identificador conhecido como email ou user_id. Isso permite que um atacante se passe por um user real para seus colegas, dando acesso a conversas anteriores e dados potencialmente sensíveis.

O que é um JSON web token (JWT)?

Um JWT é uma forma padrão da indústria para assinar dados. Normalmente consiste em três partes, separadas por pontos. Um JWT típico se parece com isto: header.payload.signature.

O header especifica o tipo do token (JWT) e o algoritmo de assinatura (ex: HS256).
O payload contém declarações sobre o user ou sessão (ex: user_id, email).
Finalmente, a assinatura garante que o token não foi adulterado, usando uma chave secreta ou privada.

Quais são os benefícios de proteger o Messenger com JSON web tokens (JWTs)?

Identidade segura do user: Proteger seu messenger permite que seus colegas tenham certeza de que o user com quem estão falando é realmente aquele user.
Segurança aprimorada dos dados do user: Proteger seu Messenger permite a transmissão segura de atributos de dados sobre seu user através da API do Messenger.
Risco reduzido de sessões roubadas: Proteger seu Messenger com JWTs permite definir expiração para o token, reduzindo significativamente o risco de vazamentos de dados que poderiam ocorrer se tokens forem roubados do navegador do seu user. Ao especificar uma expiração curta, o risco é diminuído.
Workflows Fin e AI mais seguros: Dê seus processos complexos, Actions e Workflows para o Fin, mesmo que exijam informações confiáveis do user.

Ao transmitir com segurança a identidade e dados do user e aplicar a expiração do token, os JWTs garantem que seu Fin Messenger esteja no estado mais seguro possível.

Dica: Ativar a Segurança do Messenger com JWTs também restaura o histórico completo de conversas dos seus clientes no Fin Messenger. Sem JWTs, clientes logados veem apenas seu próprio histórico de conversas dos últimos 14 dias. Esse limite foi introduzido em abril de 2026 como medida de segurança. 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 clientes no Messenger, não deletadas.

Experiência do cliente

Ao usar JWTs com o Fin Messenger, a experiência é a seguinte:

Sua integração do Messenger iniciará seu user logado com uma requisição Intercom('boot') contendo um JWT, que inclui todos os dados do user que você deseja enviar para seu workspace. A assinatura do JWT é gerada usando a chave secreta do Messenger nas suas configurações.
Então, seu workspace fornecerá ao user um cookie de sessão no navegador. Esse cookie tem duração padrão de 7 dias. O cookie será usado durante sua vida útil para autenticar o user e realizar quaisquer atualizações nesse user.
Se a sessão expirar e nenhum JWT novo for enviado, a sessão do user terminará. O user verá um Messenger novo como visitante do site deslogado. Ele não conterá o histórico de conversas.
Uma vez que o Messenger seja reiniciado com Intercom('boot') e um JWT válido, o Messenger identificará o user e mostrará suas conversas históricas e uma nova sessão. Também iremos mesclar qualquer atividade deslogada ocorrida no mesmo dispositivo na conta desse user autenticado.

Dicas:

Se desejar que a duração do cookie de sessão do user seja menor que os 7 dias padrão, você pode especificar o TTL do cookie em milissegundos com o atributo session_duration do Messenger.
Se você está criando tickets Zendesk a partir do Fin Messenger e quer que os tickets sejam direcionados para uma organização específica, você pode incluir um campo de empresa no JWT. O valor id deve corresponder ao ID externo da organização Zendesk (não o ID interno do Zendesk).

Nota: O Fin sincroniza respostas de colegas no Fin para conversas web que são transferidas. Contudo, isso não se aplica a casos Salesforce — uma vez que um caso é reatribuído a um agente ao vivo dentro do Salesforce, o Fin para de puxar atualizações.

Instalação: Gerando e enviando JWTs

Passo 1: Instale o Messenger em sua aplicação

Você pode encontrar as instruções únicas de configuração para seu workspace em Configurações > Fin Messenger > Segurança.

A principal diferença entre uma configuração insegura do Messenger e uma segura é que você incluirá um campo adicional intercomUserJwt em suas requisições de user, que será usado para identificar e atualizar o user.

Você verá uma opção para adicionar atributos de dados no seu snippet Javascript. Isso governa quais dados você quer enviar para seu workspace Fin. Como você usará JWTs para transmitir dados para nós, deve incluir aqui apenas atributos que não deseja assinar, por exemplo: se quiser enviar alguns dados específicos do front-end.

Se não quiser enviar nenhum dado fora do JWT, pode remover todos os dados do seu snippet exceto api_base e app_id. Seu app_id é o identificador único do seu workspace Fin.

Para visitantes sem identificadores específicos de user (como user_id ou email), configure um snippet do Messenger para usuários deslogados incluindo apenas o App ID na configuração. Evite adicionar atributos de user para manter uma configuração leve e segura para visitantes anônimos.

Passo 2: Comece a gerar JWTs para seus users

Você pode usar bibliotecas padrão da indústria para gerar o token, usando o Messenger API Secret como chave secreta. Sua chave secreta pode ser gerada em Configurações > Segurança > Messenger.

Nota: Tokens JWT devem ser gerados exclusivamente para cada sessão de user usando qualquer biblioteca JWT padrão. Tokens devem incluir declarações identificadoras como user_id e ser assinados com o Messenger API Secret para garantir associação segura com o user correto.

Escolha seus frameworks de back e front end para obter exemplos de código relevantes para sua instalação.

Aqui está um exemplo para Node.js:

Se houver atributos adicionais que você queira enviar sobre seus users (ex: price_plan ou number_of_songs_added), você deve adicioná-los também no seu JWT. user_id é o único campo obrigatório. Certifique-se que os nomes dos campos dentro do payload do JWT e atributos são sensíveis a maiúsculas e minúsculas. Por exemplo, "user_id" deve ser escrito com 'i' minúsculo em vez de "user_Id", pois a sensibilidade incorreta pode atrapalhar a identificação correta do user.

Nota: Ao usar o JWK gerado pelo Fin para assinar tokens JWT, a declaração sub padrão é o User ID atribuído pelo Fin e serve como identificador único do user. Isso fornece um mecanismo consistente e seguro para identificação do user. Ao usar o mecanismo JWK, o valor sub é fixo e não pode ser personalizado, garantindo compatibilidade e evitando configurações incorretas.

Passo 3: Adicione JWTs ao seu snippet do Messenger

Ao iniciar o Messenger para um user logado, você pode fornecer um JSON Web Token assinado e atribuí-lo ao atributo intercom_user_jwt do payload do Messenger. Alternativamente, você também pode usar Intercom.setUserJwt(jwt) antes de logar um user para atribuir o token JWT para atribuição segura de dados.

Exemplo de Configuração no Lado do Cliente

  window.Intercom("boot", {
   api_base: "https://api-iam.intercom.io",
   app_id: "APP_ID_CODE",
   intercom_user_jwt: <YOUR_USER_JWT_TOKEN>,
    };

Esse JWT pode conter quaisquer atributos de dados do user que você queira enviar com segurança para o user. Uma vez que um JWT válido seja recebido para o user, um cookie de sessão será criado no navegador do user com duração padrão de 7 dias.

Para controlar o TTL do cookie de sessão do Messenger, você pode definir um máximo no menu suspenso Mantenha seu Messenger seguro em Configurações > Fin Messenger > Geral.

Passo 4: Garanta que atualizações estejam desativadas para seus atributos

É possível habilitar atualizações inseguras para atributos de dados da API do Messenger, o que significa que qualquer atualização via Messenger para atualizar esse atributo terá sucesso.

Se você está enviando alguns dados com segurança no seu JWT, deve garantir que desative atualizações inseguras do Messenger para esses atributos, de modo que sejam atualizados apenas via JWT válido. Nota: esse controle não impede que você colete dados diretamente de leads com um bot

Recomendamos que você habilite esse controle para qualquer atributo que esteja enviando no seu JWT.

Passo 5: Encerrar sessões de usuários ao sair

Você pode instalar o Fin Messenger em qualquer site público que você possua (seu site de marketing, seu site de documentação, seu hub de desenvolvedores, etc). Para manter a continuidade das conversas em todos esses subdomínios diferentes enquanto seus users estiverem logados, definimos um cookie no navegador do usuário. Esse cookie expira após uma semana.

Qualquer user que use um computador e navegador compartilhados com outra pessoa poderá ver o histórico de conversas do user que fez login mais recentemente até que o cookie expire. Por isso, é muito importante encerrar corretamente o Fin Messenger quando a sessão do user no seu app terminar (seja por logout manual ou automático).

Veja como encerrar o Fin Messenger:

Você já terá começado a rastrear seu user via o snippet Intercom JS ou o método “boot”.
Quando seu user fizer logout do Fin Messenger (ou for desconectado automaticamente pelo seu app), chame Intercom('shutdown'); da nossa API JavaScript para encerrar a sessão e limpar o cookie.

Passo final: Aplique a Segurança do Messenger para seu workspace

Quando sua integração estiver enviando JWTs corretamente para seus users, você deve aplicar a segurança do Messenger ativando-a em Configurações > Fin Messenger > Segurança. Fazendo isso, o Fin Messenger exigirá que as requisições para seus users do workspace sejam protegidas com um JWT válido ou um user_hash válido.

Nota: A autenticação JWT é suportada tanto para web quanto para mobile. O SDK mobile está pronto e totalmente funcional na arquitetura Bring Your Own Channel — os passos de configuração deste artigo se aplicam tanto para implementações web quanto mobile.

Orientações para solução de problemas

Temos duas ferramentas para ajudar a depurar sua instalação: uma para ver logs recentes de erros e um depurador de token.

Verifique seus logs de instalação

No passo 6 em Configurações > Fin Messenger > Segurança, você verá seus logs de instalação. Eles mostrarão todos os logs de falhas relacionados à sua instalação JWT. Aqui você verá erros indicando se seus JWTs são inválidos, expirados etc. Clique em "Ver log" para ver um log completo incluindo ID da requisição, timestamp, referer e dados do user. Isso pode ajudar a entender por que sua requisição falhou e rastrear até seu próprio app.

Mensagens de erro comuns

HTTP 400 - "user_hash and intercom_user_jwt cannot be provided simultaneously": A requisição incluiu tanto um JWT quanto um user_hash. Os clientes devem incluir um desses valores, mas não ambos.
HTTP 400 - “Missing user_id in payload”: Todos os JWTs devem incluir user_id como parte do payload. Se um cliente considera “email” seu identificador principal, deve colocar o valor do email tanto no campo user_id quanto no campo email do payload.
HTTP 400 - “Invalid intercom_user_jwt payload”: O payload do JWT é inválido. Os clientes devem garantir que o payload esteja bem formado, codificado e assinado com um SHA256 HMAC usando o valor api_secret como segredo de assinatura.
HTTP 400 - “Intercom_user_jwt expired”: O ‘exp’ do JWT é um timestamp no passado. Os clientes devem fornecer uma data de expiração no futuro.
HTTP 400 - “JWT identity mismatch": O ID do user fornecido no JWT não corresponde ao user associado ao cookie de sessão intercom ativo. Isso indica uma tentativa de iniciar duas sessões concorrentes. Certifique-se de chamar Intercom('shutdown') antes de tentar iniciar um novo user.
HTTP 400 - "Invalid intercom_user_jwt": Certifique-se de estar inicializando um user válido.
Se a verificação do token JWT falhar (por exemplo, por divergência nas claims ou assinatura incorreta), a conversa será automaticamente encerrada e um erro será registrado nos logs de erro da API para ajudar na depuração.

Decodificador JWT

Nossa ferramenta de decodificação também permite verificar um JSON web token. Você pode encontrá-la na barra lateral em Configurações > Messenger > Segurança.

Na ferramenta, você pode verificar um dos seus JWTs de user gerados para validade. Escolha a chave secreta relevante usada para gerar o JWT e clique em Decodificar.

Uma vez decodificado, você pode ver os detalhes do user do payload do seu JWT, o cabeçalho e uma nota indicando se é válido ou inválido.

Neste exemplo, usamos tanto um segredo inválido quanto não incluímos o campo user_id, ambos causarão falha.

Por que recebo um erro 403 Forbidden ao inicializar um user logado com um JWT válido?

Um erro 403 "Requisição proibida" ao inicializar um user logado com um JWT válido ocorre quando a API do Messenger para web está desativada no seu workspace. Enquanto estiver desativada, o Fin Messenger ainda carrega para visitantes anônimos, mas rejeita todos os users logados, mesmo quando o JWT é válido e seu user_id corresponde ao external_id do contato.

Para corrigir o erro 403, vá em Configurações > Canais > Messenger > Instalar e ative a API do Messenger para web (mostrada como "Ativar a API do Messenger"). Depois, inicialize o Fin Messenger novamente com seu JWT.

Perguntas frequentes

Por que o user_id é obrigatório dentro do JWT?

Agora você precisa fornecer user_id como seu identificador principal para users. Historicamente, suportávamos user_id ou email como identificadores potenciais, mas isso causou confusão significativa no produto em Verificação de Identidade básica. Se você só tem um email para identificar seus users, pode fornecer o endereço de email tanto no user_id quanto nos atributos email do payload.

Como configurar isso para users não logados, onde não tenho user_id?

O recurso de segurança do Messenger exige que seus users tenham IDs únicos que você forneça. Se você está usando o Messenger apenas para leads, não pode identificá-los dessa forma. Porém, se você tem users com user_ids no seu workspace de alguma outra integração (REST API, CSV etc), ainda deve ativar a segurança JWT do Messenger para evitar que alguém tente inicializar o Messenger para esses users. Para visitantes deslogados, você pode configurar o messenger para funcionar sem autenticação usando uma versão leve. Basta carregar o script do Messenger apenas com o App ID e evitar passar dados do user ou tokens JWT. Isso garante facilidade de uso mantendo a funcionalidade do sistema e integridade dos dados.

Em resumo, se você tem algum user no seu workspace com identificadores previsíveis (email, user_id), deve ativar a segurança do Messenger. Ao suportar users logados e deslogados, adote uma estratégia mista para segurança e usabilidade. Use autenticação JWT para sessões de users logados para proteger informações sensíveis, enquanto permite que visitantes deslogados usem uma configuração simplificada do messenger sem tokens ou dados específicos do user.

Qual deve ser o tempo de expiração?

Você deve enviar um novo JWT toda vez que o Messenger for inicializado, então a duração do token só precisa suportar o tempo entre os lançamentos do Messenger. Escolha a duração mínima adequada ao comportamento da aplicação. Se a página web for recarregada frequentemente, o JWT deve ser de curta duração, embora sugerimos um mínimo de 5 minutos para evitar problemas de expiração inesperada. Sempre inclua uma claim de expiração (exp) nos seus JWTs para garantir segurança reduzindo o impacto de tokens roubados.

Qual algoritmo de assinatura posso usar?

Nós suportamos:

HS256 (HMAC com SHA-256). Este algoritmo usa uma chave secreta compartilhada para assinar e verificar o token, garantindo que os dados dentro do token não foram adulterados.
RS256 para JWTs, que usa um par de chaves assimétricas - privada para assinatura e pública para verificação, oferecendo uma alternativa para segurança aprimorada.
Configurações JSON Web Key (JWK), que permitem integração perfeita com chaves geradas pela Fin para gerenciamento simplificado de tokens.

Posso enviar tanto user_hash quanto intercom_user_jwt?

Não, não suportamos enviar ambos user_hash e intercom_user_jwt, pois o `user_hash` deve ser substituído pelos JWTs. No entanto, você pode alternar entre enviar user_hashes e/ou valores intercom_user_jwt, pois alguns clientes precisarão fazer isso enquanto migram de user_hash para intercom_user_jwt.

Como posso verificar se meus JWTs são válidos e se tudo está funcionando?

Veja a seção de solução de problemas acima.

Como faço para aplicar a exigência de JWTs para meu workspace?

Você deve ativar o toggle de aplicação nas configurações do Messenger.

Quais atributos devo proteger?

Todos os atributos identificadores devem ser marcados como protegidos e enviados com segurança no JWT, se possível. Isso inclui email, telefone e quaisquer account_ids que o cliente possa armazenar no registro do User. Você pode encontrar seus atributos em Configurações > Dados de Pessoas.

Qualquer atributo que você queira que o Fin use em uma parte crítica de uma Ação ou Workflow deve ser protegido, para garantir que um usuário malicioso não possa substituir esse valor.

Se você quiser enviar dados fora do JWT, pode fazer isso desde que tenha permitido atualizações do Messenger, mas lembre-se de que um usuário pode atualizar esse campo por conta própria.

    window.intercomSettings = {
      app_id: <APP_ID_CODE>,
      intercom_user_jwt: <TOKEN>,
      unsigned_data_attribute: 'data'
    };

E se a sessão expirar no meio do uso pelo usuário?

Se houver atividade no Messenger por um usuário após o cookie expirar, ele emitirá um cookie novo e de curta duração de 1 hora para evitar impacto negativo na experiência do usuário. Para evitar efeitos indesejados na experiência do usuário, recomendamos que você escolha uma duração de sessão do cookie que corresponda ao tempo limite da sessão do seu aplicativo.

Por que não exigimos que toda a carga útil seja assinada?

Permitimos que você envie atributos não assinados para suportar situações em que é necessário enviar dados de baixa fidelidade sobre o usuário, enquanto o usuário está realizando uma ação no seu aplicativo. Se você não precisa dessa capacidade, pode atualizar todos os seus Atributos de Dados do Usuário para serem “protegidos contra atualizações do Messenger” e enviar apenas a carga útil assinada.

Como gerencio e rotaciono minhas chaves secretas do Messenger?

Sua chave secreta pode ser gerada nas configurações de segurança do Messenger do seu workspace.

Você pode encontrar e copiar suas chaves existentes na barra lateral direita da página de configuração do JWT.
Você pode rotacionar chaves em Configurações > Segurança > Messenger.

Se você conectou mais de um ambiente Salesforce, pode atribuir uma chave a um ambiente quando criá-la em Configurações > Segurança > Messenger. Uma chave atribuída a um ambiente só verifica usuários em solicitações do Messenger desse ambiente. Deixe em Todos os ambientes para manter o comportamento atual. As chaves existentes permanecem não atribuídas e continuam funcionando em todos os ambientes. O ambiente de uma chave é fixo quando você a cria: para mover uma chave para um ambiente diferente, crie uma nova chave e revogue a antiga. Para atribuir um ambiente ao criar uma chave via REST API, passe environment_id na versão Preview da API. Veja Identity Verification Secrets na documentação para desenvolvedores.

O que aconteceu com a Identity Verification? Os JWTs substituem isso?

Identity Verification é a iteração anterior da Segurança do Messenger que funciona usando hashes HMAC do usuário para identificar que uma solicitação do usuário foi enviada pela sua integração.

Embora os user_hashes continuem sendo aceitos, recomendamos fortemente que todos os clientes façam upgrade para usar JWTs, pois oferecem mais benefícios de segurança e a Identity Verification não receberá atualizações futuras.

Se você precisar gerenciar sua instalação de Identity Verification a partir das páginas do JWT, ainda pode. As instruções foram atualizadas para refletir a configuração do JWT e, se você estiver fazendo alterações, recomendamos fortemente que migre para JWTs, mas se precisar desativar o recurso ou rotacionar suas chaves secretas da API do Messenger, ainda pode fazer isso em Configurações > Segurança > Messenger.

Posso incluir dados da empresa no meu JWT para associar usuários a uma empresa?

Sim. Inclua company_id e outros atributos da empresa na carga útil do seu JWT para associar usuários a uma empresa. Isso criará e associará automaticamente a empresa no momento da inicialização, sem latência adicional.

Importante: Dados da empresa passados fora do JWT (por exemplo, como um objeto company na sua chamada Intercom('boot')) são ignorados quando um JWT está presente. A empresa não será atualizada e o valor last_seen da empresa não será atualizado. Para garantir que os dados da empresa sejam atualizados corretamente, inclua-os na carga útil do seu JWT.

Autenticando users no Fin Messenger com JSON web tokens (JWTs)