Entendendo e gerenciando IDs de usuários

Para gerenciar seus clientes de forma eficaz, o Intercom usa dois tipos de IDs: o Intercom ID e o user_id. Entender como eles funcionam juntos é essencial para manter a integridade dos dados e garantir a identificação precisa do cliente.

O Intercom ID

O Intercom ID é um identificador gerado automaticamente pelo nosso sistema para cada registro de cliente. Esse ID é constante e não pode ser alterado. Em nossa API, ele é frequentemente chamado de contact_id.

O user_id personalizado (ID externo)

O user_id é um identificador personalizável que você pode definir para corresponder à chave primária ou ID único do seu próprio banco de dados. Ele oferece uma forma flexível de integrar o Intercom com seus sistemas externos e pode ser atualizado via API.

Melhores práticas para gerenciar IDs de usuários

Seguir essas melhores práticas ajudará a evitar problemas comuns de dados, como registros duplicados ou conversas mescladas.

Atribua um identificador único e consistente

Você deve sempre atribuir um user_id único para cada cliente, tipicamente a chave primária dos seus próprios registros de banco de dados. É crucial usar esse mesmo user_id para todas as interações futuras e atualizações de perfil desse cliente específico.

Evite passar diferentes user_ids para o mesmo endereço de e-mail, pois isso criará registros duplicados de clientes.

Importante:

Usar user_ids inconsistentes ou sobrepostos pode causar sérios problemas de integridade dos dados, como logins cruzados entre contas e conversas mescladas entre clientes diferentes.
O valor -1 é reservado pelo sistema do Intercom para fins internos e não deve ser usado como user_id. Usar esse valor pode causar comportamentos inesperados, como conversas associadas incorretamente ao perfil errado do usuário. Se você usar -1 como user_id, ele geralmente é usado como valor padrão ou marcador. Isso significa que, se um usuário o possui, ele não é mais único e pode causar problemas.

Use IDs de usuário globalmente únicos em configurações multi-tenant

Os valores de user_id enviados ao Intercom devem ser globalmente únicos em todo o seu workspace. Em configurações multi-tenant — onde múltiplos tenants ou organizações compartilham o mesmo workspace do Intercom — IDs de usuário que são únicos apenas dentro de um único tenant podem colidir entre tenants, fazendo com que clientes diferentes sejam mesclados no mesmo registro de contato do Intercom.

Para evitar isso, prefixe os valores de user_id com um identificador do tenant antes de enviá-los ao Intercom. Por exemplo, em vez de enviar "user_123", envie "tenant_abc:user_123".

Nota: Ativar a autenticação JWT também é necessário para evitar colisões de registros de usuários e garantir identificação segura. Sem isso, um agente malicioso pode se passar por outro usuário fornecendo seu user_id, o que pode resultar em acesso não autorizado ao histórico de conversas e dados do workspace. Valores de user_id globalmente únicos previnem mesclagens acidentais de registros, enquanto a autenticação JWT previne impersonações deliberadas.

Evite usar valores padrão ou marcadores

Nunca atribua valores padrão como "undefined" ou use o mesmo user_id para múltiplos clientes. Isso levará a erros de dados e impedirá a identificação correta dos clientes individuais.

Preenchendo ou atualizando IDs de usuários

Se precisar atualizar um registro de cliente que anteriormente tinha um user_id desconhecido, você pode adicionar o identificador correto depois.

Dica profissional: Você pode consultar seu próprio banco de dados para encontrar o user_id correto e então atualizar o registro do cliente no Intercom usando uma importação CSV ou nossa API.

Passo a passo: atualizando um user_id via Intercom ID

Use o endpoint Search for a Contact para encontrar o contato pelo e-mail ou outro atributo conhecido.
Anote o campo id na resposta — este é o Intercom ID permanente do contato.
Procure o user_id correto no seu próprio banco de dados.
Chame o endpoint Update a Contact, passando o Intercom ID (id) e o user_id correto.

{
  "id": "contact_intercom_id",
  "user_id": "your_stable_database_id"
}

Importante: Sempre use o Intercom ID (id) — não o e-mail ou um user_id existente — ao direcionar um contato para atualização. Isso garante que você atualize o registro correto, mesmo quando o contato não tem user_id definido ou tem um incorreto.

Evitando que integrações definam user_ids incorretos

Integrações como sincronizações de CRM, ferramentas de análise e pipelines de dados podem definir user_ids incorretos inadvertidamente. Causas comuns incluem:

Mapear um session ID, cookie ou token temporário em vez de uma chave primária estável do banco de dados
Enviar null, undefined, 0 ou -1 como valores marcadores quando um cliente não está autenticado
Usar um endereço de e-mail no campo user_id (e-mails podem mudar, quebrando a continuidade do contato)
Diferentes integrações enviando user_ids diferentes para o mesmo cliente

Para evitar isso:

Audite seus mapeamentos de integração — confirme qual campo no seu sistema mapeia para user_id no Intercom. Deve ser a chave primária do seu banco de dados para cada cliente.
Valide antes de enviar — assegure que user_id não seja nulo, vazio ou um valor reservado (como -1 ou undefined) antes de ser enviado ao Intercom.
Use uma única fonte de verdade — se múltiplas integrações enviam dados ao Intercom, garanta que todas usem o mesmo identificador estável do cliente.
Teste com registros conhecidos — após configurar uma integração, use o endpoint Search for a Contact para verificar se os user_ids de alguns clientes correspondem ao seu banco de dados.

Gerenciando IDs de usuários com a API

Você pode usar a API do Intercom para realizar várias ações importantes para gerenciar seus IDs de clientes. Para detalhes completos, veja nosso Developer Hub.

Recuperando, atualizando ou buscando um contato

Recuperar um contato: Consulte os detalhes de um cliente usando seu Intercom ID (id) ou seu user_id personalizado com o endpoint Retrieve a Contact.
Atualizar um contato: Defina ou corrija um user_id usando o endpoint Update a Contact.
Buscar um contato: Valide identificadores como user_id ou e-mail usando o endpoint Search for a Contact.

Auditando suas integrações

Auditorias regulares ajudam a detectar user_ids incorretos antes que causem problemas de integridade dos dados. Siga estes passos para auditar suas integrações e garantir que todos os contatos tenham o user_id correto e estável.

Identifique contatos com user_ids ausentes ou suspeitos — use o endpoint Search for a Contact para consultar contatos onde user_id está em branco ou contém um valor marcador conhecido (como -1 ou undefined). Você também pode exportar sua lista de contatos do Intercom e filtrar por anomalias.
Rastreie a origem de cada user_id — para cada contato sinalizado, identifique qual integração definiu o user_id por último. Verifique seus logs de integração ou histórico de eventos para confirmar a origem do valor.
Corrija o user_id usando o Intercom ID — procure o user_id correto no seu próprio banco de dados, depois use o endpoint Update a Contact com o Intercom ID do contato para definir o valor correto. Veja Preenchendo ou atualizando IDs de usuários para o processo passo a passo.
Corrija a configuração da integração — atualize a integração para mapear para o identificador correto e estável daqui para frente. Para ferramentas de terceiros, verifique as configurações de mapeamento de campo e atualize para apontar para a chave primária do seu banco de dados.
Valide após a correção — pesquise novamente os contatos atualizados para confirmar que o user_id agora reflete o valor correto, e monitore novas ocorrências nos dias seguintes.

Garantindo identificação correta com autenticação JWT

Para garantir autenticação robusta para clientes logados, é recomendável usar a chave primária do seu banco de dados como user_id no payload do JSON Web Token (JWT).

Se você só tem um endereço de e-mail para identificar um cliente, deve preencher tanto os atributos user_id quanto email no payload do JWT com o endereço de e-mail do cliente.

Solução de problemas comuns de erros de ID de usuário

Arquivando um user_id personalizado

Se você arquivar um atributo user_id personalizado, o campo user_id padrão do Intercom não será atualizado automaticamente com esses dados. Será necessário um preenchimento manual para atualizar os registros.

Lidando com registros duplicados

Valores inconsistentes de user_id também podem causar que a atividade de um único visitante — incluindo visualizações de página — seja dividida entre múltiplos registros de contato. Essa fragmentação de contato significa que algumas visualizações de página não aparecerão no contato esperado, por exemplo, no app Recent page views.

Se você encontrar registros duplicados causados por associações incorretas entre user_id e e-mail, será necessário limpar os registros manualmente ou usando a API para mesclá-los ou excluí-los.

Mudando de um user_id personalizado para o ID padrão

Se precisar atualizar o campo do seu banco de dados de usuários, consulte seu desenvolvedor sobre como usar a API do Intercom ou utilize o fluxo de importação CSV.