Chaque connecteur de données consiste en un appel API que vous pouvez configurer en coulisses. Fin choisira automatiquement quand l’utiliser et fournira une réponse personnalisée au client.
Vous pouvez connecter n’importe quel système disposant d’une API ; cela peut être votre outil interne unique que vous avez développé pour votre entreprise, ou une application tierce que vous utilisez comme Shopify, Salesforce, Stripe, Jira, et plus encore.
Note :
L’authentification des users doit être configurée pour mettre un connecteur de données en service pour les users. Cela empêche toute personne d’usurper vos users connectés ou de voir leurs conversations. Apprenez à configurer les JWT pour l’authentification des users.
Créer un connecteur de données
Pour configurer un connecteur de données personnalisé pour Fin, allez dans Paramètres > Intégrations > Connecteurs de données et cliquez sur + Nouveau.
Phase 1 : API
L’éditeur de configuration est organisé en quatre onglets : API, Data, Fin et Sécurité. Parcourez chaque onglet pour construire votre connecteur avant de le mettre en service.
Identité
Commencez par fournir un nom court pour décrire ce que fait ce connecteur de données, comme « Obtenir le solde impayé ». Ensuite, fournissez une description détaillée expliquant quand Fin doit l’utiliser.
Incluez des exemples des données fournies par ce connecteur de données et des requêtes clients auxquelles il aide à répondre.
Par exemple :
Utilisez ce connecteur de données pour récupérer les transactions récentes d’un client. Ce connecteur de données fournit des informations clés telles que… Exemples de requêtes clients incluent… « Pouvez-vous vérifier si j’ai un solde impayé sur mon compte ? » « Y a-t-il un paiement dû sur mon compte en ce moment ? » « Dois-je quelque chose sur mon compte ? » « Pouvez-vous me dire si j’ai des factures ou charges impayées ? » « Y a-t-il un solde que je dois régler sur mon compte ? » « Pouvez-vous confirmer si mon compte est entièrement payé ? »
Connexion API
Si vous le souhaitez, vous pouvez spécifier si Fin doit collecter des données avant d’utiliser ce connecteur de données. Cela peut être utile dans les cas où vous devez vous assurer que des données existent avant que le connecteur de données ne soit exécuté. Par exemple, vous pourriez demander au client son numéro de compte si celui-ci n’est pas stocké dans son profil user dans Intercom.
Pour collecter des données, cliquez sur + Ajouter une entrée de données et choisissez le format des données à collecter (texte, nombre, nombre décimal ou vrai/faux) puis donnez-lui un nom et une description pour que Fin sache comment les collecter.
Note :
Lorsque disponible, Fin recueillera les informations du contexte de la conversation.
Vous pouvez connecter des connecteurs de données à des API qui renvoient du XML. Intercom convertira automatiquement les réponses XML en JSON, vous n’avez donc pas besoin de faire de conversion manuelle ni d’utiliser un outil tiers. Cela signifie que vous pouvez connecter une gamme plus large de systèmes externes, même s’ils ne supportent pas JSON nativement.
Ensuite, vous devez spécifier l’URL HTTPS de votre API et sélectionner la méthode de requête : GET, POST, PUT, DELETE ou PATCH.
Vous pouvez vouloir utiliser des attributs disponibles dans votre espace de travail, comme l’ID user ou l’email d’un client, pour effectuer une recherche. Vous devez aussi vous assurer de spécifier le jeton d’authentification correct et de spécifier les en-têtes corrects (par exemple : Accept: application/json ou Content-Type: application/json).
Une fois terminé, testez votre connexion pour valider la configuration avant de passer à l’onglet Data.
Tester la réponse
Vous devrez tester cette action pour vous assurer qu’elle récupère les bonnes données de l’API à laquelle vous vous connectez. Vous pouvez tester votre connecteur de données de deux manières :
Réponse en direct : Testez avec des données de réponse en direct de votre requête API pour garantir une configuration correcte. La réponse en direct effectuera un appel API réel à votre point de terminaison, soyez donc prudent au cas où cette requête affecterait des données réelles.
Réponse d’exemple : Fournissez des données JSON d’exemple utiles si votre API n’est pas encore complètement développée ou si vous devez simuler/imiter une réponse particulière.
Si tout semble correct, continuez à l’onglet Data pour configurer la forme de la réponse.
Phase 2 : Data
Cet onglet contrôle la façon dont la réponse API est structurée avant que Fin ne l’utilise.
Restreindre et structurer
Par défaut, Fin peut accéder à toutes les données 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 auxquelles Fin peut accéder. Puis cochez les champs de données auxquels vous voulez donner accès à Fin.
Vous pouvez aussi 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 destiné au client ainsi que spécifier toute transformation des données.
Par exemple, si la réponse API renvoie un solde de 0, au lieu que Fin indique que le solde impayé est de 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 les connecteurs de données, nous vous permettons de transformer et manipuler directement les réponses API en Python — directement dans la configuration de votre connecteur.
Les charges non structurées ou trop volumineuses provenant des API peuvent faire halluciner, mal interpréter ou simplement empêcher les réponses basées sur l’IA (comme Fin ou d’autres agents IA) de fournir des réponses claires. Désormais, vous pouvez prétraiter, filtrer ou ajuster programmatiquement les réponses API avant qu’elles ne soient envoyées à Fin ou mappées aux objets Intercom sans nécessiter de modifications backend ou d’intégrations tierces.
Comment ça marche
returnstatement : Le résultat principal produit par votre bloc de code doit être renvoyé avec une instructionreturn. Seul ce qui est renvoyé sera transmis à Fin ou au reste de votre connecteur.print()statements : Utilisez-les uniquement pour le débogage ou la journalisation de progression. Ces sorties sont capturées séparément et NE sont PAS envoyées comme résultat de l’API.Modules standards uniquement : Vous êtes limité à un ensemble de modules Python standards (
math,decimal,re,datetime,datetime.timezone,json,random,time). Nous ajouterons d’autres modules au fil du temps selon les besoins.
Note :
Réponses de test non JSON : Les blocs de code exigent que la réponse de test de votre API soit un objet ou un tableau JSON valide. Les charges non JSON ne sont pas prises en charge (et entraîneront des échecs).
Requêtes API non réussies : Les blocs de code ne peuvent transformer que les réponses API réussies (code statut 200). Les réponses d’erreur avec des codes comme 400, 404 ou 500 ne sont pas prises en charge pour la transformation par bloc de code.
Comment configurer les blocs de code pour les connecteurs de données
Allez dans Paramètres > Intégrations > connecteurs de données et sélectionnez le connecteur de données avec lequel vous souhaitez utiliser des blocs de code. Puis cliquez sur Transformation des données et sélectionnez l’option « Utiliser du code pour filtrer ou transformer la réponse ».
Accéder aux données d’entrée (réponse API) dans votre bloc de code
Pour accéder aux données renvoyées par votre API (la réponse de test), utilisez la variable inputs['data'] dans votre bloc de code. En général, cela vous donne toute la réponse de votre API, prête à être transformée comme vous le souhaitez.
Par exemple, au début de votre bloc de code, vous écrivez généralement :
api_response = inputs['data']
Cela assigne la réponse API (un dictionnaire Python, une liste ou une chaîne, selon votre API) à la variable api_response pour un traitement ultérieur.
Obtenez des suggestions automatiques pour les blocs de code
Lorsque vous naviguez vers l’onglet Transformation des données, la réponse de votre connecteur de données est automatiquement analysée pour identifier des suggestions qui amélioreront les performances de Fin.
Cela détecte les problèmes courants comme les horodatages Unix et les charges utiles surdimensionnées — des données non structurées ou trop volumineuses pouvant entraîner des réponses IA erronées, des mauvaises interprétations ou des réponses peu claires.
Lorsqu’une suggestion est trouvée, vous verrez une bannière avec un bouton Voir la suggestion affichant le code Python recommandé qui rendra vos données plus propres et plus fiables pour Fin. Sélectionnez Tester le code pour voir le résultat retourné.
Si vous êtes satisfait de l’instruction de retour, sélectionnez Accepter la suggestion pour améliorer significativement la qualité et la précision des réponses de Fin à partir des données de votre connecteur.
Mappage d’objets
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 ensuite l’utiliser pour résoudre les questions. La réponse est générée à partir de la section « Test response ». Chaque ligne correspond à un point de données dans la réponse JSON.
Une fois que vous avez configuré l’onglet Données, continuez à la Phase 3 : Fin pour définir comment Fin utilise ce connecteur, et à la Phase 4 : Sécurité pour configurer l’authentification et effectuer des contrôles de sécurité avant la mise en production.
Phase 3 : Fin
Cet onglet détermine comment Fin interagit avec le connecteur.
Comment Fin doit-il utiliser ce connecteur ?
Choisissez entre deux modes :
Activé (déclenchement direct) — Fin déclenche automatiquement le connecteur en fonction de la question du client. Idéal pour les connecteurs en lecture seule comme « Vérifier le statut de la commande » et les requêtes répétitives à fort volume.
Désactivé (déclenchement manuel) — Le connecteur ne s’exécutera pas automatiquement. Vous devrez l’ajouter manuellement à un Workflow, une Tâche, une Procédure ou un Macro. Idéal pour les connecteurs sensibles ou actifs en écriture où vous souhaitez une supervision humaine ou par workflow avant toute exécution.
Audience
Contrôlez qui peut accéder à ce connecteur en utilisant des audiences Fin réutilisables, ou créez une audience personnalisée pour des règles ponctuelles. Par exemple, rendez-le disponible aux clients de votre audience « Enterprise plan », ou restreignez-le aux users connectés avec un email vérifié.
Astuce : Vous pouvez choisir Tout le monde, une audience Fin réutilisable, ou une audience Personnalisée pour des règles ponctuelles. Vous pouvez sélectionner plusieurs audiences Fin, mais vous ne pouvez pas combiner des règles Personnalisées avec une audience Fin. Toute règle d’audience existante que vous avez configurée deviendra une audience Personnalisée pour préserver la fonctionnalité.
Aperçu Fin
Utilisez l’aperçu Fin pour voir exactement comment Fin répondra en utilisant ce connecteur avant de le mettre en production.
Phase 4 : Sécurité
La dernière étape avant la mise en production. Cet onglet gère le contrôle d’accès aux données clients.
Authentification client
Activez ceci pour appliquer les règles d’authentification de votre espace de travail avant que le connecteur puisse accéder ou afficher des informations sensibles. Les règles d’authentification sont configurées dans Paramètres > Espace de travail > Sécurité > Authentification client.
Contrôle de sécurité
Effectuez un diagnostic pour évaluer la sécurité de votre configuration API. Tout risque est mis en évidence avec des recommandations exploitables — résolvez-les avant de mettre le connecteur en production.
Important : Il existe plusieurs façons potentielles pour que Fin partage accidentellement des informations d’un autre user lors du passage de paramètres. Consultez nos paramètres recommandés pour mieux atténuer ces risques.
Une fois tous les contrôles passés, enregistrez votre connecteur et mettez-le en production.
Déploiement des connecteurs de données
Nous recommandons d’utiliser les règles d’audience pour déployer les connecteurs de données par phases auprès de votre base clients. Cela vous permet de valider les performances des connecteurs de données et d’apporter des ajustements si nécessaire.
Si vous rencontrez des problèmes où votre connecteur de données ne se déclenche pas pour un user, assurez-vous d’avoir supprimé toutes les règles d’audience spécifiques à votre entreprise que vous auriez pu ajouter lors de la phase de test.
Dépannage
À des fins de dépannage, toutes les données de réponse générées par les connecteurs de données déclenchés par Fin sont enregistrées pendant 14 jours. Vous pouvez accéder à ces journaux sous l’onglet Connecteur de données > Journaux. Vous pouvez consulter les données de réponse en fonction du type de données auxquelles Fin a accès.
Réponse entière – Réponse complète et non modifiée
Réponse expurgée & formatée – Après transformation
Aucune donnée de réponse
FAQ
Puis-je utiliser les connecteurs de données pour envoyer des attributs lors du transfert d’une conversation Fin vers une plateforme tierce (autre que Zendesk/Salesforce) ?
Puis-je utiliser les connecteurs de données pour envoyer des attributs lors du transfert d’une conversation Fin vers une plateforme tierce (autre que Zendesk/Salesforce) ?
Si vous essayez d’envoyer une requête POST (par exemple, avec une structure comme ci-dessous), utilisez plutôt vos options de transfert de workflow Fin :
{
"body": "the conversation with Fin",
"from": "users_email_address",
"to": "our_ticketing_email_address"
}
Les options de transfert de workflow incluent le transfert avec JavaScript et le transfert vers URL, avec la possibilité d’inclure le contexte de la conversation via des résumés générés par IA.
1. Transfert avec JavaScript
Cela vous permet de définir une fonction handoff_with_javascript dans votre application Messenger qui peut :
Collecter le résumé de la conversation (via « AI Add Summary Note »)
Accéder à l’email de l’utilisateur (en utilisant des attributs)
Envoyer un fetch() ou XMLHttpRequest à votre point de terminaison externe avec la structure souhaitée
En savoir plus ici 👉 Transfert avec JavaScript
2. Transfert vers URL
Cette option redirige uniquement l’utilisateur vers une page spécifique, elle ne transmet pas une requête POST ni ne transporte les données de la conversation. Elle ne conviendrait donc pas à votre cas d’utilisation si vous essayez de POSTER du JSON.
Configuration recommandée
Utilisez le JavaScript hand-off, et incluez une logique telle que :
handoff_with_javascript = function (params) {
const userEmail = params.user.email;
const summary = params.conversation_summary;
fetch('https://your-endpoint.com/api', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
body: summary,
from: userEmail,
to: 'your_support@company.com'
})
});
}