Comprender y gestionar los IDs de usuario

Para gestionar eficazmente a tus clientes, Intercom utiliza dos tipos de IDs: el Intercom ID y el user_id. Entender cómo funcionan juntos es esencial para mantener la integridad de los datos y asegurar una identificación precisa del cliente.

El Intercom ID

El Intercom ID es un identificador que nuestro sistema genera automáticamente para cada registro de cliente. Este ID es constante y no puede ser cambiado. En nuestra API, a menudo se le llama contact_id.

El user_id personalizado (ID externo)

El user_id es un identificador personalizable que puedes configurar para que coincida con la clave primaria o ID único de tu propia base de datos. Ofrece una forma flexible de integrar Intercom con tus sistemas externos y puede actualizarse vía API.

Mejores prácticas para gestionar los IDs de usuario

Seguir estas mejores prácticas te ayudará a evitar problemas comunes de datos como registros duplicados o conversaciones fusionadas.

Asignar un identificador único y consistente

Siempre debes asignar un user_id único para cada cliente, típicamente la clave primaria de tus propios registros de base de datos. Es crucial usar este mismo user_id para todas las interacciones futuras y actualizaciones de perfil de ese cliente específico.

Evita pasar diferentes user_ids para la misma dirección de correo electrónico, ya que esto creará registros duplicados de clientes.

Importante:

Usar user_ids inconsistentes o superpuestos puede causar graves problemas de integridad de datos, como inicios de sesión cruzados entre cuentas y conversaciones fusionadas entre diferentes clientes.
El valor -1 está reservado por el sistema de Intercom para fines internos y no debe usarse como user_id. Usar este valor puede causar comportamientos inesperados, como conversaciones asociadas incorrectamente con el perfil de usuario equivocado. Si usas -1 como user_id, a menudo se usa como valor predeterminado o marcador de posición. Esto significa que si un usuario lo tiene, ya no es único y puede causar problemas.

Usa IDs de usuario globalmente únicos en configuraciones multi-inquilino

Los valores de user_id enviados a Intercom deben ser globalmente únicos en todo tu espacio de trabajo. En configuraciones multi-inquilino — donde múltiples inquilinos u organizaciones comparten el mismo espacio de trabajo de Intercom — los user_ids que solo son únicos dentro de un solo inquilino pueden colisionar entre inquilinos, causando que clientes separados se fusionen en el mismo registro de contacto de Intercom.

Para evitar esto, antepone un identificador de inquilino a los valores de user_id antes de enviarlos a Intercom. Por ejemplo, en lugar de enviar "user_123", envía "tenant_abc:user_123".

Nota: Habilitar la autenticación JWT también es necesario para evitar colisiones de registros de usuario y asegurar una identificación segura. Sin ella, un actor malintencionado puede suplantar a otro usuario suministrando su user_id, lo que puede resultar en acceso no autorizado al historial de conversaciones y datos del espacio de trabajo. Los valores de user_id globalmente únicos previenen fusiones accidentales de registros, mientras que la autenticación JWT previene la suplantación deliberada.

Evita usar valores predeterminados o marcadores de posición

Nunca asignes valores predeterminados como "undefined" ni uses el mismo user_id para múltiples clientes. Esto causará errores de datos y te impedirá identificar correctamente a clientes individuales.

Rellenar o actualizar los IDs de usuario

Si necesitas actualizar un registro de cliente que previamente tenía un user_id desconocido, puedes agregar el identificador correcto más tarde.

Consejo profesional: Puedes consultar tu propia base de datos para encontrar el user_id correcto y luego actualizar el registro del cliente en Intercom usando una importación CSV o nuestra API.

Paso a paso: actualizar un user_id mediante el Intercom ID

Usa el endpoint Search for a Contact para encontrar el contacto por correo electrónico u otro atributo conocido.
Anota el campo id en la respuesta — este es el Intercom ID permanente del contacto.
Busca el user_id correcto en tu propia base de datos.
Llama al endpoint Update a Contact, pasando el Intercom ID (id) y el user_id correcto.

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

Importante: Siempre usa el Intercom ID (id) — no el correo electrónico ni un user_id existente — al dirigirte a un contacto para una actualización. Esto asegura que actualices el registro correcto, incluso cuando el contacto no tiene user_id asignado o tiene uno incorrecto.

Evitar que las integraciones establezcan user_ids incorrectos

Integraciones como sincronizaciones CRM, herramientas analíticas y pipelines de datos pueden establecer user_ids incorrectos inadvertidamente. Las causas comunes incluyen:

Mapear un ID de sesión, cookie o token temporal en lugar de una clave primaria estable de base de datos
Enviar null, undefined, 0 o -1 como valores marcadores de posición cuando un cliente no está autenticado
Usar una dirección de correo electrónico en el campo user_id (los correos pueden cambiar, rompiendo la continuidad del contacto)
Diferentes integraciones enviando diferentes user_ids para el mismo cliente

Para evitar esto:

Audita tus mapeos de integración — confirma qué campo en tu sistema se mapea a user_id en Intercom. Debe ser la clave primaria de tu base de datos para cada cliente.
Valida antes de enviar — asegúrate de que user_id no sea nulo, vacío ni un valor reservado (como -1 o undefined) antes de pasarlo a Intercom.
Usa una única fuente de verdad — si múltiples integraciones envían datos a Intercom, asegúrate de que todas usen el mismo identificador estable del cliente.
Prueba con registros conocidos — después de configurar una integración, usa el endpoint Search for a Contact para verificar que los user_ids de algunos clientes coincidan con tu base de datos.

Gestionar los IDs de usuario con la API

Puedes usar la API de Intercom para realizar varias acciones clave para gestionar los IDs de tus clientes. Para detalles completos, consulta nuestro Developer Hub.

Recuperar, actualizar o buscar un contacto

Recuperar un contacto: Consulta los detalles de un cliente usando su Intercom ID (id) o tu user_id personalizado con el endpoint Retrieve a Contact.
Actualizar un contacto: Establece o corrige un user_id usando el endpoint Update a Contact.
Buscar un contacto: Valida identificadores como user_id o correo electrónico usando el endpoint Search for a Contact.

Auditoría de tus integraciones

Las auditorías regulares te ayudan a detectar user_ids incorrectos antes de que causen problemas de integridad de datos. Sigue estos pasos para auditar tus integraciones y asegurar que todos los contactos tengan el user_id correcto y estable.

Identifica contactos con user_ids faltantes o sospechosos — usa el endpoint Search for a Contact para consultar contactos donde user_id esté vacío o contenga un valor marcador de posición conocido (como -1 o undefined). También puedes exportar tu lista de contactos desde Intercom y filtrar anomalías.
Rastrea la fuente de cada user_id — para cada contacto marcado, identifica qué integración estableció el user_id por última vez. Revisa tus registros de integración o historial de eventos para confirmar el origen del valor.
Corrige el user_id usando el Intercom ID — busca el user_id correcto en tu propia base de datos, luego usa el endpoint Update a Contact con el Intercom ID del contacto para establecer el valor correcto. Consulta Rellenar o actualizar los IDs de usuario para el proceso paso a paso.
Corrige la configuración de la integración — actualiza la integración para mapear al identificador correcto y estable de ahora en adelante. Para herramientas de terceros, revisa la configuración de mapeo de campos y actualízala para que apunte a la clave primaria de tu base de datos.
Valida después de la corrección — vuelve a buscar los contactos actualizados para confirmar que user_id ahora refleja el valor correcto y monitorea nuevas ocurrencias en los días siguientes.

Asegurar la identificación correcta con autenticación JWT

Para asegurar una autenticación robusta para clientes conectados, es mejor usar la clave primaria de tu base de datos como user_id en la carga útil del JSON Web Token (JWT).

Si solo tienes una dirección de correo electrónico para identificar a un cliente, debes llenar tanto los atributos user_id como email en la carga útil del JWT con la dirección de correo electrónico del cliente.

Solución de problemas comunes de IDs de usuario

Archivando un user_id personalizado

Si archivas un atributo user_id personalizado, el campo user_id predeterminado de Intercom no se actualizará automáticamente con esos datos. Será necesario un relleno manual para actualizar los registros.

Manejo de registros duplicados

Los valores inconsistentes de user_id también pueden causar que la actividad de un solo visitante — incluyendo vistas de página — se divida entre múltiples registros de contacto. Esta fragmentación de contacto significa que algunas vistas de página no aparecerán en el contacto que esperas, por ejemplo en la app de Vistas de página recientes.

Si encuentras registros duplicados causados por asociaciones incorrectas entre user_id y correo electrónico, deberás limpiar los registros manualmente o usando la API para fusionarlos o eliminarlos.

Cambiar de un user_id personalizado al ID predeterminado

Si necesitas actualizar el campo de tu base de datos de usuarios, consulta con tu desarrollador sobre cómo usar la API de Intercom o usa el flujo de importación CSV.