Passer au contenu principal

Créer des connecteurs de données pour Fin

Comment configurer Fin avec des réponses personnalisées nécessitant des données de systèmes externes.

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 :

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… Les requêtes clients exemples 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 :

  • Quand disponible, Fin recueillera l’information depuis le contexte de la conversation.

  • Vous pouvez connecter des connecteurs de données à des APIs qui renvoient du XML. Intercom convertira automatiquement les réponses XML en JSON, vous n’avez donc pas besoin de faire de conversion manuelle ou d’utiliser un outil tiers. Cela signifie que vous pouvez connecter une plus grande variété 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 bon jeton d’authentification et de spécifier les bons en-têtes (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 :

  1. 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.

  2. Réponse 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 bon, 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.

Note : Lors de l’utilisation de Restreindre manuellement l’accès, les champs dont les noms contiennent des caractères spéciaux — tels que parenthèses (), signes plus +, ou barres obliques / — peuvent être silencieusement exclus des données reçues par Fin, à cause d’un bug de correspondance de chemin. Pour contourner cela, renommez les champs affectés en supprimant les caractères spéciaux avant de restreindre l’accès. Sinon, utilisez l’accès complet aux données si la réponse ne contient pas de données sensibles.

Vous pouvez aussi modifier les éléments de données individuellement 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 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 utilisant Python — directement dans la configuration de votre connecteur.

Les charges non structurées ou trop volumineuses provenant des APIs 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

  • return statement : Le résultat principal produit par votre bloc de code doit être renvoyé avec une instruction return. 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 supportées (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 supportées 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 les 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 des 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 AI qui hallucinent, interprètent mal ou ne fournissent pas de réponses 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 return, 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.

Astuce : Consultez ces conseils et exemples pratiques pour la transformation des données.

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 limitez-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.

Note : Les modifications du paramètre de déclenchement Fin sont enregistrées en mode brouillon et ne prendront effet qu’après publication. La version en production du connecteur continue d’utiliser ses paramètres existants jusqu’à ce que vous cliquiez sur Mettre en production. Après modification, confirmez toujours que le paramètre est reflété dans la version en production — pas seulement dans le brouillon.

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 cette option 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 signalé 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.

Note : Les connecteurs de données utilisent un système de version brouillon/en production. Toute modification que vous effectuez — y compris sur le paramètre de déclenchement Fin sous l’onglet Fin — est enregistrée en brouillon et n’affectera pas le connecteur en production tant que vous n’aurez pas cliqué sur Mettre en production. Si le connecteur semble se comporter de manière inattendue après une modification, vérifiez si le brouillon mis à jour a été publié. La liste des connecteurs dans Paramètres affiche le statut actuel de chaque connecteur (en production ou brouillon).

Déploiement des connecteurs de données

Nous recommandons d’utiliser des règles d’audience pour déployer les connecteurs de données par phases auprès de votre base client. 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.

Astuce : Vous pouvez dupliquer un connecteur de données existant pour l’utiliser comme point de départ pour un nouveau. Ouvrez le connecteur et cliquez sur le menu ... en haut à droite, puis sélectionnez Dupliquer. La copie s’ouvre en mode brouillon avec tous les paramètres préremplis.

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 et 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) ?

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 AI.

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 du user (en utilisant des attributs)

  • Envoyer un fetch() ou XMLHttpRequest à votre point de terminaison externe avec la structure souhaitée

En savoir plus ici 👉 Hand-off with JavaScript

2. Transfert vers URL

Cette option redirige uniquement l'utilisateur vers une page spécifique, elle n'envoie pas de POST ni ne transmet de données de 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'
})
});
}

Avez-vous trouvé la réponse à votre question ?

Articles connexes