Un appel est terminé dans Aircall, mais aucune activité n’apparaît dans le CRM. Ailleurs, le même transfert a créé deux tâches commerciales, et le numéro partagé par plusieurs contacts a rattaché l’enregistrement au mauvais compte. Le symptôme semble intermittent parce que chaque système montre une partie cohérente de l’histoire. Pour le commercial ou le support, pourtant, la chronologie client devient fausse au moment précis où elle devrait servir de preuve.
La difficulté ne consiste pas seulement à recevoir un webhook. Un appel possède plusieurs étapes, des participants qui peuvent changer, un numéro distant parfois ambigu, des métadonnées finalisées après le raccrochage et des ressources sensibles qui n’arrivent pas toutes au même instant. Une intégration fragile transforme chaque événement en nouvelle activité ; une intégration fiable construit progressivement un seul dossier autour de l’identifiant Aircall.
Le bon arbitrage commence par la responsabilité des données. Aircall décrit le déroulement téléphonique, tandis que le CRM possède le client, l’opportunité, le ticket et la qualification commerciale. En pratique, le connecteur rapproche ces deux mondes sans prétendre qu’un numéro identifie toujours une personne. Contre-intuitivement, laisser une activité « contact à confirmer » est souvent plus juste que sélectionner automatiquement le premier résultat.
Notre accompagnement en intégration API Aircall traite précisément ce rapprochement entre appel et dossier. La démarche reste ancrée dans une intégration API sur mesure : contrat d’événements, idempotence, sécurité, reprise et supervision sont conçus avec les équipes qui exploiteront réellement le flux.
Décider ce qu’Aircall et le CRM possèdent réellement
Aircall fait foi sur l’existence de l’appel, son identifiant, sa direction, son numéro Aircall, le numéro distant et les étapes de son cycle. Le CRM fait foi sur le compte, le contact, le ticket ou l’opportunité auxquels l’activité doit être associée. Le connecteur conserve le lien entre les deux, mais il ne transforme pas Aircall en référentiel client ni le CRM en source de durée téléphonique.
Cette séparation s’écrit champ par champ. La qualification finale peut provenir d’un tag Aircall ou d’un champ CRM selon le processus choisi. Un commentaire d’agent peut enrichir l’activité sans remplacer une note commerciale déjà revue. Le propriétaire de chaque donnée, la direction de synchronisation et la règle de conflit figurent dans le contrat avant toute écriture.
Cas concret. Un appel entrant concerne un client dont le contrat est enregistré dans le CRM. Aircall fournit le numéro appelé, le numéro distant, l’agent et les événements. Le CRM sélectionne le compte et conserve le responsable commercial. Si le rapprochement reste ambigu, le connecteur crée une activité en attente de classement sans modifier la fiche d’un candidat.
Choisir le bon événement dans le cycle d’un appel
Séparer le temps réel du journal final
Les événements précoces répondent aux besoins immédiats. L’événement call.created permet de préparer un écran ou un contexte, call.answered confirme la prise d’appel et call.transferred signale un transfert. Ils ne constituent pas encore le journal définitif. Créer une activité complète dès le premier événement oblige ensuite à la corriger plusieurs fois.
L’événement call.hungup est émis immédiatement lorsque l’appel se termine et convient aux interfaces temps réel. La notification call.ended arrive après finalisation des données de l’appel, environ trente secondes plus tard selon la documentation actuelle, et sert mieux de base à la synchronisation CRM. Le contrat peut ouvrir une activité légère au début, puis la finaliser sur call.ended.
Attendre les ressources qui arrivent après la fin
L’enregistrement ou le message vocal peut ne pas être disponible au moment de call.ended. L’événement call.comm_assets_generated permet de compléter le dossier lorsque ces ressources sont prêtes. Cette étape enrichit l’activité existante grâce au même identifiant d’appel ; elle ne crée pas une nouvelle interaction dans le CRM.
La chronologie conserve l’événement reçu, son horodatage et la révision du dossier. Un événement tardif peut donc ajouter une ressource sans revenir sur le contact déjà validé. Si une information finale contredit une valeur provisoire, la règle de mise à jour est explicite et observable.
Rattacher un numéro sans inventer un contact certain
Le champ raw_digits représente le numéro de l’autre partie : l’appelant pour un entrant, le numéro composé pour un sortant. Il constitue la première clé de recherche recommandée dans les données d’appel. Le champ contact reflète uniquement le répertoire propre à Aircall et peut rester nul lorsque la personne provient d’un CRM externe ou ne figure pas dans ce répertoire.
Le numéro doit être normalisé avec son contexte international, puis comparé aux téléphones connus du CRM. Cette recherche produit zéro, un ou plusieurs candidats. Un résultat unique et actif peut être rattaché automatiquement si la politique locale l’autorise. Plusieurs candidats actifs imposent un arbitrage humain ou un signal complémentaire, jamais un choix selon l’ordre de réponse de la base.
Le numéro Aircall appelé apporte un contexte utile : service commercial, support, pays ou marque. L’agent, l’équipe et un éventuel ticket ouvert peuvent affiner la sélection. Ces indices augmentent la confiance sans changer la nature du numéro. Le journal conserve la règle de matching, les candidats évalués et la raison du choix.
Le seuil d’automatisation doit être mesurable. Si une organisation exige une correspondance exacte entre numéro normalisé et compte actif, tout résultat différent rejoint la file « contact à confirmer ». Une deuxième règle peut autoriser une association au compte sans sélectionner de personne. Un cadrage Aircall–CRM sur un numéro pilote permet de tester cette politique sans transformer une donnée partagée en identité certaine.
Synchroniser les contacts sans créer deux référentiels
La synchronisation de contacts vise à donner aux agents un nom et un contexte utiles dans Aircall. Elle ne doit pas ouvrir un second lieu de maintenance pour les coordonnées, les consentements et le cycle de vie client. Le CRM reste généralement l’autorité ; le connecteur projette seulement les champs nécessaires à l’usage téléphonique.
Chaque contact projeté conserve l’identifiant externe du CRM et une version ou date de modification. Une fusion CRM retire ou remplace l’ancienne projection sans réattribuer l’historique des appels. Les appels passés restent liés à leur call.id et au compte finalement retenu dans le CRM, même si le répertoire Aircall évolue ensuite.
Les suppressions demandent une politique distincte. Désactiver une personne, retirer un numéro obsolète et satisfaire une demande d’effacement ne sont pas la même action. Le flux transmet une intention nommée, contrôle son effet et conserve uniquement la preuve autorisée. Une absence dans un export ne vaut jamais ordre implicite de suppression.
Un import initial se traite par lots avec rapport de rejets. Les numéros invalides, les doublons et les contacts sans identifiant source n’entrent pas silencieusement dans Aircall. Le bilan sépare créations, mises à jour, éléments inchangés et erreurs à corriger avant d’activer la synchronisation continue.
Créer une seule activité CRM par appel
L’identifiant call.id devient la clé externe de l’activité Aircall dans le CRM. La première réception crée ou retrouve le dossier ; toutes les suivantes le mettent à jour. Une contrainte d’unicité au niveau de la persistance protège ce principe même si deux workers traitent simultanément un événement rejoué.
L’idempotence porte sur l’effet, pas uniquement sur le message. Le webhook peut être livré plusieurs fois, le worker peut tomber après l’écriture CRM et un retry peut repartir sans connaître le résultat précédent. Avant toute création, le connecteur recherche l’activité par identifiant Aircall. Après un délai dépassé, il relit l’état distant avant de décider une nouvelle mutation.
Les événements sont stockés avec une empreinte minimale, leur type et leur statut de traitement. Si un événement ancien arrive après une version plus récente, il complète éventuellement une information manquante mais ne rétablit pas un état dépassé. Le dossier expose la dernière transition acceptée et les événements ignorés avec leur motif.
Le coût caché d’un doublon ne se limite pas à une ligne supplémentaire. Il peut déclencher deux tâches, fausser les statistiques d’activité, attribuer deux fois un appel et demander une suppression manuelle risquée. Le seuil de production doit donc rester à zéro doublon inexpliqué sur l’échantillon de recette.
Conserver transferts, participants et responsabilité finale
Un transfert change la personne qui traite l’appel sans créer nécessairement une nouvelle interaction client. Le connecteur rattache chaque événement au même dossier, puis conserve la succession des agents et des équipes. L’activité CRM affiche le propriétaire final selon la règle choisie, tandis que l’historique permet d’expliquer le parcours.
La responsabilité commerciale ne découle pas automatiquement du dernier agent. Un standard peut transférer vers un spécialiste sans que le compte change de propriétaire. Le contrat distingue participant téléphonique, auteur de la qualification, responsable de l’activité et propriétaire du client. Ces rôles évitent qu’un simple transfert réattribue une opportunité.
Cas concret. Un appel arrive sur le support, passe par un agent de niveau un puis par un expert produit. Le journal CRM conserve les deux participants et la durée globale, mais le ticket reste assigné à la file support jusqu’à une décision explicite. Le commentaire de l’expert enrichit le ticket sans modifier le responsable du compte.
Distinguer appel manqué, durée totale et temps parlé
Un appel manqué ne se déduit pas d’un type générique nommé « missed ». Dans le modèle actuel, le statut terminé et la présence d’un missed_call_reason permettent de le reconnaître. La raison distingue notamment les situations liées aux horaires, à l’abandon ou à l’absence de réponse. Le CRM conserve ce motif au lieu de réduire tous les cas à une seule tâche de rappel.
La durée totale inclut la sonnerie. Pour connaître le temps réellement parlé, le calcul utilise l’heure de fin et answered_at, lorsque cette dernière existe. Un appel non répondu n’a pas d’heure de réponse. Les indicateurs commerciaux doivent donc nommer précisément ce qu’ils mesurent avant de comparer des équipes.
Le workflow de rappel dépend du contexte. Un abandon très court, un appel hors horaires et un appel sans agent disponible ne demandent pas la même priorité. La décision peut intégrer le numéro Aircall, le segment CRM et l’existence d’une demande récente. Elle reste séparée du simple fait technique « appel manqué ».
Propager tags et commentaires sans écraser le métier
Les tags et commentaires ajoutés après l’appel peuvent modifier la qualification utile au CRM. Les événements dédiés mettent à jour l’activité existante. Le mapping traduit un tag Aircall vers une valeur autorisée, sans copier automatiquement toute nouvelle étiquette créée par un administrateur.
Un tag décrit souvent l’issue téléphonique, tandis qu’un statut CRM porte une décision commerciale plus large. « À rappeler » peut créer une tâche sans faire reculer l’opportunité. « Mauvais numéro » peut ouvrir une demande de correction sans effacer la personne. Chaque correspondance indique l’effet, l’auteur attendu et le comportement en cas de valeur inconnue.
Les commentaires restent des contenus libres potentiellement sensibles. Le flux décide s’ils doivent être copiés, résumés ou seulement référencés. Un masque protège les journaux techniques ; il ne corrige pas une copie excessive vers le CRM. La minimisation se traite donc dans le contrat de données.
Protéger enregistrements, messages vocaux et transcriptions
Les champs d’enregistrement et de message vocal peuvent contenir des URL signées soumises à expiration. Enregistrer seulement l’URL dans le CRM crée un lien qui cessera de fonctionner. Avant toute copie, l’entreprise décide si elle doit conserver le média, pendant combien de temps, dans quel stockage et pour quels rôles.
L’accès technique ne suffit pas à autoriser l’usage. Le traitement doit respecter l’information des personnes, les règles internes, les durées de conservation et les contraintes applicables au contexte. Lorsque le CRM n’a besoin que de signaler l’existence d’un enregistrement, il conserve un indicateur et un accès contrôlé plutôt qu’une duplication générale.
Les transcriptions, résumés ou éléments d’intelligence conversationnelle ne font pas partie du même objet d’appel. Ils arrivent par des ressources ou événements distincts et peuvent dépendre d’options spécifiques. Le connecteur les relie à l’appel sans supposer leur présence. Leur absence ne bloque pas la finalisation de l’activité téléphonique de base.
Une révocation d’accès doit être testée. Le support vérifie qu’un ancien lien ne donne plus le média, que la copie éventuelle suit sa propre politique et que les traces ne contiennent ni URL complète ni contenu vocal. Cette recette associe sécurité, conformité et exploitation concrète.
Recevoir les webhooks rapidement et les traiter durablement
Vérifier le compte puis accuser réception
La création du webhook fournit un jeton propre à cette souscription. Le récepteur l’associe au compte Aircall attendu afin d’identifier l’émetteur et de vérifier l’origine de l’événement. Une valeur inconnue est refusée avant toute écriture métier. Le secret est stocké, renouvelé et journalisé comme une référence, jamais en clair.
Le point d’entrée valide la forme minimale, persiste l’événement dans une file durable puis répond rapidement. La mise à jour du CRM se déroule de façon asynchrone. Une panne du CRM ne doit pas maintenir la requête Aircall ouverte ni provoquer une tempête de traitements concurrents.
Accepter répétitions et ordre non garanti par le métier
Le consommateur suppose qu’un événement peut être rejoué ou arriver après une information plus récente. Il ordonne les effets grâce à l’état courant du dossier, au type d’événement et aux horodatages pertinents. Les mises à jour commutatives, comme l’ajout d’un tag absent, sont plus faciles à reprendre que les écrasements complets.
La file de quarantaine conserve compte, appel, événement, cause et prochaine action. Le support peut rejouer après correction sans réinjecter un payload modifié à la main. Si le schéma contient un champ inconnu, le message reste consultable et l’intégration continue de traiter les événements compatibles.
Réconcilier l’historique avec l’API REST
Les webhooks alimentent le flux quotidien, tandis que l’API REST sert au rattrapage et à l’import historique. La liste des appels est paginée. Le connecteur suit le lien de page suivant au lieu de construire lui-même un numéro arbitraire, puis limite chaque extraction à une fenêtre de dates contrôlable.
La documentation actuelle indique une limite de récupération paginée de dix mille appels et recommande de découper les gros imports par plages temporelles. Elle illustre également une cadence tenant compte d’une limite de soixante requêtes par minute. Ces valeurs doivent être relues avant le développement, car les limites d’un fournisseur peuvent évoluer.
Le rattrapage réutilise exactement la même fonction d’upsert que les webhooks. Il ne crée pas une seconde voie de transformation. Une fenêtre chevauchante relit les appels récents afin de récupérer une finalisation tardive ; l’unicité sur call.id empêche les doublons.
La réconciliation compare au minimum les appels terminés côté Aircall et les activités correspondantes dans le CRM. Elle classe absences, doublons, associations ambiguës et ressources manquantes. Un écart possède un état de résolution et une ancienneté, ce qui permet de prioriser les dossiers à impact client plutôt que de compter seulement les erreurs HTTP.
Choisir l’authentification et limiter les données exposées
Une intégration privée reliant les outils d’une seule entreprise peut utiliser l’authentification basique avec l’identifiant API et le jeton prévus par Aircall. Une application distribuée à plusieurs comptes utilise OAuth. Le choix suit le modèle d’installation réel ; partager une paire de secrets entre plusieurs clients n’est pas une simplification acceptable.
Le compte technique reçoit uniquement les accès nécessaires aux appels, contacts, utilisateurs ou webhooks effectivement exploités. Les secrets sont séparés par environnement et leur rotation est exercée. La révocation doit arrêter proprement le flux, déclencher une alerte et préserver les événements en attente sans exposer leur contenu.
Les logs conservent identifiants, types, statuts, latence et corrélation. Ils excluent numéros complets, commentaires, URL signées, transcription et média. Les personnes autorisées retrouvent le détail dans les systèmes sources à partir de l’identifiant d’appel, plutôt que dans un agrégateur de logs trop largement accessible.
Donner au support une preuve par appel
Le point d’entrée du diagnostic est l’identifiant Aircall ou l’identifiant de l’activité CRM. La vue de support affiche le compte concerné, les événements reçus, la dernière révision appliquée, le contact choisi, les candidats écartés et les traitements encore en attente. Elle ne demande pas au support de croiser trois exports.
Les indicateurs utiles suivent les appels sans activité, les activités en double, les contacts ambigus, les événements en quarantaine et le délai entre call.ended et la finalisation CRM. Le taux de réussite global peut rester élevé alors qu’un numéro stratégique accumule les erreurs ; les mesures sont donc ventilées par ligne, organisation et type de cause.
Le signal faible apparaît lorsque les corrections manuelles augmentent sans hausse des erreurs techniques. Cela indique souvent un mauvais matching ou une règle de qualification devenue obsolète. Un deuxième signal est l’âge croissant des éléments en quarantaine malgré un volume stable : le runbook ne permet probablement plus une reprise autonome.
Le runbook décrit les entrées, les responsabilités, les dépendances, les seuils et la journalisation. Il précise quand exécuter un retry, quand relire Aircall, comment réconcilier le CRM et comment annuler une association erronée sans supprimer la preuve de l’appel. L’exercice de reprise utilise les mêmes droits et outils qu’en production.
Savoir quand une intégration Aircall dédiée est utile
Le développement dédié devient pertinent lorsque plusieurs lignes, équipes ou objets CRM doivent suivre des règles de rattachement différentes. Il apporte aussi de la valeur lorsque les transferts, les enregistrements, les tags, les tickets ou la réconciliation exigent une preuve que le connecteur standard ne fournit pas.
Une intégration native reste préférable si elle couvre le besoin sans détour, que le modèle CRM est standard et que son exploitation répond aux attentes. Le sur-mesure ne doit pas reproduire une fonction existante uniquement pour déplacer sa configuration. Il se justifie par une responsabilité, une règle ou une reprise réellement spécifique.
Le projet doit être différé lorsque les numéros CRM sont trop peu fiables, que personne ne possède les règles de matching ou que la conservation des enregistrements n’est pas décidée. Automatiser dans ce contexte accélère les mauvaises associations. La priorité devient le nettoyage du référentiel et la clarification des responsabilités.
Erreurs fréquentes qui faussent le journal CRM
- Créer une activité pour chaque webhook. Le cycle d’un seul appel produit plusieurs événements qui doivent enrichir le même dossier grâce à
call.id. - Utiliser uniquement le champ
contact. Il peut rester nul pour un contact provenant d’un CRM externe, alors queraw_digitspermet de lancer le rapprochement. - Choisir le premier numéro trouvé. Un standard, un foyer ou un ancien doublon peut correspondre à plusieurs fiches actives et exige une décision contrôlée.
- Finaliser le CRM sur
call.hungup. Les métadonnées complètes et les ressources de communication peuvent arriver plus tard dans le cycle. - Confondre durée et temps parlé. La durée inclut la sonnerie, tandis que le temps de conversation dépend de l’heure de réponse.
- Stocker durablement une URL signée. Le lien peut expirer et ne remplace ni une politique de conservation ni un contrôle d’accès.
- Réparer directement dans la base. Une correction non tracée casse la réconciliation et réapparaît lors du prochain événement ou import.
Arbitrer le périmètre avant le développement
La décision de départ porte sur un objectif métier précis : journaliser les appels terminés, ouvrir un ticket lors d’un appel manqué ou afficher le contexte client dès la sonnerie. Mélanger ces trois besoins dans un premier lot multiplie les événements, les contraintes de délai et les droits avant que le matching soit prouvé.
- D’abord, choisir un objet CRM. Retenir activité, ticket ou tâche selon la décision attendue, sans créer les trois pour le même appel.
- Ensuite, fixer le matching. Écrire les règles pour zéro, un et plusieurs contacts candidats, puis attribuer la validation au responsable métier.
- Puis, sélectionner les événements. Utiliser les étapes temps réel uniquement si elles déclenchent une action immédiate et finaliser le journal avec les données adaptées.
- Après cela, borner les données sensibles. Refuser la copie d’enregistrements, commentaires ou transcriptions tant que l’usage, les droits et la durée ne sont pas décidés.
- Enfin, exiger une reprise. Ne pas ouvrir un second numéro avant que le support sache expliquer, corriger et rejouer un dossier sans accès direct à la base.
Plan d’action pour déployer un premier numéro
Cadrer le contrat et la qualité des identités
Sélectionnez une ligne Aircall, une équipe et un seul objet CRM. Extrayez un échantillon d’appels entrants, sortants, manqués et transférés. Mesurez les numéros sans candidat, les correspondances uniques et les doublons. Les cas ambigus deviennent des scénarios de recette, pas des anomalies exclues de l’analyse.
Décrivez les entrées et sorties : call.id, direction, raw_digits, numéro Aircall, participants, temps, motif d’appel manqué, tags, contact retenu et activité cible. Attribuez chaque champ à sa source, puis définissez absence, valeur nulle et correction. Le responsable CRM valide les effets sur compte, contact et ticket.
Construire une ingestion rejouable et observable
Le récepteur vérifie le jeton du webhook, enregistre l’événement et répond sans attendre le CRM. Un worker réalise l’upsert idempotent sous contrainte d’unicité. Les dépendances, délais, retries et erreurs permanentes sont séparés. La quarantaine conserve la cause et la prochaine action, tandis que le tableau de bord suit retard et divergences.
Ajoutez un rattrapage REST par fenêtre de dates et pagination. Il appelle la même transformation que les webhooks, respecte les limites documentées et produit un rapport de réconciliation. Le runbook explique comment reprendre un événement, relire l’appel, corriger une association et exécuter un rollback fonctionnel sans effacer l’historique.
Recetter un transfert puis étendre par ligne
Le scénario appelle un numéro partagé, présente deux contacts candidats, transfère vers un second agent puis ajoute une qualification. La recette attend une seule activité, une chronologie complète, un contact non choisi par défaut et une ressource sensible inaccessible aux rôles non autorisés. Une coupure du CRM vérifie la file, le retry et l’absence de doublon.
Le pilote reste en lecture ou sur une population limitée jusqu’à ce que le support traite seul les écarts. La bascule exige zéro doublon inexpliqué, une quarantaine sous le seuil local et une réconciliation terminée. Chaque nouvelle ligne reprend les mêmes contrôles ; elle n’est pas ajoutée seulement parce que le volume du premier numéro paraît faible.
Guides complémentaires pour sécuriser le flux
Protéger l’entrée événementielle
La vérification d’origine, la réponse rapide et la protection contre le rejeu sont approfondies dans la méthode consacrée aux webhooks signés et rejoués. Chaque fournisseur possède son mécanisme ; l’architecture doit néanmoins conserver une frontière d’entrée homogène.
Lorsque plusieurs événements enrichissent le même objet, la stratégie décrite pour les webhooks reçus dans le désordre aide à séparer ordre de livraison, état courant et effet idempotent.
Conserver une preuve exploitable sans surcollecte
Le journal d’audit d’une intégration API précise les informations nécessaires pour expliquer une mutation, une association ou une reprise. Il permet de conserver la décision sans dupliquer les commentaires, médias ou données personnelles dans chaque log.
Si le matching Aircall–CRM reste fragile ou si les activités divergent déjà, un audit ciblé de l’intégration Aircall permet de mesurer doublons, appels orphelins, droits et procédures de reprise avant de généraliser le flux.
- Vérifier l’autorité de chaque champ et l’unicité de
call.idavant d’ajouter un nouvel effet CRM. - Comparer régulièrement appels terminés, activités CRM, contacts ambigus et ressources encore en attente.
- Faire exécuter la reprise par le support avec les droits réels avant d’étendre le pilote à une autre ligne.
Conclusion : une chronologie fiable plutôt qu’une copie exhaustive
Une intégration Aircall réussie ne copie pas chaque événement dans le CRM. Elle construit une seule activité par appel, choisit le moment de finalisation adapté et conserve les compléments tardifs sans dupliquer l’interaction. Le cycle technique devient ainsi une chronologie que les équipes peuvent réellement expliquer.
Le matching mérite la même prudence. Le champ raw_digits ouvre la recherche, mais le numéro n’est pas toujours une identité. La ligne appelée, les candidats CRM, les participants et le contexte métier permettent de décider ; lorsque les preuves restent insuffisantes, le dossier attend une validation humaine plutôt qu’une association arbitraire.
La fiabilité se joue enfin dans les reprises : webhook persisté, upsert par call.id, événement tardif, rattrapage REST, quarantaine et runbook. Les enregistrements et transcriptions restent soumis à leur propre politique d’accès et de conservation au lieu de circuler comme de simples champs techniques.
Pour cadrer cette chronologie dans une démarche d’expertise en intégration API, notre équipe peut vous aider à auditer le matching, écrire les contrats et déployer un premier numéro avec ses tests, sa supervision et sa réconciliation.
