Comprendre et gérer les identifiants utilisateur

Pour gérer efficacement vos clients, Intercom utilise deux types d'IDs : l'ID Intercom et le user_id. Comprendre leur fonctionnement conjoint est essentiel pour maintenir l'intégrité des données et assurer une identification client précise.

L'ID Intercom

L'ID Intercom est un identifiant généré automatiquement par notre système pour chaque fiche client. Cet ID est constant et ne peut pas être modifié. Dans notre API, il est souvent appelé contact_id.

Le user_id personnalisé (ID externe)

Le user_id est un identifiant personnalisable que vous pouvez définir pour correspondre à la clé primaire ou à l'ID unique de votre propre base de données. Il offre une manière flexible d'intégrer Intercom à vos systèmes externes et peut être mis à jour via l'API.

Meilleures pratiques pour gérer les identifiants utilisateur

Suivre ces meilleures pratiques vous aidera à éviter des problèmes courants de données comme les doublons ou les conversations fusionnées.

Attribuer un identifiant unique et cohérent

Vous devez toujours attribuer un user_id unique pour chaque client, généralement la clé primaire de vos propres enregistrements de base de données. Il est crucial d'utiliser ce même user_id pour toutes les interactions futures et mises à jour de profil de ce client spécifique.

Évitez de passer différents user_ids pour la même adresse email, car cela créera des doublons dans les fiches clients.

Important :

Utiliser des user_ids incohérents ou qui se chevauchent peut causer de graves problèmes d'intégrité des données, comme des connexions inter-comptes et des conversations fusionnées entre différents clients.
La valeur -1 est réservée par le système d'Intercom à des fins internes et ne doit pas être utilisée comme user_id. Son utilisation peut provoquer des comportements inattendus, comme des conversations associées incorrectement à un mauvais profil utilisateur. Si vous utilisez -1 comme user_id, c'est souvent une valeur par défaut ou un espace réservé. Cela signifie que si un utilisateur l'a, ce n'est plus unique et cela peut causer des problèmes.

Utilisez des user_ids globalement uniques dans les environnements multi-tenant

Les valeurs user_id envoyées à Intercom doivent être globalement uniques dans tout votre espace de travail. Dans les environnements multi-tenant — où plusieurs locataires ou organisations partagent le même espace Intercom — des user_ids uniques seulement au sein d'un locataire peuvent entrer en collision entre locataires, fusionnant ainsi des clients distincts dans la même fiche contact Intercom.

Pour éviter cela, préfixez les valeurs user_id avec un identifiant de locataire avant de les envoyer à Intercom. Par exemple, au lieu d'envoyer « user_123 », envoyez « tenant_abc:user_123 ».

Note : Activer l'authentification JWT est également nécessaire pour éviter les collisions de fiches utilisateur et garantir une identification sécurisée. Sans cela, un acteur malveillant peut usurper l'identité d'un autre utilisateur en fournissant son user_id, ce qui peut entraîner un accès non autorisé à l'historique des conversations et aux données de l'espace de travail. Des user_ids globalement uniques empêchent les fusions accidentelles, tandis que l'authentification JWT empêche l'usurpation délibérée.

Évitez d'utiliser des valeurs par défaut ou des espaces réservés

N'attribuez jamais de valeurs par défaut comme « undefined » ou n'utilisez pas le même user_id pour plusieurs clients. Cela entraînera des erreurs de données et vous empêchera d'identifier correctement chaque client.

Compléter ou mettre à jour les user_ids

Si vous devez mettre à jour une fiche client qui avait auparavant un user_id inconnu, vous pouvez ajouter l'identifiant correct ultérieurement.

Astuce : Vous pouvez consulter votre propre base de données pour trouver le user_id correct, puis mettre à jour la fiche client dans Intercom via une importation CSV ou notre API.

Étape par étape : mise à jour d'un user_id via l'ID Intercom

Utilisez le point de terminaison Search for a Contact pour trouver le contact par email ou un autre attribut connu.
Notez le champ id dans la réponse — c'est l'ID Intercom permanent du contact.
Recherchez le user_id correct dans votre propre base de données.
Appelez le point de terminaison Update a Contact, en passant l'ID Intercom (id) et le user_id correct.

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

Important : Utilisez toujours l'ID Intercom (id) — pas l'email ni un user_id existant — pour cibler un contact lors d'une mise à jour. Cela garantit que vous modifiez la bonne fiche, même si le contact n'a pas de user_id défini ou en a un incorrect.

Empêcher les intégrations de définir des user_ids incorrects

Les intégrations comme les synchronisations CRM, les outils d'analyse et les pipelines de données peuvent involontairement définir des user_ids incorrects. Les causes courantes incluent :

