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 dos clientes.

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, isso é 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 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 de posição. Isso significa que, se um usuário o tiver, ele não será mais único e pode causar problemas.

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

Os valores de user_id enviados para o Intercom devem ser globalmente únicos em todo o seu workspace. Em configurações multi-tenant — onde vários tenants ou organizações compartilham o mesmo workspace do Intercom — IDs de usuários 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 para o 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 mal-intencionado 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 evitam mesclagens acidentais de registros, enquanto a autenticação JWT previne impersonações deliberadas.

Evite usar valores padrão ou marcadores de posição

Nunca atribua valores padrão como "undefined" ou use o mesmo user_id para vários clientes. Isso levará a erros de dados e impedirá que você identifique corretamente clientes individuais.

Preenchendo ou atualizando IDs de usuários

Se você precisar atualizar um registro de cliente que anteriormente tinha um user_id desconhecido, 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.

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 Recuperar um Contato.
Atualizar um contato: Defina ou corrija um user_id usando o endpoint Atualizar um Contato.
Buscar um contato: Valide identificadores como user_id ou e-mail usando o endpoint Buscar um Contato.

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

Para garantir autenticação robusta para clientes logados, é melhor 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.

Resolvendo erros comuns de user ID

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

Se você encontrar registros duplicados causados por associações incorretas entre user_id e e-mail, precisará 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 banco de dados do usuário, consulte seu desenvolvedor sobre como usar a API do Intercom ou utilize o fluxo de importação CSV.