Connecter le logiciel de votre clinique

Un outil, c’est une requête HTTP vers l’API de votre logiciel. Pendant un appel, votre agent IA :

1. décide d’utiliser l’outil, selon sa Description;
2. remplit, à partir de la conversation, les valeurs dont la requête a besoin (AlloMia les appelle des variables);
3. envoie la requête et lit ce que votre API répond;
4. répond au patient dans ses propres mots.

La page Outils sert seulement à ces connexions. Les textos, les transferts d’appel, les documents de la clinique et les campagnes d’appels ont leurs propres pages sous Outils et actions, pour les gestionnaires de la clinique. Consultez Configurer votre agent IA.

• Un accès au tableau de bord AlloMia de votre clinique. Toute personne du compte de la clinique, avec le rôle Propriétaire ou Utilisateur, peut créer, modifier et supprimer des outils.
• La documentation de l’API de votre logiciel : l’URL du point de terminaison, la méthode HTTP, la façon de s’authentifier, et le JSON attendu et retourné.
• Un point de terminaison accessible depuis Internet, idéalement en HTTPS. Les requêtes viennent des serveurs d’AlloMia, pas du réseau de votre clinique. Si votre pare-feu n’accepte que des adresses connues, écrivez à support@medfarsolutions.com avant de commencer.
• Des identifiants créés seulement pour AlloMia, avec seulement les accès dont l’agent a besoin.
• Un environnement de test, si votre logiciel en a un. Les tests et les appels d’essai envoient de vraies requêtes.

1. Dans le menu de gauche, cliquez sur Outils et actions, puis sur Outils (Tools & Actions et Tools si votre tableau de bord s’affiche en anglais).
2. Cliquez sur + Outil. Un nouvel outil s’ouvre dans l’onglet Détails.
3. Dans Nom, tapez de 3 à 64 caractères : commencez par une lettre minuscule et n’utilisez que des lettres et des chiffres, par exemple verifierDisponibilites. Cette règle passe toutes les vérifications du tableau de bord. Donnez à chaque outil un nom différent.
4. Dans Description, dites à l’agent quand utiliser l’outil et ce qu’il retourne (voir la section suivante).
5. Laissez Exécution asynchrone et Validation stricte désactivés. Pour l’instant, ils n’ont aucun effet pendant les appels.

L’agent lit la description pour décider quand utiliser l’outil. Rédigez-la comme une consigne :

• Quand l’utiliser, et ce que l’agent doit savoir avant.
• Ce qu’il retourne.
• Quand ne pas l’utiliser, si un autre outil fait quelque chose de proche.

Exemple : « Utilise cet outil pour trouver les plages de rendez-vous libres. Appelle-le quand le patient a dit quel jour il souhaite. Retourne les heures libres de ce jour-là. »

1. Dans l’onglet Authentification, choisissez comment AlloMia se connecte à votre API et ajoutez les en-têtes HTTP dont elle a besoin. Consultez Sécuriser une connexion au logiciel de votre clinique.
2. Dans l’onglet Connexion, choisissez la Méthode HTTP : GET, POST, PUT, PATCH ou DELETE.
3. Dans Point de terminaison URL, tapez l’URL complète, par exemple https://api.exemple.com/v1/plages?date={{date}}.
4. Dans Délai d’expiration, indiquez combien de secondes AlloMia attend une réponse (3 par défaut, jusqu’à 300). Choisissez un peu plus que la réponse normale la plus lente de votre API.
5. Dans Nombre de tentatives, indiquez combien de fois AlloMia peut renvoyer la requête (3 par défaut, jusqu’à 5). Voir « Bon à savoir » plus bas.
6. Ajoutez les variables (section suivante).
7. Pour POST, PUT et PATCH, rédigez le corps dans l’onglet Corps de la requête (voir plus bas).
8. Cliquez sur Enregistrer les paramètres, en bas à droite. Le bouton reste gris tant que Nom et un Point de terminaison URL valide ne sont pas remplis.

Une variable est une valeur que l’agent recueille pendant l’appel et met dans la requête. Dans l’onglet Connexion, sous Variables, cliquez sur Ajouter une variable, puis remplissez :

• Nom de la variable : le nom utilisé dans les espaces réservés, par exemple date.
• Type : Chaîne, Nombre, Booléen, Tableau (choisissez le type de ses Éléments) ou Objet (ajoutez ses Propriétés). Les types simples sont les plus fiables.
• Description : ce que l’agent doit y mettre, et dans quel format. Par exemple : « Le jour souhaité par le patient, au format AAAA-MM-JJ. »
• Obligatoire : activé si l’agent doit avoir cette valeur avant d’utiliser l’outil.
• Valeur : une valeur d’exemple pour l’onglet Tests. Pendant les appels, AlloMia l’utilise aussi quand l’agent omet une variable facultative. Utilisez donc des données de test sans conséquence, jamais les renseignements d’un vrai patient.

