Se você deseja usar o Intercom como chat de suporte no seu aplicativo White-Label, siga este guia para conectar e proteger seu workspace adequadamente.
1. Cadastre-se no Programa Intercom para Startups
Para começar, você precisa de:
-
APP_ID
-
A maneira mais fácil de encontrar o ID do seu workspace é na URL de qualquer página do Intercom. Por exemplo:
https://app.intercom.io/a/inbox/xyz123/inbox/admin
Aqui, xyz123 é o seu APP_ID.
-
Alternativamente, navegue até: Configurações > Instalação > Web > Instalar chat para visitantes > Com código
-
Chave Secreta
-
Necessária para a segurança do Messenger (veja abaixo).
2. Proteja Seu Messenger com JWTs
JSON Web Tokens (JWTs) são a forma recomendada de proteger seu Messenger. Eles previnem acesso não autorizado, falsificação de identidade ou vazamento de dados.
Como funciona:
-
JWTs são gerados no lado do servidor com base em:
-
user_id(obrigatório) -
Payload opcional com dados adicionais do usuário
-
Chave Secreta da API do Messenger
-
O Intercom usa o JWT para verificar a identidade do usuário em cada sessão.
Por que usar JWTs:
- Previne que pessoas mal-intencionadas acessem conversas.
- Garante que apenas usuários autenticados possam interagir com seu Messenger.
- Fortemente recomendado para todas as instalações.
Já está usando Verificação de Identidade HMAC? Consulte o guia de migração para mudar para JWT e obter segurança aprimorada.
3. Configurando a Segurança do Messenger
Você pode habilitar, desabilitar ou ajustar a Segurança do Messenger no Intercom:
- Acesse Configurações do Intercom para Web
- Siga as instruções e exemplos de código para sua linguagem/framework.
- Nota: Desabilitar esse recurso durante o desenvolvimento é possível, mas torna seu workspace vulnerável.
Melhores Práticas para Implementação de JWT
-
Expiração do Token
-
Defina o tempo de vida do token de acordo com a duração da sessão do seu aplicativo.
-
Tokens com vida mais curta melhoram a segurança.
-
Atualização do Token
-
Forneça tokens atualizados periodicamente, especialmente se as informações do usuário mudarem.
-
Rotação de Chaves Secretas
-
Suas chaves secretas da API do Messenger estão em: Workspace > Segurança > Messenger
-
Copie as chaves existentes ou faça a rotação delas para maior segurança.
4. Opções de Verificação de Identidade
- Recomendado: Verificação baseada em JWT
- Suporte legado: Verificação de Identidade baseada em HMAC
- Dica: Mude para JWT em todas as novas integrações.
5. Solução de Problemas
Problemas comuns e soluções:
-
Messenger não funciona em todos os lugares: Certifique-se de que a Segurança do Messenger está habilitada em todas as plataformas (web, iOS, Android).
-
Erros na geração do JWT:
-
Sempre use o user_id do usuário para a criação do token.
-
Use a chave secreta correta das configurações do seu workspace.
-
Evite expor sua chave secreta em código público/frontend. Se vazar, faça a rotação imediatamente.
-
Depuração:
-
Verifique os logs detalhados na página de configuração.
-
Use o depurador de token para problemas com JWTs.
6. Pontos-Chave
- Sempre proteja seu Intercom Messenger com JWTs.
- Use o APP_ID e a chave secreta corretamente em todas as plataformas.
- Faça a rotação das chaves secretas regularmente e atualize os tokens JWT quando necessário.
- Teste o Messenger em todos os dispositivos (web, iOS, Android) para garantir funcionalidade consistente.
- Use as ferramentas e logs do Intercom para solução de problemas.
✅ Com essa configuração, sua integração com o Intercom estará segura, consistente e pronta para dar suporte aos usuários do seu aplicativo White-Label com segurança.