Mapper un ID de session, un cookie ou un jeton temporaire au lieu d'une clé primaire stable de base de données
Envoyer null, undefined, 0 ou -1 comme valeurs d'espace réservé quand un client n'est pas authentifié
Utiliser une adresse email dans le champ user_id (les emails peuvent changer, rompant la continuité du contact)
Différentes intégrations envoyant différents user_ids pour le même client

Pour éviter cela :

Auditez vos mappings d'intégration — confirmez quel champ dans votre système correspond à user_id dans Intercom. Il doit s'agir de la clé primaire de votre base de données pour chaque client.
Validez avant d'envoyer — assurez-vous que user_id n'est pas nul, vide, ni une valeur réservée (comme -1 ou undefined) avant qu'il soit transmis à Intercom.
Utilisez une source unique de vérité — si plusieurs intégrations envoient des données à Intercom, assurez-vous qu'elles utilisent toutes le même identifiant client stable.
Testez avec des enregistrements connus — après avoir configuré une intégration, utilisez le point de terminaison Search for a Contact pour vérifier que les user_ids de quelques clients correspondent à votre base de données.

Gérer les user_ids avec l'API

Vous pouvez utiliser l'API d'Intercom pour effectuer plusieurs actions clés pour gérer vos IDs clients. Pour plus de détails, consultez notre Developer Hub.

Récupérer, mettre à jour ou rechercher un contact

Récupérer un contact : Recherchez les détails d'un client en utilisant son ID Intercom (id) ou votre user_id personnalisé avec le point de terminaison Retrieve a Contact.
Mettre à jour un contact : Définissez ou corrigez un user_id en utilisant le point de terminaison Update a Contact.
Rechercher un contact : Validez des identifiants comme user_id ou email en utilisant le point de terminaison Search for a Contact.

Auditer vos intégrations

Des audits réguliers vous aident à détecter les user_ids incorrects avant qu'ils ne causent des problèmes d'intégrité des données. Suivez ces étapes pour auditer vos intégrations et garantir que tous les contacts ont le user_id correct et stable.

Identifiez les contacts avec des user_ids manquants ou suspects — utilisez le point de terminaison Search for a Contact pour interroger les contacts où user_id est vide ou contient une valeur d'espace réservé connue (comme -1 ou undefined). Vous pouvez aussi exporter votre liste de contacts depuis Intercom et filtrer les anomalies.
Tracez la source de chaque user_id — pour chaque contact signalé, identifiez quelle intégration a défini en dernier le user_id. Vérifiez vos journaux d'intégration ou l'historique des événements pour confirmer l'origine de la valeur.
Corrigez le user_id en utilisant l'ID Intercom — recherchez le user_id correct dans votre propre base de données, puis utilisez le point de terminaison Update a Contact avec l'ID Intercom du contact pour définir la bonne valeur. Voir Compléter ou mettre à jour les user_ids pour le processus étape par étape.
Corrigez la configuration de l'intégration — mettez à jour l'intégration pour qu'elle corresponde à l'identifiant stable et correct à l'avenir. Pour les outils tiers, vérifiez les paramètres de mapping des champs et mettez-les à jour pour pointer vers la clé primaire de votre base de données.
Validez après correction — recherchez à nouveau les contacts mis à jour pour confirmer que user_id reflète maintenant la bonne valeur, et surveillez les nouvelles occurrences dans les jours suivants.

Assurer une identification correcte avec l'authentification JWT

Pour garantir une authentification robuste des clients connectés, il est recommandé d'utiliser la clé primaire de votre base de données comme user_id dans la charge utile JSON Web Token (JWT).

Si vous ne disposez que d'une adresse email pour identifier un client, vous devez remplir à la fois les attributs user_id et email dans la charge utile JWT avec l'adresse email du client.

Dépannage des erreurs courantes liées aux user_ids

Archivage d'un user_id personnalisé

Si vous archivez un attribut user_id personnalisé, le champ user_id Intercom par défaut ne sera pas automatiquement mis à jour avec ces données. Un remplissage manuel sera nécessaire pour mettre à jour les enregistrements.

Gestion des doublons

Des valeurs user_id incohérentes peuvent aussi provoquer la fragmentation de l'activité d'un visiteur unique — y compris les vues de pages — répartie sur plusieurs fiches contact. Cette fragmentation signifie que certaines vues de pages n'apparaîtront pas sur le contact attendu, par exemple dans l'application Vues de pages récentes.

Si vous trouvez des doublons causés par des associations user_id et email incorrectes, vous devrez nettoyer les fiches manuellement ou en utilisant l'API pour les fusionner ou les supprimer.

Passer d'un user_id personnalisé à l'ID par défaut

Si vous devez mettre à jour votre champ de base de données utilisateur, consultez votre développeur sur la manière d'utiliser l'API Intercom ou utilisez le workflow d'importation CSV.