Pour utiliser une variable, écrivez son nom entre doubles accolades : {{date}}. Les espaces réservés fonctionnent dans l’URL, dans les valeurs des en-têtes et dans le corps de la requête.

• Dans l’URL, la valeur est insérée telle quelle, sans encodage d’URL. Gardez le texte libre, comme les noms, dans le corps.
• Pour les requêtes GET, mettez vous-même chaque variable dans l’URL. Pendant les appels, AlloMia ne les ajoute pas à la chaîne de requête.
• Vous pouvez aussi utiliser {{callId}}, un identifiant qu’AlloMia donne à chaque appel, par exemple pour retrouver les requêtes dans vos journaux.

Dans l’onglet Corps de la requête, rédigez le JSON attendu par votre API, avec les espaces réservés sans guillemets :

{ "date": {{date}}, "motif": {{motif}} }

AlloMia ajoute les guillemets autour des valeurs texte et laisse les nombres et les valeurs true ou false tels quels. Une fois les valeurs remplies, le corps doit être un JSON valide. AlloMia envoie Content-Type: application/json, sauf si vous choisissez un autre type sous En-têtes HTTP, dans l’onglet Authentification. Les requêtes GET n’ont pas de corps.

• Quand votre API répond avec un statut 2xx, l’agent reçoit le corps de la réponse, en JSON ou en texte, et s’en sert pour répondre.
• Avec tout autre statut, l’agent reçoit le statut et le corps comme une erreur, et répond selon ses instructions.
• L’agent lit toute la réponse. Ne retournez que ce dont il a besoin, avec des noms de champs clairs, par exemple "heuresLibres": ["09:00", "10:30"].
• Ce que votre API retourne est enregistré avec l’appel : on le voit dans la transcription de l’appel, dans Journal d’appels.

Dans les instructions de l’agent, dites quoi faire si l’outil échoue, par exemple : « Si tu ne peux pas consulter l’horaire, propose que la clinique rappelle le patient. » Consultez Rédiger les instructions de votre agent IA.

• AlloMia peut envoyer la même requête plus d’une fois : quand votre API répond avec une erreur temporaire comme 429, 500, 502, 503 ou 504 et, pour un outil qui utilise une authentification, quand votre API ne répond pas avant la fin du Délai d’expiration. Assurez-vous qu’une requête répétée ne crée pas un deuxième rendez-vous. Un Nombre de tentatives de 0 est traité comme 3.
• Si votre API ne répond pas avant la fin du Délai d’expiration, la requête échoue et l’agent en est informé.
• Vous pouvez choisir ce que dit l’agent pendant qu’il attend. Consultez Ce que dit l’agent pendant qu’il cherche une information.

1. Dans le menu de gauche, cliquez sur Agents IA, puis sur l’agent IA dans la liste Mes agents.
2. Cliquez sur l’onglet Outils et actions.
3. Trouvez votre outil : il porte l’étiquette Function. Activez son interrupteur.
4. Cliquez sur Enregistrer les paramètres. Les appels qui commencent ensuite peuvent utiliser l’outil.

Consultez Activer ou désactiver les actions de votre agent IA.

1. Dans l’onglet Tests de l’outil, cliquez sur Tester l’outil. Consultez Tester une connexion.
2. Dans l’agent IA, cliquez sur Parler avec l’agent et demandez quelque chose qui a besoin de l’outil, par exemple : « Avez-vous de la place mardi matin? » Si l’outil prend des rendez-vous, le rendez-vous est réel : annulez-le ensuite.
3. Dans Journal d’appels, ouvrez l’appel d’essai. Dans la Transcription de la conversation, une ligne Appel d’outil montre les valeurs envoyées par l’agent, et une ligne Résultat d’outil montre la réponse de votre API. Cliquez dessus pour voir les détails.

• Enregistrer les paramètres reste gris : remplissez Nom et un Point de terminaison URL complet qui commence par https:// ou http://.
• « Veuillez remplir tous les champs obligatoires » s’affiche alors que Nom, Description et Point de terminaison URL sont remplis : le message vise aussi les autres onglets. Vérifiez que chaque variable a un nom, un type et une description, que chaque en-tête a une clé et une valeur, et que tous les champs d’authentification sont remplis.
• L’agent n’utilise jamais l’outil : vérifiez son interrupteur dans l’onglet Outils et actions de l’agent, puis précisez dans la description quand l’utiliser.
• L’agent envoie de mauvaises valeurs : précisez les descriptions des variables, avec le format attendu.
• Le test fonctionne, mais pas les appels : pour GET, vérifiez que chaque variable est dans l’URL. Comparez ensuite les lignes Appel d’outil et Résultat d’outil de la transcription avec les journaux de votre API.
• Deux outils se comportent comme un seul : deux outils activés pour le même agent ont le même nom. Renommez-en un.