Notifications & synchronisation Intercom
Notifications & synchronisation — Intercom
Envoyer et synchroniser les informations apps/utilisateurs vers Intercom pour un support et un suivi client plus efficace
Centralisez le contexte client (apps, incidents, licences) dans Intercom pour accélérer le support, l’onboarding et les relances commerciales.
Capacités clés
Synchroniser Apps → Companies
Envoyer les informations d’une app (nom, identifiant, plan, statut, nombre d’utilisateurs actifs, licence/tier, facturation à venir, métriques) en tant que company dans Intercom pour donner du contexte à l’équipe support. Les champs envoyés sont maintenant normalisés : les métadonnées principales de l’app sont transmises en tant qu’attributs de company (par ex. name, external_id (mappé depuis app_id), plan, status, users_count, tier, billing_next_invoice) et les métriques sont regroupées sous un champ structuré (ex. usage_metrics) placé dans les attributs personnalisés (custom_attributes) de la company. Le mapping inclut également, lorsque disponible, des informations de domaine/company_domain. Par défaut, les apps sans utilisateurs actifs sont ignorées pour éviter de créer des companies vides (option “force” disponible pour outrepasser ce comportement). Les emails de contact ne sont plus dupliqués systématiquement au niveau company et sont gérés côté contacts.
Synchroniser Users → Contacts
Créer ou mettre à jour les contacts Intercom pour chaque utilisateur : email principal et secondaires, numéro(s) de téléphone normalisés, rôle standardisé, nombre d’apps, dernier actif, timestamp de dernière synchronisation et autres métadonnées utiles au support. Les métadonnées utilisateur sont envoyées dans un espace dédié (custom attributes / attributs personnalisés) et les tags sont gérés séparément. En cas d’opt‑out ou de contraintes de confidentialité, les données personnelles sont automatiquement omises.
Créer / mettre à jour pour tous les tenants
Lancer une opération d’administration qui crée ou met à jour toutes les companies et tous les users Intercom pour l’ensemble des tenants (pratique après une migration ou un rollout).
Tagger users avec métadonnées
Ajouter des tags et attributs personnalisés (ex. source de migration, whitelabel partner). Les tags suivent la convention migration:
Synchronisation ciblée
Rafraîchir le profil Intercom d’une app ou d’un utilisateur précis après une modification (ex. changement de plan, nouvelle facture). Note : l’action lance désormais un job en arrière-plan et la propagation vers Intercom peut être soumise à un délai lié au quota/rate‑limit. Le job normalise le payload (namespaces d’attributs, regroupement des métriques), inclut external_id et un attribut company_last_synced_at, et applique des retries/backoff en cas d’erreur.
Respect des whitelabels et options
Appliquer des configurations spécifiques (désactiver marketing/messenger, marquer partenaire) pour chaque app lorsqu’elles existent.
Flux métier Qonto vers Intercom
Un traitement backend dédié à Qonto calcule des statistiques d’inscription et met à jour Intercom avec des données liées à l’inscription Qonto, afin d’alimenter le support et le suivi client avec ce contexte métier.
How to use it
Étapes principales pour utiliser la synchronisation Intercom
1. Préparer l'intégration Intercom
Allez dans le panneau d’administration → Intégrations → Intercom. Collez la clé Intercom (credential) fournie par Intercom et sauvegardez. Vérifiez que la clé est correcte : un test de connexion ou un message de confirmation doit s’afficher. Sans cette clé, la synchronisation ne fonctionnera pas.
2. Synchronisation complète (création de tous les users & companies)
Si vous êtes administrateur et devez pousser toutes les données (ex. après une importation ou une migration) : depuis la zone Admin → Outils / Maintenance → Synchronisation Intercom, lancez l’action « Synchronisation complète » (ou « Créer tout »).
- Ce processus parcourt tous les tenants et planifie des jobs en arrière-plan pour créer/mettre à jour les companies et contacts Intercom de façon batched et rate‑limited.
- L’opération n’est plus synchrone : les éléments sont mis en file et traités progressivement pour respecter les quotas Intercom.
- Par défaut, seules les apps marquées pour synchronisation et disposant d’au moins un utilisateur actif sont créées comme companies (pour éviter des entrées vides). Vous pouvez forcer la création de toutes les apps via l’option “force” si nécessaire.
- Le mapping des companies inclut désormais external_id (mappé depuis app_id), company_domain quand disponible, et des attributs supplémentaires (plan, billing_status, seats, billing_next_invoice, created_at). Les métriques d’usage sont envoyées sous un champ structuré (ex. usage_metrics) au sein des custom_attributes. Les tags sont transmis séparément des attributs.
- Le système peut utiliser les mécanismes de batch / bulk d’Intercom lorsque possible pour réduire le nombre d’appels et limiter le throttling.
- Attendez la confirmation et surveillez la file de jobs : l’opération peut durer longtemps (plusieurs heures selon le volume et les limites API).
- Sur succès : toutes les companies auront leurs attributs principaux et un attribut company_last_synced_at pour tracer la dernière synchronisation. Les informations de contact (emails secondaires, téléphones) sont transmises au niveau des contacts utilisateurs, pas systématiquement au niveau company. Les contacts recevront leurs métadonnées (emails secondaires, téléphone, rôle, last_active, last_synced_at, etc.).
3. Mettre à jour les companies (synchronisation en masse des apps)
Pour simplement rafraîchir les données d’apps (companies) sans recréer les utilisateurs, utilisez l’option « Mettre à jour les companies ».
- Utile après une modification globale (changement de tarification, d’info légale).
- L’action planifie des jobs par lot et applique un dispatch rate‑limité vers Intercom ; consultez les logs/jobs pour suivre la progression.
- Les jobs détectent et priorisent les apps dont les attributs clés ont changé (ex. plan, statut, facturation) et envoient des mises à jour partielles (patch) lorsque l’API d’Intercom le permet, afin de réduire la taille des payloads et le nombre de requêtes.
- Par défaut, les apps sans utilisateurs actifs sont ignorées ; utilisez l’option “force” si vous devez inclure ces apps.
- Lancez depuis Admin → Intégrations → Synchronisation Intercom → « Mettre à jour les companies ».
- Contrôlez les logs/suivi pour vérifier les entreprises mises à jour et repérer d’éventuels 429 / retries. Les jobs normalisent les attributs envoyés et regroupent les métriques pour limiter la taille des payloads.
4. Synchronisation ciblée d'une app ou d'un utilisateur
Pour rafraîchir uniquement une app ou un utilisateur :
- Ouvrez la fiche App (ou la fiche User) dans l’interface.
- Cliquez sur « Synchroniser vers Intercom » (ou bouton équivalent).
- Que se passe-t-il : l’action n’exécute plus un appel direct vers Intercom mais enfile un job UpdateIntercom qui sera traité en arrière-plan par le dispatcher. Le job formate le payload (attributs personnalisés regroupés, tags séparés), inclut external_id/company_last_synced_at et tente d’envoyer uniquement les champs modifiés quand c’est possible. Il gère les retries avec backoff en cas d’erreurs transitoires.
- Conséquence opérationnelle : la mise à jour est généralement traitée en quelques minutes, mais peut être retardée si le système applique un throttling ou si des retries sont en cours. Vérifiez l’état du job si la modification n’apparaît pas rapidement.
5. Tagger un utilisateur avec une source de migration
Si vous migrez des clients depuis un ancien logiciel, ajoutez la source de migration pour tracer l’origine :
- Sur la fiche utilisateur, choisissez « Marquer / Tagger pour Intercom ».
- Sélectionnez la valeur (ex. “XLogiciel”) dans le champ “Source de migration” et validez.
- L’utilisateur recevra un tag dans Intercom au format migration:
et un attribut migration_source (avec la valeur). Lorsqu’une source de migration est fournie, un attribut migration_date (au format ISO‑8601) est également ajouté au payload pour tracer la date de marquage. - Attention : si l’utilisateur a exercé un opt‑out ou est soumis à des contraintes de confidentialité, les données personnelles sont omises selon les règles de consentement.
6. Vérifier les résultats et dépanner
Après une synchronisation :
- Vérifiez dans Intercom qu’une company/contact existe et que les champs attendus sont renseignés. Cherchez l’external_id (mappé depuis app_id) sur la company pour vérifier le mapping.
- Si un contact ou company n’apparaît pas, contrôlez la clé Intercom et relancez la synchronisation ciblée pour l’élément.
- Pour les synchronisations en masse, inspectez la file de jobs et les logs : les erreurs 429 (rate limit) entraînent des retries automatiques avec backoff exponentiel, ce qui ralentit la propagation. En cas d’erreurs client persistantes (4xx non-transitoires), le job logue l’erreur et passe à l’élément suivant ; certains champs peuvent être appliqués en mise à jour partielle si l’API le permet.
- En cas d’erreur récurrente, notez l’heure et l’objet (user/app) et contactez l’équipe technique avec ces éléments pour qu’ils consultent les logs.
Astuce pro
Lorsque vous prévoyez une synchronisation complète, lancez-la en dehors des heures de forte activité (soirée ou week-end). Cela réduit l’impact sur les quotas et facilite le suivi. Commencez par une synchronisation ciblée sur quelques comptes clés pour vérifier les mappings avant de lancer la synchronisation globale. Pensez également à vérifier la file de jobs et l’état du dispatcher si vous attendez des mises à jour qui ne sont pas encore visibles.
Règles et limites importantes
- Vous devez disposer des identifiants Intercom valides pour activer la synchronisation.
- Intercom applique des quotas et limites d’API : évitez les synchronisations répétées et simultanées. Planifiez et séquencez les opérations lourdes. Les opérations sont désormais traitées par lots et peuvent subir un throttling (429) avec retries automatiques et backoff exponentiel.
- Respectez la vie privée : n’envoyez pas de données personnelles pour des utilisateurs ayant exercé un opt‑out ou dont la confidentialité l’interdit. Le système omettra les données personnelles en cas d’opt‑out.
- Certains attributs (ex. licence/tier, billing_next_invoice) sont mis à jour au niveau company tandis que d’autres (ex. emails secondaires, last_active) proviennent du job utilisateur. Les métriques d’usage sont désormais regroupées pour réduire les tailles de payload. En cas de doute, vérifiez si le champ est attendu sur la company ou sur le contact.
- Par défaut, les apps sans utilisateurs actifs sont ignorées pour éviter de créer des companies vides ; utilisez l’option “force” si vous devez inclure ces apps.
- Les companies utilisent maintenant external_id (mappé depuis app_id) et un attribut company_last_synced_at est ajouté pour tracer la dernière synchronisation. Le système peut recourir au mécanisme de batch/bulk d’Intercom pour réduire le nombre d’appels.
- En cas d’erreur transitoire (429 / timeouts), le job réessaie automatiquement avec backoff ; en cas d’erreur non-transitoire (4xx), l’élément est logué et ignoré pour éviter des boucles de retry infinies — consultez les logs/jobs pour les détails.
FAQ
Frequently Asked Questions
Besoin d'aide pour lancer la synchronisation ?
Si vous n’êtes pas sûr des credentials, des quotas ou de la portée d’une synchronisation, contactez l’équipe support avant d’exécuter une opération globale.