Les Data connectors sont des intégrations sans code et profondément intégrées qui peuvent connecter vos données externes en direct à Intercom. Ces données en direct peuvent être utilisées pour alimenter Fin, Workflows et l’Inbox, permettant à vos clients de résoudre automatiquement leurs requêtes en libre-service.
Une excellente façon de commencer est de penser aux questions courantes auxquelles vos coéquipiers passent beaucoup de temps à répondre, en utilisant des informations actuellement non disponibles dans Intercom.
Il peut s’agir de questions où vos clients veulent simplement obtenir une information que vous stockez dans un système externe, par exemple « Quel est le statut de ma commande ? », ou d’actions de Data connector comme « Reprogrammer une livraison » ou « Traiter un remboursement » dans votre système externe.
Lorsque vous savez quelles questions vous souhaitez résoudre, il est étonnamment simple et rapide de configurer un Data connector avec peu ou pas d’expertise technique.
Création d’un Data connector
Tout d’abord, allez dans Paramètres > Intégrations > Data connectors.
C’est ici que vous configurerez toutes les différentes connexions que vous avez vers des données externes (par ex. Shopify, Salesforce, etc.) en fonction de votre cas d’utilisation. Cliquez sur + Nouveau.
Conseil : Il est également possible d’utiliser les Data connectors pour Fin.
Nom et description
Donnez à votre Data connector un nom unique qui explique exactement quel Data connector il effectuera (par ex. « Obtenir l’ID de commande »). Utilisez le champ de description pour indiquer à vos coéquipiers quand utiliser ce Data connector et quelles informations ils peuvent attendre qu’il récupère (par ex. « Obtenir la commande pour un ID donné. L’ID de commande doit être stocké dans Conversation CDA »).
Pour permettre à Fin d’utiliser directement ce connector, allez dans l’onglet Fin et définissez Comment Fin doit-il utiliser ce connector ? sur Activé (déclencheur direct). Si vous souhaitez uniquement l’utiliser à l’intérieur d’un Workflow, d’une tâche, d’une procédure ou d’un Macro, réglez-le sur Désactivé (déclencheur manuel).
Connexion API
Ensuite, remplissez les détails de la requête. C’est ici que vous devrez entrer l’URL HTTPS du système tiers auquel vous vous connectez (par ex. Shopify, Salesforce, etc.).
Requête API
Vous pouvez spécifier quel Data connector vous souhaitez que cette requête utilise en sélectionnant la méthode :
GET - Lire et stocker des informations depuis le système tiers.
POST - Créer ou ajouter des informations au système tiers.
PUT - Mettre à jour des informations dans le système tiers.
DELETE - Supprimer des informations du système tiers.
PATCH - Mettre à jour des informations dans le système tiers.
Dans cet exemple, nous demanderons à la requête de GET l’ID de commande depuis l’API et d’entrer l’URL.
Pour effectuer une requête, l’URL doit être une adresse HTTPS.
Conseils :
Vous pouvez insérer des attributs provenant de l’Utilisateur, de la Conversation, de la Société et des événements en tant que valeurs modèles dans l’URL et dans le corps de la requête des méthodes POST et PUT. Utilisez les attributs de données personnalisés que vous avez déjà configurés dans votre espace de travail. Ou, pour une flexibilité de données bien supérieure, essayez d’utiliser des objets personnalisés.
Les Data connectors convertissent automatiquement les réponses XML en JSON. Si votre API renvoie du XML, saisissez simplement le point de terminaison comme d’habitude — Intercom s’occupera de la conversion et affichera le JSON résultant dans l’étape Test response. Vous pourrez ensuite mapper et utiliser les données comme avec une API JSON native.
En-têtes HTTP
Vous pouvez choisir d’ajouter des paramètres supplémentaires à cette requête en cliquant sur Ajouter paire clé-valeur puis sélectionnez Paire clé-valeur sous En-têtes HTTP :
Authentification
Les Data connectors prennent en charge les jetons fixes et dynamiques pour l’authentification. Sous les en-têtes HTTP, vous pouvez sélectionner le jeton d’authentification que vous souhaitez utiliser dans la requête, qui sera alors ajouté à l’en-tête.
Remarque : vous pouvez attacher plusieurs jetons à un seul Data connector. Assurez-vous de configurer chaque jeton avec une clé d’en-tête différente. Tous les jetons attachés seront envoyés avec la requête.
Corps de la requête
Si vous effectuez une requête POST ou PUT, vous aurez la possibilité de fournir un corps de requête pour inclure toutes les données que vous souhaitez envoyer dans la requête :
Veillez à inclure les en-têtes HTTP appropriés requis par l’API à laquelle vous effectuez la requête (par exemple, accept: application/json et Content-Type: application/json). Si vous envoyez un corps JSON, Content-Type: application/json doit être ajouté explicitement — sans cela, l’API n’analysera pas le corps de la requête et rejettera tous les champs comme invalides, même si le JSON est correctement formaté.
Test de la réponse
Ensuite, vous devrez tester la réponse pour ce Data connector afin de vous assurer qu’il récupère les bonnes données depuis le système tiers auquel vous vous connectez.
Important : Tester cette requête établit une connexion avec l’API, donc cela exécutera le Data connector que vous avez créé. Par exemple, si vous lui avez demandé de DELETE des données de l’API, ces informations seront supprimées. Essayez de tester avec une requête GET afin de vous assurer que vous lisez uniquement des informations et que vous ne les modifiez pas.
Cliquez sur Test request pour vérifier que le Data connector a été configuré correctement. Vous devriez obtenir une coche verte et voir les détails de cette requête si la connexion est validée avec l’API.
Ce sont toutes les informations que vous pouvez désormais utiliser pour alimenter vos Workflows et fournir aux clients des réponses rapides, comme le statut d’une commande.
Conseil : Les Data connectors convertissent automatiquement les réponses XML en JSON. Si votre API renvoie du XML, saisissez simplement le point de terminaison comme d’habitude — Intercom s’occupera de la conversion et affichera le JSON résultant dans l’étape Test response. Vous pourrez ensuite mapper et utiliser les données comme avec une API JSON native.
Transformation des données
Par défaut, Fin peut accéder aux données complètes de la réponse pour générer des réponses. Sélectionnez Restreindre manuellement l’accès si vous souhaitez limiter les données que Fin peut lire. Cochez ensuite les champs de données auxquels vous voulez donner accès à Fin.
Vous pouvez également modifier les éléments de données individuels en cliquant sur l’icône modifier pour donner à vos données de réponse un nom visible par le client ainsi que spécifier toute transformation des données.
Par exemple, si la réponse de l’API renvoie un solde de 0, au lieu que Fin indique que le solde impayé est 0, il peut répondre qu’il n’y a actuellement aucun solde impayé restant.
Utiliser du code pour filtrer ou transformer la réponse
Avec les blocs de code pour Data connectors, nous vous permettons de transformer et manipuler directement les réponses API en utilisant Python — directement dans la configuration de votre connector.
Mappage d’objet
Cette étape est facultative. Elle indique au Data connector où stocker ces informations dans Intercom afin qu’elles puissent être fournies aux clients dans vos Workflows comme réponses à leurs questions.
Des scénarios courants où vous n’aurez peut-être pas besoin de stocker les données sont les types de requête Data connector PUT, POST, DELETE. Pour toutes les requêtes GET, si vous souhaitez utiliser les données dans des bots, vous devrez stocker ces données dans Intercom.
Lors de la création de connecteurs de données pour Fin, il n’est pas nécessaire de mapper les données de réponse aux attributs ou objets Intercom. Fin interprète directement la réponse JSON et peut l’utiliser pour résoudre les questions. La réponse est générée à partir de la section « Test response ». Chaque élément de ligne correspond à un point de données dans la réponse JSON.
Les données de réponse JSON peuvent être stockées dans :
Objets standard : attributs User et Conversation.
Custom Objects : attributs d’objet que vous avez créés dans Intercom.
Sélectionnez l’objet Intercom puis mappez-le avec l’objet API externe.
Tous les custom attributes et custom objects doivent être créés avant de pouvoir être utilisés pour le stockage des réponses ici.
Sélectionnez maintenant les attributs de données dans Intercom dans lesquels vous souhaitez stocker ces informations. Par exemple, nous avons sélectionné « Order » comme objet Intercom puis avons sélectionné « root » comme objet API dans le système externe et l’avons mappé avec l’attribut API « currency » :
Les données externes ne peuvent être stockées que dans des attributs de données personnalisés et non dans les attributs de données Intercom standard.
Mapper les données de réponse aux Custom Objects
Lors du mapping avec les Custom Objects, vous devez mapper l’ID sur le champ external_id sinon cela créera des doublons à chaque requête GET. En savoir plus sur la configuration des bonnes références avec les Custom Objects
Mise à jour des références depuis People ou Conversations
L’étape suivante consiste à sélectionner quelles références depuis People ou Conversation sont liées à votre objet personnalisé que vous souhaitez mettre à jour.
Mettre en ligne
Une fois que vous avez testé votre Data connector avec succès, vous êtes prêt à le mettre en ligne.
Note : Les Data connectors utilisent un système de versioning brouillon/en ligne. Tout changement que vous apportez — y compris le paramètre de déclenchement Fin sous l’onglet Fin — est enregistré comme brouillon et n’affectera pas le connecteur en ligne tant que vous n’aurez pas cliqué sur Set live. Si le connecteur semble se comporter de manière inattendue après une modification, vérifiez si la version mise à jour a été mise en ligne. La liste des connecteurs dans Paramètres affiche le statut actuel de chaque connecteur (live ou draft).
La limite de timeout pour les Data connectors est de 15 secondes et n’est pas configurable par le client. Pour les Data connectors utilisés dans les Fin Procedures dans les espaces de travail éligibles, le timeout est étendu à 30 secondes.
Conseil : Si vous souhaitez plus de visibilité en temps réel sur les taux de réussite et d’échec de vos Data Connectors, vous pouvez utiliser le Data Connector Execution Webhook. Cela peut être utile pour recevoir des événements d’exécution afin de créer des tableaux de bord en temps réel, des alertes et la surveillance des SLA dans vos services externes.
Afficher les dépendances des Data connector
Pour gérer ou modifier en toute sécurité vos Data connectors à grande échelle, vous pouvez auditer de manière proactive où chaque Data Connector ou action MCP est utilisé dans Intercom.
Comment activer la vue « Used by » :
La colonne Used by peut être masquée par défaut. Pour l’afficher :
Accédez à Paramètres > Integrations > Data connectors.
Cliquez sur le menu (trois lignes horizontales) en haut à droite du tableau.
Cochez la case à côté de Used by.
Cette colonne fournit une liste d’éléments de référence cliquable et en direct. Cliquer sur n’importe quel élément vous amènera directement à cette source.
Elle suit l’utilisation des Data connector dans :
Workflows
Procédures & Tasks
Custom Answers
Macros
Surveillance de la santé des Data connector
Une fois votre Data connector en ligne, vous pouvez surveiller ses performances directement depuis Paramètres > Integrations > Data connectors.
Indicateurs d’état de santé
Une colonne Health affiche le statut opérationnel de chaque connecteur en fonction de ses récents taux de réussite d’exécution et de latence.
Status | Criteria | Implication |
Healthy | Taux de réussite > 95 % et latence normale.
| Fonctionnement optimal.
|
Degraded | Taux de réussite entre 80-95 % OU la latence est 2x la ligne de base historique.
| Rencontre des problèmes mais toujours partiellement fonctionnel.
|
Unhealthy | Le taux de réussite est de 80 % ou moins.
| Problèmes critiques nécessitant une attention immédiate. |
Survolez n’importe quel badge d’état de santé pour voir une ventilation détaillée de ses performances récentes :
Field Name | Description |
Taux de réussite | Pourcentage d'exécutions réussies sur le total analysé. |
Latence externe | Temps de réponse de l'API/service externe (p90, p50, moyenne, min, max en ms).
Remarque : seules les exécutions réussies sont incluses.
|
Latence interne | Surcharge de traitement interne (temps passé dans le système d'Intercom pour exécuter le connecteur de données) (p90, p50, moyenne, min, max en ms). |
Latence Intercom | Temps d'exécution total, calculé comme Latence externe + Latence interne (p90, p50, moyenne, min, max en ms). |
Répartition des statuts HTTP | Répartition des codes de statut HTTP renvoyés par le service externe (par ex. 200, 500, délai d'attente) avec nombre et pourcentage. Retourne null s'il n'y a pas d'exécutions. |
Répartition des types d'échec | Répartition des types d'échec (par ex. "Connection Timeout", "Authentication Failed"), triée par fréquence, avec nombre et pourcentage. Retourne null s'il n'y a pas d'échecs. |
Nombre d'exécutions | Nombre réel d'exécutions analysées pendant la période en cours. |
Filtres temporels
Utilisez le filtre temporel en haut du tableau de bord pour ajuster la fenêtre de reporting. Options disponibles : 1h, 6h, 24h, 7d ou 14d.
Journaux
Cliquez sur un connecteur pour ouvrir son tableau de bord de santé dédié, puis sélectionnez l'onglet Logs pour voir un enregistrement horodaté de chaque exécution. Chaque entrée indique le canal sur lequel elle a été exécutée et si elle a réussi ou échoué — cliquez sur une entrée pour développer les détails complets de l'exécution.
Vous pouvez filtrer les journaux par :
ID d'exécution
Conversation
Statut (succès ou échec)
Type d'échec
Remarque : Les journaux sont conservés pendant 14 jours maximum. Pour demander une période plus courte de 7 jours, contactez notre équipe Support. Pour un accès programmatique aux données d'exécution au-delà du tableau de bord, voir API access to execution results.
Passer un connecteur de données en brouillon
Si vous souhaitez déprécier d'anciens connecteurs de données qui ne sont plus nécessaires, vous pouvez les passer en état de brouillon.
Allez dans Paramètres > Intégrations > Connecteurs de données et cliquez sur le connecteur de données que vous souhaitez passer en brouillon puis sélectionnez Définir en brouillon.
Bien qu'Intercom vous empêche de mettre en brouillon un connecteur ayant des dépendances actives, vous pouvez maintenant les gérer de manière proactive en utilisant la colonne 'Used by'. Cette colonne fournit une liste indexée en direct de chaque Workflow, Procedure, Task, Macro, and Custom Answer qui référence l'action. Vous pouvez cliquer directement sur un élément de cette liste pour accéder à cette automatisation spécifique et résoudre la dépendance.
Remarque : Une Procedure en pause compte toujours comme une dépendance active. Le passage d'un connecteur en brouillon sera bloqué même si chaque Procedure qui le référence est en pause plutôt qu'en ligne. Résolvez toutes les références au connecteur — y compris celles dans les Procedures en pause — avant d'essayer de définir le connecteur en brouillon.