Les Data connectors offrent un moyen puissant de fournir des réponses personnalisées en se connectant aux données de vos systèmes tiers. Au lieu que les clients attendent que les teammates recherchent manuellement l'information ou soient dirigés pour la trouver eux-mêmes, Fin peut accéder instantanément aux données pertinentes et élaborer une réponse personnalisée.
Pour garantir que ces Data connectors fonctionnent correctement et soient utilisés dans les bons scénarios, voici quelques meilleures pratiques à considérer…
Rédiger des invites efficaces pour les Data connectors
L'une des étapes les plus importantes est de rédiger une invite efficace dans la section Fin de votre Data connector.
Vous devez écrire 3 à 5 phrases pour décrire quand l'agent Fin AI doit déclencher ce Data connector. Soyez aussi précis que possible et assurez-vous d'inclure une ou plusieurs des options suivantes :
Exemples des types de requêtes clients qui seraient répondues par ce Data connector.
Phrases clés que les clients pourraient utiliser.
Scénarios courants dans lesquels le déclenchement de ce Data connector serait approprié.
Vous pouvez également consulter les modèles recommandés par l'IA comme exemple.
Soyez descriptif
Expliquez clairement quand ce Data connector doit être utilisé et les types de détails qu'il doit fournir.
Bonne pratique | Utilisez ce Data connector pour obtenir des détails sur les commandes du client et aider à résoudre tout problème lié à une commande. Ce Data connector fournira tous les détails de la commande pour le client, comme le statut de la commande, les articles achetés, l'adresse de livraison, les informations de suivi ou d'autres détails pertinents de la commande. |
Mauvaise pratique | Utilisez ce Data connector pour obtenir des informations sur leur commande. |
Évitez d'utiliser des pronoms
Remplacez les pronoms tels que « nous », « nous », et « leur » par le nom propre auquel vous faites référence, comme le nom de votre entreprise.
Bonne pratique | Utilisez ce Data connector pour consulter la consommation d'électricité d'un client avec Examply. |
Mauvaise pratique | Utilisez ce Data connector pour consulter leur consommation d'électricité avec nous. |
Soyez précis
Utilisez des scénarios courants dans lesquels le déclenchement de ce Data connector serait approprié.
Bonne pratique | Utilisez ce Data connector pour consulter les incidents non résolus, comme lorsque les clients veulent savoir quand un incident a commencé, le statut actuel du problème, quels produits ou services sont affectés par un incident, ou si la performance du système est revenue à la normale. |
Mauvaise pratique | Utilisez ce Data connector pour consulter les incidents non résolus. |
Incluez des phrases clients
Regardez comment les clients ont formulé leurs requêtes dans les conversations précédentes et incluez les mots-clés et phrases qu'ils utilisent.
Bonne pratique | Recherchez ces phrases clés comme « commande échouée », « problème avec les commandes », « commandes n'apparaissant pas dans le système », « difficulté avec la commande ». |
Mauvaise pratique | Ne pas inclure les phrases clés des clients. |
Choisissez le bon point de terminaison API
Pour fournir aux clients les bonnes données, il est important de choisir le bon point de terminaison API, qu'il provienne d'une application tierce ou d'un système externe appartenant à votre entreprise.
Si vous ne savez pas par où commencer, vous pouvez demander à un ingénieur de vous aider à déterminer quelle API renverra les données requises.
Par exemple, si vous avez un système de réservation interne qui stocke les détails de réservation d'un client, vous voudrez utiliser une API pour ce système qui peut accéder directement aux détails de réservation.
Vous voudrez également utiliser une API qui peut trouver les détails d'un client en utilisant un identifiant unique comme paramètre, comme un ID ou une adresse e-mail.
Si vous décidez d'utiliser le nom ou l'adresse e-mail d'un client comme paramètre de requête, et qu'il a plusieurs réservations, vous devrez probablement préciser la requête en utilisant la date de la réservation. Plutôt que de demander plusieurs données, il serait optimal de ne demander qu'une seule : l'ID de réservation.
De cette façon, vous pouvez collecter l'ID de réservation comme donnée d'entrée, ce qui incitera Fin à obtenir cette information du client dans la conversation. Ensuite, l'ID peut être inséré dans le point de terminaison en survolant le menu à la fin du champ d'entrée URL.
Astuce : Les Data connectors prennent désormais en charge les réponses API JSON et XML. Si votre système externe ne fournit que du XML, vous pouvez toujours le connecter directement — Intercom convertira automatiquement le XML en JSON, vous permettant d'utiliser les données dans Fin, Workflows, et l'Inbox sans étapes supplémentaires.
Vous voudrez également vous assurer d'utiliser les bons en-têtes HTTP pour la requête. Si ceux-ci sont utilisés dans plusieurs Data connectors, vous pouvez les ajouter en tant que jeton d'authentification stocké, qui les sauvegardera en toute sécurité dans votre espace de travail.
En reprenant notre exemple de réservation, supposons qu'un client souhaite reprogrammer son voyage pour un autre jour. S'il existe un Data connector disponible pour vérifier les tarifs et la disponibilité des réservations, Fin le choisira automatiquement dans la même conversation.
Lorsque vous choisissez les points de terminaison API à utiliser pour les Data connectors, vous pouvez envisager des cas où les données dont vos clients ont besoin se trouvent sur plusieurs points de terminaison.
Pour que le client puisse voir les tarifs et la disponibilité, vous pouvez créer un autre Data connector vers un point de terminaison contenant ces informations.
Créez des connexions sécurisées et sûres
Vérification d'identité
Pour un appel le plus sécurisé, nous recommandons d'utiliser « Email » ou « User ID » sur l'objet People pour faire correspondre l'utilisateur dans votre système.
Intercom vous permet actuellement uniquement de vérifier les valeurs d'email ou d'ID utilisateur provenant de Messenger. Nous vous encourageons vivement à authentifier les users dans Messenger avec des JSON web tokens (JWTs).
Vérification de l'email avec un code à usage unique (OTP)
Utilisez la vérification par email pour les connecteurs de données avec OTP afin de fournir une étape de vérification supplémentaire avant l'utilisation d'un connecteur de données en demandant aux clients de vérifier leur identité via un code unique et sensible au temps envoyé par email.
Protection contre les fuites de données
Il y a généralement deux façons dont les données peuvent être compromises :
Un user modifie malicieusement l'un de ses propres attributs - Par exemple, en définissant "user_shopify_id=123", où 123 est l'ID Shopify d'une victime. Ensuite, ces données sont poussées ou extraites de Shopify pour l'ID 123, et elles sont associées au user malveillant dans Intercom.
Un user manipule des données chez un tiers, et un connecteur de données importe des données compromises dans Intercom - Par exemple, un user s'inscrit chez un tiers en utilisant le numéro de téléphone d'une victime. Ensuite, un connecteur de données interroge ce tiers et synchronise ce numéro de téléphone avec un attribut people dans Intercom. Maintenant, le user a remplacé son numéro de téléphone par celui de la victime.
Pour éviter que cela ne se produise, testez toujours votre connecteur de données avant de le mettre en production afin de vous assurer qu'il est correctement configuré.
Points clés à vérifier :
Assurez-vous que votre connecteur de données renvoie des données pertinentes pour le user correspondant.
Assurez-vous que vos données sont correctement stockées dans vos attributs Intercom mappés.
Utilisez la transformation des données pour restreindre les données
Les charges utiles non structurées ou trop volumineuses provenant des API peuvent entraîner des réponses basées sur l'IA (comme Fin ou d'autres agents AI) qui hallucinent, interprètent mal ou échouent simplement à fournir des réponses claires. En utilisant des blocs de code dans les connecteurs de données, vous pouvez prétraiter, filtrer ou modifier 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.
Conseils :
Utilisez toujours
returnpour votre résultat principal.Imprimez uniquement pour le débogage (par exemple,
print('Processing order', order['id'])).Restez simple : Évitez de tout transformer en même temps — une transformation claire par bloc de code est préférable.
Validez la forme de la sortie : Assurez-vous que la sortie correspond à ce que Fin (ou votre étape de mappage) attend.
Pas d'importations au-delà des modules approuvés : Modules Python standard (
math,decimal,re,datetime,datetime.timezone,json,random,time). Nous ajouterons plus de modules au fil du temps selon les besoins.
Exemples pratiques
Voici 4 modèles courants, chacun avec un exemple réaliste utilisant les dernières exigences (y compris return).
1. Réduction des charges utiles volumineuses pour Fin
Les API renvoient souvent trop de données. Disons que votre réponse inclut 1 000 produits, mais vous ne voulez que les 5 premiers pour Fin afin d'éviter les hallucinations.
api_response = inputs['data']
# Reduce payload to just the first 5 products
result = api_response[:5]
return result
2. Gestion des dates dans les réponses API
Parfois, les LLM (comme Fin) interprètent mal les chaînes de dates, surtout avec les fuseaux horaires. Utilisez Python pour convertir toutes les chaînes de dates en un format ISO uniforme avec UTC explicite.
import datetime
def to_iso_utc(date_str):
try: # Adjust this format as needed!
dt = datetime.datetime.strptime(date_str, "%Y-%m-%d %H:%M:%S")
dt = dt.replace(tzinfo=datetime.timezone.utc)
return dt.isoformat()
except Exception as e:
print(f"Error parsing {date_str}: {e}")
return date_str
api_response = inputs['data']
for item in api_response:
if 'created_at' in item:
item['created_at'] = to_iso_utc(item['created_at'])
return api_response
3. Filtrage des résultats API pour une valeur de champ spécifique
Supposons que vous ne vouliez retourner que les voitures où make est 'toyota' (voir vos captures d'écran !).
api_response = inputs['data']
filtered = [car for car in api_response if car.get('make', '').lower() == 'toyota']
return filtered
4. Aplatissement des lignes imbriquées pour les commandes récentes
Si votre réponse API est profondément imbriquée (commandes, avec des lignes à l'intérieur de chacune), aplatissez-la pour Fin :
orders = inputs['data']['orders']
result = []
for order in orders:
for item in order['line_items']:
result.append({
"order_id": order['id'],
"item_name": item['name']
})
return result
Retournez des liens profonds cliquables depuis votre connecteur de données
Si votre connecteur de données renvoie une URL que vous souhaitez que Fin présente comme un lien cliquable, vous avez deux options.
Option 1 : Formatez le lien dans votre réponse API
Incluez la syntaxe de lien markdown directement dans le texte renvoyé par votre API. Fin l'affichera comme un lien cliquable dans la conversation.
Utilisez ce format pour afficher un texte de lien personnalisé :
[View Dashboard](beyond://account/dashboard)
Ou ce format si vous voulez que l'URL elle-même soit visible et cliquable :
[beyond://account/dashboard](beyond://account/dashboard)
Option 2 : Utilisez les instructions de Fin pour formater le lien
Si votre API renvoie une URL simple dans un attribut de données, vous pouvez demander à Fin de la formater comme un lien cliquable en utilisant des instructions. Référez-vous au nom du connecteur de données et à l'attribut contenant le lien profond, et dites à Fin de le présenter en utilisant la syntaxe de lien markdown.
Utilisez les règles d'audience
Si vous débutez avec les connecteurs de données, vous pouvez expérimenter quelles configurations de connecteurs de données conduisent à plus de résolutions. Une façon de le faire est d'activer d'abord le connecteur de données pour un sous-ensemble de users afin de voir comment il fonctionne. Vous pouvez le faire en utilisant les règles d'audience.
Les règles d'audience peuvent être sélectionnées à partir d'une liste d'attributs d'entreprise ou de contact déjà disponibles dans votre espace de travail. Si vous avez Shopify, Statuspage ou Stripe installés, vous pouvez également accéder aux attributs spécifiques à l'application.
Si un attribut que vous souhaitez utiliser n'existe pas, vous pouvez configurer des attributs de données personnalisés pour identifier les users qui répondent aux critères que vous souhaitez cibler pour le connecteur de données.
Une fois la règle créée, vous pouvez voir un aperçu des users qui peuvent recevoir une réponse alimentée par le connecteur de données.
Utilisez des contrôles de sécurité pour protéger vos connecteurs
Avant de mettre un connecteur en production, exécutez les contrôles de sécurité intégrés dans l'onglet Sécurité. Ceux-ci mettent en évidence les risques potentiels avec des recommandations exploitables afin que vous puissiez prendre des décisions éclairées avant la mise en production.
Les contrôles peuvent inclure :
Les attributs de données client ne sont pas vérifiés — si les attributs de données client peuvent être mis à jour sans vérification de l'user, ajoutez une vérification de l'user.
Les données collectées par Fin pour ce connecteur nécessitent une révision — si Fin collecte des informations auprès des clients avant d'appeler votre API, validez d'abord les entrées dans votre backend.
Les Workflows utilisant ce connecteur de données nécessitent une révision — si certains workflows présentent un risque d'exposition de données client sensibles, révisez-les pour les valider dans votre backend.
Un en-tête de requête pour ce connecteur de données nécessite une révision — si les détails client sont envoyés avec chaque requête, assurez-vous que votre API vérifie la valeur.
Chaque vérification comprend des étapes claires pour résoudre le problème. Résolvez tous les risques signalés avant de mettre le connecteur en service.
Analysez les conversations pour stimuler les optimisations
Chaque data connector dispose d'un tableau de bord santé dédié où vous pouvez évaluer l'impact et repérer des opportunités d'amélioration des performances. Allez dans Paramètres > Intégrations > data connectors et cliquez sur un connecteur pour ouvrir son tableau de bord. De là, vous pouvez consulter les taux de réussite, la latence d'exécution, la répartition des statuts HTTP et la catégorisation des types d'échec — tous filtrables par fenêtre temporelle (1h, 6h, 24h, 7j ou 14j). Pour les détails d'exécution individuels, sélectionnez l'onglet Logs. Au-delà du tableau de bord, examinez les conversations où un data connector a été utilisé pour voir ce qui a bien fonctionné ou ce qui a manqué sa cible.
Si vous utilisez des attributs de données personnalisés pour cibler l'audience, vous pouvez ensuite utiliser cet attribut pour filtrer dans l'inbox et voir comment il a performé, et si des ajustements doivent être faits.
Quelques questions à considérer incluent :
Le data connector s'est-il déclenché dans le bon cas ?
Un coéquipier a-t-il dû intervenir, et si oui, à quelle étape ?
Le data connector a-t-il fourni les bonnes informations au client en fonction de ce qui a été demandé, alors que la question du client portait en réalité sur autre chose ?
La réponse aurait-elle pu être étayée par des informations supplémentaires de votre Knowledge Hub ?
Fin ne peut pas interroger les attributs personnalisés ni les données d'événements pour obtenir des 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 aux sources de données externes via API.