Comment configurer une intégration API personnalisée avec AI Assist

Les instructions ci-dessous s’appliquent uniquement aux ordinateurs de bureau et portables.


tawk.to’s AI Assist prend en charge les intégrations d'API personnalisées qui permettent à votre agent IA d'effectuer automatiquement des recherches et des actions en arrière-plan — comme le ferait un agent humain.

Par exemple, votre agent IA peut :
  • Rechercher dans votre catalogue de produits
  • Vérifier l'état d'une commande ou d'un paiement
  • Consulter les détails de facturation
  • Récupérer les achats passés

Cela permet aux clients d'obtenir des réponses instantanément sans attendre un agent humain.

Les intégrations d'API sont configurées par propriété. Si vous utilisez plusieurs agents IA, vous pouvez activer ou désactiver chaque intégration individuellement pour chaque agent.

Ce guide couvre :
  • Ce dont vous avez besoin avant de commencer
  • Comment configurer l'intégration dans tawk.to
  • Comment tester l'intégration
  • Une référence technique pour les développeurs construisant l'API

Note : Les intégrations sont uniquement disponibles avec les plans Growth, Business et Enterprise.

 Avant de commencer 

Pour configurer une intégration d'API personnalisée, vous aurez besoin de :

  • Un point de terminaison API (endpoint)
    Une URL vers laquelle AI Assist peut envoyer des requêtes et recevoir des données.


    • Un schéma OpenAPI
      Un fichier qui décrit les points de terminaison, les paramètres et les réponses de votre API afin qu'AI Assist sache comment l'utiliser.

    • Identifiants d'authentification (si requis)
      Par exemple : clé API, nom d'utilisateur et mot de passe, ou d'autres méthodes d'authentification prises en charge par votre API.

    Vous utilisez Shopify, WooCommerce ou BigCommerce ?
    Au lieu d'une intégration d'API personnalisée, vous pouvez utiliser les intégrations natives de tawk.to. Consultez ces guides pour des instructions étape par étape :
    Comment intégrer AI Assist avec Shopify
    Comment intégrer AI Assist avec WooCommerce
    Comment intégrer AI Assist avec BigCommerce

    Pour les autres plateformes
    Si vous utilisez d'autres plateformes, telles que :
    • Wix
    • Squarespace
    • Magento
    • PrestaShop
    • Un produit SaaS avec sa propre API
    • Un système backend personnalisé
    — vous aurez besoin d'un développeur pour construire le point de terminaison API et le schéma OpenAPI.

    Si votre plateforme n'expose pas d'API directe, votre développeur peut avoir besoin de créer un service proxy. Les outils courants utilisés pour cela incluent :
    • Google Apps Script
    • Cloudflare Workers
    • Un serveur Node.js

    Si vous n'êtes pas à l'aise pour construire cela vous-même, partagez ce guide avec un développeur. La section Référence technique pour les développeurs ci-dessous explique exactement ce qu'ils doivent implémenter.

    Ajouter l'intégration dans tawk.to


    1. Connectez-vous à votre compte tawk.to, et sélectionnez la bonne propriété.


     

    2. Cliquez sur Automation dans la barre de navigation de gauche.


    3. Cliquez sur Integrations dans le sous-menu de gauche.


    4. Cliquez sur OpenAPI Server sous Custom Tool.



    Vous pouvez également rechercher “OpenAPI” en utilisant la barre de recherche en haut.


    5. Cela ouvre la page de présentation d'OpenAPI Server. Cliquez sur Install dans le coin supérieur droit.



    6. Dans le formulaire de configuration, saisissez les détails suivants :
    - URL du fichier de schéma
    Il doit s'agir d'une URL accessible publiquement pointant directement vers un fichier de schéma OpenAPI YAML ou JSON.

    Vous pouvez héberger votre schéma en utilisant des services tels que :
    - GitHub (utilisez l'URL du fichier Raw)
    - GitHub Gist
    - Amazon S3
    - Tout service d'hébergement web

    Vous pouvez également sélectionner Paste Schema et coller votre schéma en JSON.
    Si vous n'avez pas encore de fichier de schéma, consultez la section Référence technique pour les développeurs ci-dessous.

    - URL de base de l'API :
    Il s'agit de l'URL racine de votre API. Les points de terminaison définis dans votre schéma seront accessibles relativement à cette URL.

    Exemple :
    Si l'URL de base de votre API est :
    https://script.google.com/macros/s/ABC123

    et que votre schéma définit le point de terminaison :
    /exec

    AI Assist appellera :
    https://script.google.com/macros/s/ABC123/exec



    7. Choisissez la méthode d'authentification requise par votre API.


    - No Auth — si votre API ne nécessite pas d'authentification.


    - API key — saisissez la clé et la valeur. (ex: clé: “x-api-key”, valeur: “votre-clé-secrète”)


    - Basic — saisissez votre nom d'utilisateur et votre mot de passe.


    8. Cliquez sur Save.


    9. Après l'enregistrement, cliquez sur Agents dans le sous-menu de gauche.



    10. Sélectionnez votre agent IA. Ensuite, cliquez sur Tools dans le menu de gauche et assurez-vous que l'intégration est activée sous Status.

     Configurer votre base de connaissances (facultatif) 


    Si vos descriptions de schéma sont claires et spécifiques, AI Assist devrait appeler automatiquement les bons points de terminaison de l'API. Cependant, si AI Assist ne déclenche pas le bon appel d'API, vous pouvez ajouter une instruction à votre base de connaissances.

    Exemple :
    “Si le client pose des questions sur l'état d'une commande, utilisez l'outil d'appel API trackOrder.”

    Pour les étapes détaillées sur la configuration de votre base de connaissances, consultez ce guide :
    Modifier la base de connaissances

     Tester votre intégration 


    Avant de déployer votre intégration, testez-la soigneusement.

    Tester l'API directement
    Utilisez un outil tel que Postman ou un navigateur pour appeler votre point de terminaison API et confirmer qu'il renvoie les réponses attendues.

    Tester à l'aide de l'aperçu AI Assist
    Dans la page des paramètres d'AI Assist, utilisez le panneau d'aperçu du chatbot pour simuler les questions des clients. Exemples de tests :

    • Recherche de produit : “Montre-moi des sacs en cuir”
      Comportement attendu : déclenche un appel API de recherche de produit.

    • Suivi de commande : “Où est ma commande #12345 ?”
      Comportement attendu : déclenche un appel API de suivi de commande.

    • Question sans rapport : “Quel temps fait-il aujourd'hui ?”
      Comportement attendu : ne doit pas déclencher d'appel API.

    Tester les cas limites (edge cases)
    Assurez-vous que votre API gère des situations telles que :
    • Aucun produit trouvé
    • Commande non trouvée
    • Délais ou expirations de l'API
    • Erreurs d'API


      Dépannage 


      Voici quelques problèmes courants que vous pourriez rencontrer lors de la configuration d'une intégration d'API.

      AI Assist n'appelle jamais l'API
      Causes possibles :
      • Le bouton d'état de l'intégration est désactivé
      • Les descriptions du schéma sont trop vagues
      • Les instructions de la base de connaissances ne font pas référence au bon outil


        Comment y remédier :
        • Allez dans Intégration/API et confirmez que l'intégration est activée pour votre agent.
        • Révisez vos descriptions de schéma et assurez-vous qu'elles expliquent clairement quand l'API doit être utilisée.
        • Ajoutez une instruction à la base de connaissances si nécessaire pour guider AI Assist.

        AI Assist dit que la requête n'a pas fonctionné
        Dans le chat, AI Assist peut répondre par un message tel que : “Je n'ai pas pu récupérer cette information.”
        Cela signifie généralement que l'appel d'API a été tenté mais n'a pas renvoyé de données exploitables.


        Les raisons possibles incluent :
        • L'API n'a renvoyé aucun résultat correspondant
        • Les paramètres de la requête étaient incorrects
        • Un problème d'authentification
        • Une erreur d'API ou une expiration

        Comment dépanner :
        • Testez directement le point de terminaison de l'API en utilisant Postman ou un navigateur.
        • Vérifiez que les mêmes paramètres renvoient des résultats valides.
        • Vérifiez que les identifiants d'authentification et l'URL de base de l'API sont corrects.

        Si vous ne parvenez pas à identifier la cause, contactez-nous via le chat en direct. Notre équipe peut inspecter la requête complète.

        Le fichier de schéma ne se charge pas
        Causes possibles :
        • Le fichier de schéma n'est pas accessible publiquement
        • Le schéma n'est pas au format OpenAPI 3.0 valide

        Comment y remédier :
        • Ouvrez l'URL du schéma dans un navigateur pour confirmer qu'elle est accessible.
        • Validez le schéma en utilisant editor.swagger.io.

        Les réponses de l'IA contiennent des informations incorrectes ou générées
        Cela peut arriver si AI Assist génère des informations non présentes dans la réponse de l'API.

        Pour réduire ce comportement, ajoutez l'instruction suivante à votre base de connaissances :
        “Partagez uniquement les informations renvoyées par l'API.”

        Pas sûr qu'AI Assist appelle l'API
        Actuellement, les appels d'outils API ne sont pas affichés dans la répartition des sources de données du panneau d'aperçu. Si vous avez besoin de confirmer que l'API est appelée, contactez-nous via le chat en direct. Notre équipe peut consulter les journaux de requêtes.

         Choses à retenir 


        • AI Assist utilise les descriptions de votre schéma pour déterminer quand et comment appeler votre API. Des descriptions claires améliorent la fiabilité.
        • Chaque requête API est indépendante. AI Assist n'accède pas directement aux réponses d'API précédentes. Cependant, AI Assist peut faire référence aux messages déjà envoyés dans la conversation.
        • Les réponses d'API sont prioritaires sur les autres sources de données. Si les données de l'API sont disponibles, AI Assist les priorisera lors de la génération des réponses.
        • Les conversations longues peuvent être tronquées, ce qui peut empêcher AI Assist de faire référence aux messages antérieurs.

        Mises à jour du schéma
        Bien que l'URL de base de l'API puisse être modifiée à tout moment, l'URL du fichier de schéma ne peut pas être consultée ou modifiée.

        Le schéma est stocké sous forme de cliché (snapshot). Si vous mettez à jour le fichier de schéma à l'URL source, l'intégration ne se mettra pas à jour automatiquement.

        Pour appliquer les modifications du schéma :
        1. Supprimez l'intégration existante.
        2. Ajoutez à nouveau l'intégration en utilisant le schéma mis à jour.

         Bonnes pratiques 



        Référence technique pour les développeurs 

         
        Les sections ci-dessous sont destinées aux développeurs construisant le point de terminaison API et le schéma OpenAPI. Si vous travaillez avec un développeur, partagez cette section avec lui.


        Construire le point de terminaison API
        Votre point de terminaison API doit :
        • Accepter les requêtes HTTP (GET ou POST)
        • Renvoyer des réponses JSON
        • Être accessible publiquement

        La structure de la réponse est flexible, mais elle doit être claire et descriptive.

        Exemple : Réponse de recherche de produit


        Exemple : Réponse de suivi de commande


        Réponses d'erreur
        Rédigez les messages d'erreur comme s'ils pouvaient être montrés au client.

        Exemple :


        AI Assist peut utiliser ces messages lors de la génération de réponses.


        Créer le schéma OpenAPI


        Le schéma doit suivre le format OpenAPI 3.0 (YAML ou JSON).
        Outils recommandés :


        Pour un exemple concret, consultez le modèle de schéma sur GitHub.

        Rédiger de bonnes descriptions de schéma
        Les champs de description de votre schéma aident AI Assist à comprendre quand appeler votre API et comment l'utiliser. Voyez ces descriptions comme des instructions pour l'agent IA, et non comme de la documentation pour développeurs.

        Vos descriptions doivent expliquer :

        • Quand utiliser le point de terminaison
          Exemple : “Utilisez lorsque le client pose des questions sur les produits, l'inventaire ou souhaite parcourir les articles.”
        • Quels paramètres envoyer
          Expliquez d'où proviennent les valeurs et comment elles doivent être formatées. Exemple :
          “Extrayez le mot-clé du message du client.”
        • Comment interpréter la réponse
          Exemple :
        • “Si le stock est à 0, dites au client que l'article est en rupture de stock.”
        • “Si une URL de suivi est présente, incluez-la toujours dans la réponse.”

        Évitez les descriptions vagues telles que :
        • “L'action à effectuer”
        • “Mot-clé de recherche”

        Plus vos descriptions sont spécifiques, plus AI Assist pourra déclencher précisément le bon appel d'API avec les bons paramètres.

         Guides associés 


        Premiers pas avec AI AssistModifier la base de connaissances
        Comment intégrer AI Assist avec Shopify
        Comment intégrer AI Assist avec WooCommerce
        Comment intégrer AI Assist avec BigCommerce
        Comment intégrer AI Assist avec Picqer
        Comprendre les sources de données d'AI Assist
        Déployer plusieurs agents IA sur différents canaux de support
        Utiliser les instructions de la base de connaissances pour l'escalade
        Comment former AI Assist à transférer les chats à des agents humains


        Si vous avez des retours sur cet article, ou si vous avez besoin d’aide supplémentaire :



        Cet article a-t-il été utile ?

        11 sur 18 ont aimé cet article