Utilisez cet article pour configurer, paramétrer et gérer les Data connectors — la fonctionnalité qui permet à Fin de récupérer des données en direct depuis vos systèmes externes et de fournir aux clients des réponses personnalisées sans attendre un coéquipier. Vous apprendrez comment créer un connector à partir d'un modèle ou de zéro, configurer son endpoint API, structurer la réponse, contrôler qui peut le déclencher, gérer la sécurité, le déployer en toute sécurité et surveiller ses performances.
Note : Vous avez besoin de l'autorisation "Can access developer hub" permission pour créer, modifier ou mettre un Data connector en production.
Comment fonctionnent les Data connectors ?
Chaque Data connector consiste en un appel API (application programming interface) que vous configurez. Fin détermine automatiquement quand l'utiliser pour fournir des réponses spécifiques au client. Vous pouvez connecter n'importe quel système disposant d'une API, y compris :
Outils backend internes personnalisés
Plateformes tierces (Shopify, Salesforce, Stripe, Jira, etc.)
Conseil : Les Data connectors peuvent être utilisés par Fin dans les Procedures et d'autres automatisations, y compris Workflows et macros depuis l'Inbox. En savoir plus sur la façon de concevoir et utiliser vos APIs avec les Data connectors.
Comment créer un Data connector
Accédez à Settings > Integrations > Data connectors et cliquez sur New.
Si vous avez l'une des applications prises en charge installée, vous verrez un modèle pour cette application répertorié sous Create Data connector. Des templates sont actuellement disponibles pour Shopify, Stripe et Statuspage — voir From a 3rd party template ci‑dessous pour plus de détails.
À partir d'un modèle tiers
Des templates de Data connector sont disponibles lorsque les applications suivantes sont installées dans votre workspace :
Si l'application n'est pas déjà installée, rendez-vous sur l'App Store pour l'installer. Une fois l'application installée, les templates de Data connector templates pour chaque application apparaîtront comme un Data connector prêt à être mis en production.
Lorsque vous cliquez sur un modèle, vous verrez des informations sur ce que fait le Data connector et vous pouvez le tester dans l'aperçu du Messenger. Si le comportement du Data connector vous convient, sélectionnez simplement Set live for AI Agent.
L'aperçu du Messenger ici utilise des données d'exemple. Lors de la mise en production du Data connector, Fin utilisera vos données client réelles.
Si vous souhaitez configurer le Data connector, vous pouvez cliquer sur Customize, ce qui vous mènera au constructeur de Data connector pour une configuration avancée.
Si vous n'avez pas l'une de nos applications prises en charge installée, les applications apparaîtront ici pour que vous puissiez les installer sur votre workspace. Après l'installation, les templates de Data connector pertinentes apparaîtront dans la section ci‑dessous.
En savoir plus sur les Data connector templates disponibles et les cas d'utilisation pour Fin.
À partir d'une recommandation AI
Pour voir les Data connectors recommandés par l'IA, allez dans Settings > Integrations > Data connectors et cliquez sur New Data connector.
Vous verrez vos Data connectors recommandés par l'IA sous « Create Data connector from template ». Ceux-ci sont générés à partir de l'historique de vos conversations pour vous aider à identifier des Data connectors potentiels, voir quel pourcentage du volume de conversations ils pourraient résoudre et les prévisualiser dans le Messenger, avant de tout configurer.
Pour que les recommandations IA apparaissent, Fin doit être actif sur votre workspace et vous devez avoir un volume de conversations suffisant.
Lorsque vous cliquez sur un Data connector recommandé par l'IA, vous trouverez des informations sur ce que fait le Data connector et vous pouvez le prévisualiser dans le Messenger (en utilisant des données d'exemple). Les Data connectors recommandés par l'IA ne sont que des suggestions basées sur votre volume de conversations, mais ils nécessitent qu'une API soit connectée manuellement pour fonctionner.
Pour mettre le Data connector en production, cliquez sur Set up pour configurer les détails de l'API.
Il ne vous reste plus qu'à connecter le Data connector à votre API en ajoutant l'HTTPS URL.
Pour personnaliser davantage ce Data connector, consultez la section From a custom Data connector.
Créer un Data connector personnalisé à partir de zéro
Pour configurer votre propre Data connector personnalisé pour Fin, accédez à Settings > Integrations > Data connectors et cliquez sur + New > + Create from scratch.
Phase 1 : API
L'onglet API définit comment Intercom communique avec votre système externe.
Donnez à votre connector un nom court et descriptif — par exemple, "Get unpaid account balance." Cela aide Fin à comprendre quand l'utiliser. Ajoutez une description interne pour référence de votre équipe.
Consultez les bonnes pratiques pour rédiger des descriptions de Data connector.
Remarque : Les emojis ne sont pas pris en charge dans les noms de Data connector et provoqueront une erreur s'ils sont inclus.
Entrées de données
Les entrées de données vous permettent de spécifier quelles informations Fin doit collecter avant que le connector ne s'exécute — par exemple, le numéro de compte d'un client s'il n'est pas déjà stocké dans Intercom. Lorsque Fin doit transmettre une requête de recherche ou une autre valeur à l'API en fonction de ce qu'un client demande, ajoutez une entrée de données et définissez la source sur Let Fin collect — Fin recueillera automatiquement la valeur à partir de la conversation.
Cliquez sur + Data input et choisissez un format :
Texte
Nombre
Nombre décimal
Vrai/Faux
Donnez un nom et une description à chaque entrée afin que Fin sache comment la collecter. Vous pouvez également définir une valeur de secours pour les cas où l'API renvoie une réponse nulle ou manquante.
Pour chaque entrée, choisissez d'où proviennent les données :
Let Fin collect — Fin la recueille automatiquement depuis la conversation
People attribute — extrait d'un attribut Intercom existant
Custom value — une valeur fixe que vous définissez
Après avoir sélectionné une source, utilisez le bascule Obligatoire pour définir si l'entrée est requise ou facultative. Cela doit être configuré manuellement pour chaque entrée (l'état n'est pas défini automatiquement).
Le libellé du bascule change en fonction de la source sélectionnée :
Let Fin collect : le bascule affiche Fin must collect this parameter. Lorsqu'il est activé, Fin doit recueillir cette valeur auprès du client avant que le connecteur puisse s'exécuter.
People attribute ou Custom value : le bascule affiche This parameter must have a value. Lorsqu'il est activé, le connecteur ne s'exécutera pas si la valeur est manquante.
L'état requis ou facultatif de chaque entrée est affiché dans la liste des entrées de données.
API endpoint
Ajoutez l'URL HTTPS (web sécurisé) de votre API endpoint et sélectionnez la méthode de requête HTTP : GET (récupérer des données), POST (soumettre des données), PUT (remplacer des données), DELETE (supprimer des données) ou PATCH (mettre à jour partiellement des données).
Utilisez l'Attribute Inserter pour transmettre des valeurs dynamiques — comme l'ID utilisateur d'un client — directement dans le chemin de l'URL ou le corps de la requête. Sélectionnez toujours les attributs à l'aide du sélecteur — ne tapez jamais les jetons manuellement.
Remarque : Si votre connecteur appelle l'Intercom Contacts API et doit identifier un contact, sélectionnez Contact ID (user.id) dans le sélecteur — pas User ID (user_id). L'API Contacts attend l'ID de contact généré par Intercom (user.id). L'utilisation de user_id (l'ID défini en externe) fera échouer la recherche.
Important : L'éditeur convertit tout texte {{...}} en une pastille, donc un jeton saisi manuellement ressemble à un attribut valide. Si l'identifiant ne correspond pas à un attribut réel — tel que user.id ou user_id — il se résout en une valeur vide à l'exécution. Cela rend votre URL de requête malformée et provoque des erreurs comme 404 sans indication visible dans l'éditeur. Utilisez toujours le sélecteur Attribute Inserter pour insérer des attributs.
Authentification et en-têtes
Sélectionnez un jeton d'authentification et ajoutez les en-têtes personnalisés clé-valeur requis par votre API (par exemple, Content-Type: application/json).
Remarque : Si vous envoyez un corps de requête JSON (POST, PUT ou PATCH), vous devez ajouter explicitement un en-tête Content-Type: application/json. Sans cela, l'API destinataire n'analysera pas le corps de la requête et rejettera tous les champs comme invalides — même si le JSON est correctement formaté.
Remarque : Vous pouvez attacher plusieurs jetons à un seul connecteur. Chaque jeton doit utiliser une clé d'en-tête différente — tous les jetons attachés sont envoyés avec chaque requête.
Une fois l'URL de l'endpoint et les détails d'authentification complétés, cliquez sur Test connection pour valider votre configuration. Un test réussi renvoie une confirmation verte et la réponse API brute. Un test échoué affiche le code d'erreur HTTP et une description — corrigez les erreurs avant de passer à la Phase 2 : Données.
Phase 2 : Données — mise en forme de la réponse API
L'onglet Données contrôle comment la réponse API est filtrée et transformée avant que Fin ne l'utilise pour répondre aux clients. Vous pouvez restreindre les champs accessibles à Fin et remodeler les données à l'aide d'un éditeur visuel ou de code Python.
Restreindre et mettre en forme
Par défaut, Fin a accès à la réponse API complète. Pour limiter ce que Fin peut lire, passez en mode Restreindre l'accès manuellement et sélectionnez uniquement les champs que vous souhaitez exposer.
Remarque : Lors de l'utilisation de Restreindre l'accès manuellement, les champs dont les noms contiennent des caractères spéciaux — tels que des parenthèses (), des signes plus + ou des barres obliques / — peuvent être exclus silencieusement des données reçues par Fin, en raison d'un bug de correspondance de chemin. Pour contourner cela, renommez les champs concernés pour supprimer les caractères spéciaux avant de restreindre l'accès. Alternativement, utilisez l'accès complet aux données si la réponse ne contient pas de données sensibles.
Choisissez comment vous souhaitez transformer la réponse :
Vue tableau — filtrez les champs, renommez-les et définissez des transformations au niveau des champs à l'aide d'un éditeur visuel
Python — écrivez du code Python pour nettoyer, remodeler ou reformater la réponse avant qu'elle n'atteigne Fin
Mappage d'objet
Le mappage d'objet vous permet d'affecter les champs de réponse de l'API directement aux attributs de contact ou d'entreprise Intercom, synchronisant automatiquement les données de votre système externe vers votre espace de travail Intercom.
Cliquez sur Test code pour valider votre logique de transformation Python, et Test connection pour confirmer l'appel API complet et la forme de la réponse. Corrigez les erreurs avant de passer à la Phase 3 : Fin.
Remarque : Lorsque vous sélectionnez le mappage d'objet, vous ne verrez que les objets mappés dans Workflows et Procedures ; alors que sans mappage, toutes les options séléctionnées dans la table Restreindre et mettre en forme les données seront listées. Pour Python, seules les valeurs renvoyées seront visibles
Phase 3 : Fin — comment Fin déclenche le connecteur
L'onglet Fin contrôle si Fin déclenche le connecteur automatiquement ou seulement lorsqu'il est appelé explicitement depuis un workflow, une procedure, or macro. Choisissez le mode de déclenchement qui correspond à la sensibilité ou à l'activité d'écriture du connecteur.
Astuce : Avant que Fin puisse utiliser un connecteur, assurez-vous que chacun des éléments suivants est en place :
Entrées de données : Pour toute valeur que Fin doit transmettre à l'API — comme une requête de recherche, un nom de produit ou un ID de commande — ajoutez une entrée de données avec la source définie sur Let Fin collect. Cela indique à Fin de rassembler les termes pertinents depuis la conversation et de les transmettre automatiquement à l'API.
Test connection : Effectuez un test réussi en utilisant des données réelles (Phase 1). La réponse du test façonne ce que Fin verra et retournera aux clients — des données d'exemple ne refléteront pas les résultats réels.
Fin trigger : Dans cet onglet Fin, définissez How should Fin use this connector? sur Enabled (direct trigger).
Description du connecteur : Rédigez une description claire et ciblée de ce que fait le connecteur et quand l'utiliser. C'est ainsi que Fin décide quand l'appeler.
Mettre en production : Complétez les contrôles de sécurité à la Phase 4, puis cliquez sur Save et Set live.
How should Fin use this connector?
Enabled (direct trigger)
Fin triggers the connector automatically based on the customer's question — no workflow required. Best for read-only connectors like "Check order status" and high-volume, repeatable queries.
Vous pouvez contrôler qui peut accéder à ce Data connector avec reusable Fin audiences, ou en créant une audience personnalisée spécifiquement pour ce connector. Par exemple, vous pouvez le rendre disponible aux clients de votre audience « Enterprise plan », ou le restreindre à une audience personnalisée telle que des users connectés avec un e‑mail vérifié qui demandent leur solde de compte.
Note : Vous pouvez désormais utiliser Fin audiences avec les Data connectors. Fin audiences sont des groupes de clients réutilisables que vous créez une fois puis appliquez à plusieurs connectors — ce qui facilite la cohérence.
Vous pouvez choisir Tous, une Fin audience réutilisable, ou une audience Personnalisée pour des règles ponctuelles.
Vous pouvez sélectionner plusieurs Fin audiences, mais vous ne pouvez pas combiner des règles personnalisées (Custom rules) avec une Fin audience.
Toute règle d’audience Data connector existante que vous avez configurée deviendra une audience Custom pour préserver la fonctionnalité.
Astuce : Si vous souhaitez tester le Data connector avant de l’activer pour les clients, utilisez les règles d’audience pour l’activer uniquement pour vous ou vos coéquipiers au départ.
Disabled (manual trigger)
Le connector ne s’exécutera pas automatiquement. Vous devrez l’ajouter manuellement à un Workflow, Procedure, ou Macro. Idéal pour les connectors sensibles ou actifs en écriture — comme « Delete account » — où vous voulez une supervision humaine ou par workflow avant toute exécution.
Utilisez l’aperçu Fin pour voir exactement comment Fin répondra en utilisant ce connector avant de le mettre en ligne.
Note : Les modifications du paramètre de déclenchement Fin sont enregistrées en mode brouillon et ne prendront effet que lorsque vous les publierez. La version active du connector continue d’utiliser ses paramètres existants jusqu’à ce que vous cliquiez sur Set live. Après avoir effectué des modifications, confirmez toujours que le paramètre est reflété dans la version active — pas seulement dans le brouillon.
Phase 4 : Sécurité — contrôle d’accès et mise en ligne
L’onglet Sécurité est l’étape finale avant la mise en ligne. Il contrôle si les clients doivent être authentifiés avant que le Data connector puisse accéder ou afficher leurs données.
Authentification du client
Activez ceci pour appliquer les règles d’authentification de votre espace de travail avant que le connector puisse accéder ou afficher des informations sensibles. Les règles d’authentification sont configurées dans Settings > Workspace > Security > Customer authentication.
Vérification de sécurité
Exécutez un diagnostic pour évaluer la santé et la sécurité de votre configuration API. Les risques sont présentés avec des recommandations exploitables — résolvez-les avant de mettre le connector en ligne.
Une fois toutes les vérifications de sécurité réussies, cliquez sur Save puis sur Set live. Le statut du Data connector change en Live dans Settings > Integrations > Data connectors. Fin commencera à l’utiliser immédiatement pour les conversations correspondant à l’audience configurée.
Important : Il existe plusieurs façons potentielles par lesquelles Fin pourrait partager accidentellement des informations d’un autre user lors du passage de paramètres. Consultez nos paramètres recommandés pour atténuer au mieux les risques.
Comment déployer les Data connectors en toute sécurité
Note : L’aperçu Messenger ici utilise des données d’exemple. Lors de la mise en ligne du Data connector, Fin utilisera vos vraies données clients.
Les Data connectors exigent qu’AI Answers soit activé dans l’étape de workflow pour que Fin puisse les utiliser. AI Answers ne peut pas être activé dans les espaces de test, les Data connectors ne peuvent donc être entièrement testés qu’en production. Utilisez des profils d’utilisateur de test en production pour des tests sûrs.
Nous recommandons d’utiliser audience rules pour déployer les Data connectors par phases auprès de votre base de clients. Cela vous permet de valider la performance du Data connector et d’apporter des ajustements si nécessaire.
Comment surveiller et gérer les Data connectors
Pour trouver les Data connectors existants, allez dans Settings > Integrations > Data connectors. La liste des Data connectors affiche les éléments suivants pour chaque connector :
Nom et statut (live ou draft)
Utilisation générale (exécutions totales)
Fin usage — taux de résolution et l’audience à laquelle il est disponible
État de santé — taux de réussite API et un indicateur de santé global
Statut de sécurité
Détails de configuration
Cliquez sur une ligne de connector pour ouvrir son tableau de bord de santé, où vous pouvez consulter l’utilisation, les métriques de performance et les journaux d’exécution, ou ouvrir l’éditeur de configuration pour apporter des modifications.
Comment afficher l’activité du Data connector dans l’Inbox
Pour voir l’activité du Data connector pour une conversation spécifique, ouvrez la conversation dans l’Inbox et sélectionnez Show conversation events. Le panneau des événements indique si Fin a eu accès au Data connector et s’il a été déclenché avec succès.
Note :
S’il y a une erreur lors du déclenchement du Data connector, sélectionnez Logs pour savoir pourquoi.
Fin peut ne pas toujours choisir d’utiliser le Data connector malgré une requête API si un autre contenu est jugé plus pertinent.
Fin ne peut pas interroger d’attributs personnalisés ni de données d’événement pour les réponses. Pour permettre à Fin de répondre avec des données d’actifs en temps réel, configurez des Data Connectors afin que Fin puisse accéder à des sources de données externes via API.
Inbox views peuvent être créées avec l’attribut “Fin AI Agent: Action used in reply”. Cet attribut est défini si Fin appelle un Data connector et utilise une partie ou la totalité de la réponse dans une réponse.
Versioning des Data connectors
Les Data connectors utilisent un système de versionnage brouillon/en direct afin que vous puissiez effectuer des modifications en toute sécurité sans interrompre le connector en cours d’exécution.
Chaque Data connector a une version en direct et une version brouillon. Les modifications sont apportées au brouillon sans affecter la version en cours d’exécution.
Lorsque vous publiez un brouillon, un nouvel instantané de version est créé et devient la version en direct. Vous pouvez ajouter des notes au moment de la publication. La version précédente en direct est archivée.
Chaque version enregistre un numéro de version, qui l’a créée, des notes de modification (le cas échéant) et un horodatage.
L’historique complet des modifications est traçable et vous pouvez revenir à n’importe quelle version précédente.
Remarque : Cela s'applique à tous les paramètres du connector, y compris le bascule Fin trigger. Si vous modifiez How should Fin use this connector? et que vous ne publiez pas, la version en direct continuera à se déclencher exactement comme avant. Une bannière dans l'éditeur indique que vous avez des modifications non enregistrées — cliquez toujours sur Set live pour activer vos modifications.
Public APIs for Data connectors
Deux public APIs (application programming interfaces) vous donnent un accès programmatique aux configurations et aux résultats d'exécution des Data connectors. Les deux utilisent OAuth (Open Authorization) pour l'authentification. La documentation de référence complète est disponible dans le Intercom Developer Hub.
Comment utiliser la Configuration API
La Configuration API est un ensemble d'endpoints CRUD (create, read, update, delete) pour gérer programmatiquement les Data connectors. Utilisez-la pour créer de nouveaux connectors, synchroniser les connectors avec vos systèmes internes et automatiser la gestion des connectors à grande échelle. Le tableau ci-dessous répertorie les endpoints disponibles et leur objectif.
Méthode | Endpoint | Objet |
GET | /data_connectors | Renvoie une liste paginée de tous les Data connectors pour l'espace de travail, triée par mises à jour les plus récentes en premier. |
GET | /data_connectors/:id | Récupère les détails complets d'un seul Data connector par ID, y compris la configuration, les entrées de données, les champs de réponse et les mappages d'objets. |
POST | /data_connectors | Crée un nouveau Data connector à l'état brouillon. Configurez son URL, ses en-têtes, ses entrées de données et autres paramètres, puis mettez-le en ligne lorsqu'il est prêt. |
PATCH | /data_connectors/:id | Met à jour un Data connector existant. Seuls les champs fournis sont modifiés. Définissez l'état sur live ou draft pour modifier l'état du connector. |
DELETE | /data_connectors/:id | Supprime un Data connector existant. Le connector doit être à l'état brouillon et ne doit pas être utilisé par des workflows ou des AI agents. |
L'authentification utilise OAuth (Open Authorization). L'accès en lecture et écriture nécessite la portée read_write_data_connectors. L'accès en lecture seule nécessite la portée read_workflow_connector_execution_result.
Comment utiliser la Results API
La Results API vous donne un accès programmatique aux données d'exécution de chaque Data connector. Utilisez-la pour créer des tableaux de bord personnalisés, alimenter des systèmes d'alerte ou effectuer une analyse plus approfondie que le tableau de bord de santé intégré.
GET /data_connectors/:id/execution_results — récupère les logs d'exécution paginés. Par défaut, les résultats de la dernière heure sont renvoyés. Utilisez
start_tsetend_tspour personnaliser la plage temporelle. Les corps de requête/réponse sont exclus par défaut — utilisezinclude_bodies=truepour les inclure.GET /data_connectors/:id/execution_results/:result_id — récupère un seul résultat d'exécution, incluant toujours les corps de requête/réponse complets pour un débogage approfondi.
Les options de filtrage incluent le statut de réussite, des types d'erreur spécifiques et des plages temporelles spécifiées en tant que timestamps Unix (secondes écoulées depuis le 1er janvier 1970 UTC). La pagination utilise un modèle basé sur des curseurs, renvoyant jusqu'à 30 résultats par page. L'authentification utilise OAuth avec la portée read_workflow_connector_execution_result.
Limitations connues
Les limitations suivantes s'appliquent aux Data connectors. Lorsqu'une solution de contournement est disponible, elle est indiquée ci-dessous.
Fin may not always use a Data connector even if it successfully runs an API request — if other content is judged more relevant to the customer's question, Fin will use that instead. No workaround; review connector naming and description to improve relevance matching.
Fin cannot query Intercom custom attributes or event data directly to answer questions. Use a Data connector to expose this data via an external API endpoint instead.
Les Data connectors nécessitent que AI Answers soit activé dans l'étape du workflow pour que Fin puisse les utiliser. AI Answers ne peut pas être activé dans les espaces de travail de test, donc les Data connectors ne peuvent être complètement testés qu'en production. Utilisez des profils utilisateur de test en production pour des tests sûrs.
Le Data connector execution webhook n'est pas déclenché lorsque le connector est activé dans le cadre d'une conversation de preview.
Un Data connector ne peut être supprimé via l'API que lorsqu'il est à l'état brouillon et qu'il n'est référencé par aucun workflows ou AI agents.
Les emojis ne sont pas pris en charge dans les noms de Data connector — en inclure un provoquera une erreur lors de l'enregistrement.
Remarque : Il n'existe pas de champ de délai configurable par le client. Le délai par défaut est de 15 secondes. Pour les Data connectors utilisés dans les Fin Procedures dans les espaces de travail éligibles, le délai est étendu à 30 secondes.
Dépannage des Data connectors
Comment utiliser les logs de Data connector
Toutes les données de réponse des Data connectors déclenchés par Fin sont enregistrées et stockées pendant jusqu'à 14 jours. Si votre politique de sécurité ou de conformité nécessite une fenêtre plus courte, contactez notre équipe Support pour demander une conservation de 7 jours à la place.
Pour accéder aux logs, accédez à Settings > Integrations > Data connectors, cliquez sur le connector que vous souhaitez examiner, puis sélectionnez Logs.
Comment utiliser le Data connector execution webhook
Pour des signaux en temps réel sur les taux de réussite et d'échec des Data connectors, utilisez le Data connector execution webhook. Cela vous permet de recevoir des événements d'exécution d'Intercom et de les utiliser pour créer des tableaux de bord en temps réel, des alertes et une surveillance SLA (service level agreement) dans vos services externes.
Remarques :
Vous devrez create an app, set up Webhooks et vous abonner au Data connector execution webhook avant de pouvoir recevoir des notifications de Data connector.
Le Data connector execution webhook sera ignoré si le Data connector est déclenché dans le cadre d'une conversation de preview.