Vizir

# L'appel API ne marche pas tout le temps

La raison peut-être multiple. On va voir comment la découvrir étape par étape. 1°) Est ce que l'appel API a déjà marché ? Si oui, quelles sont les différences entre l'appel qui ne fonctionne pas et ceux qui ont fonctionnés? Voici quelques pistes de réflexions:

  • le token est expiré ?
  • la connexion au VPN n'est plus valide
  • la route API a changé
  • les données (body ou query params) que vous envoyez ne sont pas correctes

Si vous n'avez pas trouvé l'origine du bug à cette étape vous pouvez passer à l'étape 2.

2°) Essayez de faire le call API depuis votre ordinateur personnel via un outil comme postman par exemple. Vous pourrez avoir plus d'information sur la raison de l'échec. Si le call API fonctionne en local. Vérifiez dans l'interface Workflow > History que vous avez bien les mêmes paramètres que le call qui n'a pas fonctionné.

Ici vous devriez avoir compris la cause du problème. Si vous ne l'avez toujours pas compris, vous pouvez contacter le support avec les résultats des deux étapes précédentes (screenshot, hypothèses invalidées, ...)

TIP

Nous conseillons de TOUJOURS ajouter une étape sur les call API si le status code est différents de celui espérer pour vous envoyer un email d'avertissement que l'action na pas été bien réalisée. Ainsi, vous pourrez la re-déclencher manuellement et comprendre plus facilement la cause du problème.

# Comment s'intégrer avec une API SOAP

La plupart des API que vous allez rencontrer seront en REST (ou GraphQL), cependant il arrive toujours que certains produits soient seulement compatible avec des services SOAP.

Nous allons voir comment s'interfacer avec ces services.

  • 1°) Téléchargez un outils comme SOAP ui Télécharger (opens new window)
  • 2°) Créez un nouveau SOAP Project
  • 3°) Entrez l'url du service SOAP en question avec un ?wsdl à la fin de l'url pour récupérer tous les services
  • 4°) Vous aurez ensuite toutes les actions possibles qui vont s'afficher dans la navigation Navigation SOAP
  • 5°) Sélectionnez l'action qui vous intéresse. "Ouvrez la"
  • 6°) Entrez tous les champs qui sont nécessaires Call SOAP
  • Cliquez sur le bouton "play"

Si l'appel SOAP ne fonctionne pas, refaites les étapes précédentes pour trouver le bug.

Une fois que vous êtes capable de faire un appel SOAP vers votre service vous pouvez copier le body en XML et le copier dans le body d'un appel Webhook sur l'interface Vizir.

  • url: c'est la même url que dans SOAP UI
  • Méthode: POST
  • body: coller le body au format xml, vous pouvez ajouter des variables via l'écriture { nom_de_la_variable }
  • Headers: Il faut ajouter Content-Type: text/xml pour que les données soient envoyées au bon format.

Ensuite vous pouvez décider de sauvegarder la réponse.

# Formatter une date

Avec votre chatbot, vous avez sûrement déjà voulu récupérer une date (opens new window) auprès de vos utilisateurs. Sa date de naissance par exemple. Vous avez donc du créer une compétence action avec une ressource de collecte pour la date. Vous avez ensuite paramétré cette ressource avec un format de réponse imposé qui peut être dans ce cas  de deux types : date ou entity>time.

Ces deux formats ont chacun leur qualités et leurs défauts :

Format date :

  • Limite l'utilisateur à un seul format accepté (JJ/MM/AAAA)
  • Permet de mettre des limitations de dates minimum et maximum

Format entity>time :

  • Permet à l'utilisateur d'écrire sa date sous le format qu'il souhaite grâce à l'intelligence artificielle.
  • Propose un format de sortie peu lisible (avec des informations jusqu'à la milliseconde)

Bien souvent, la liberté de l'utilisateur est un critère très important pour un chatbot, donc on se tournera plus facilement vers la solution entity>time.

Les questions suivantes se posent donc  : Comment utiliser le format de sortie peu lisible dans mon API ? Comment proposer une écriture lisible à mes utilisateurs au moment où ils valident leurs réponses ?

En clair, comment éviter ça :

C'est très simple ! Il suffit de créer un workflow (opens new window) de modification de date qui sera déclenché dès lors que votre ressource date est définie !

Rendez-vous donc dans l'onglet workflows et créez un nouveau workflow (opens new window). Puis ajoutez une étape "Modifier le format d'une date".

Pour paramétrer cette étape de workflow il vous suffit de définir :

  • l'attribut qui correspond à la date dont vous souhaitez modifier le format
  • le nouveau format souhaité
  • le pays qui fait fois pour les dates (comme vous le savez les américains ou britanniques n'écrivent pas les dates comme nous).
  • l'attribut dans lequel sera sauvegardé la nouvelle date formatée.

Enfin, il vous suffit d'appeler cet attribut ("date-formated") plutôt que l'attribut "date" et vous obtiendrez visuellement votre date au bon format.

A vous de jouer !

Pour connaitre l'ensemble des formats qui sont supporté par Vizir vous pouvez vous fier aux formats utilisé par Moment.js visible

TIP

Si vous souhaitez faire des opérations sur les dates, nous vous conseillons de les convertir au format "timestamp" (x) puis de faire les opérations et de repasser au format "date" en fin de workflow.

# Comment récupérer les messages d'erreur en réponse api ?

Vous avez déjà mis en place une intégration API dans votre bot mais elle dysfonctionne et vous ne savez pas pourquoi, vous ne voyez pas le message d'erreur de l'API. Voici comment récupérer les messages d'erreur d'une API de manière lisible dans le bot :

Dans votre call API, allez dans la partie "réponse", cocher le "sauvegarder la réponse dans les attributs" et créer une variable "api_response" avec un chemin vide => cette variable récupérera la totalité de la réponse API dans tous les cas (et donc l'erreur en cas de call défectueux).

A vous de jouer !

# Comment créer son propre connecteur API

Vous souhaitez créer votre propre connecteur API pour aller encore plus loin. C'est possible et ça se passe ici

# Comment créer une nouvelle action API

Vous souhaitez créer votre propre action API pour aller encore plus loin. C'est possible et ça se passe ici

# Moduler une réponse en fonction d'un call API

Alors je vais vous montrer un exemple avec un bot de test qu'on a fait avec nos amis de Bolton, sur les thons Rio Mare (leader du Thon en Italie et dans l'Adriatique 🦈🦈

Le but c'est de faire un bot qui vous permet de :

  1. lui envoyer une photo (un boite de thon ou de sardines par exemple)
  2. il analyse la photo via Computer Vision (celui de Microsoft) et essayer de trouver des mots
  3. s'il trouve le mot sardine, il vous envoie des recettes de sardines, s'il trouve le mot thon, il vous envoie des recettes de thon

# C'est paarrrrti 🚀🚀

Ma compétence action a trois ressources comme 😀

Je chope l'image en validation (je demande pas de validation), et ensuite soit je trouve un mot soit je trouve rien.

Ma validation déclenche le workflow (opens new window) nommé "Vision" dès qu'on a une réponse :

# Voyons de plus près ce workflow 🔎🔎

J'ai donc un webhook (opens new window) sur le computer vision de Microsoft en mot POST

Je lui donne simplement à manger l'URL de mon image soit { tag.image.0.url }

Eeeeet j'oublie pas de stocker la réponse en retour dans un string 👇👇

L'API de Computer Vision nous renvoie un JSON complet avec les mots trouvés.

# Filtrer les réponses en fonction de la réponse de l'API

Je n'ai plus qu'à retourner dans ma ressource de réponse (compétence Vision).

Rionino a 4 type de produits (thon, saumon, sardine, crevettes).

Donc je rentre 4 message et 4 carrousels avec le contenu souhaité.

Je n'ai plus qu'à ajouter ensuite un filtre : vision_response contient {nom du poisson}

Ici un exemple avec le Thon ! 🚀🚀

# Api au format form-data

So I'm not going to write tons of them because it's simple!

You make your call. And you add in the Settings the Content-Type as written below!

Thanks -->

# Qu'est ce que le workflow Empty

Vous pourrez voir lorsque vous allez sélectionner un workflow qu'il existe un workflow empty. Cependant, celui ci ne sera pas visible dans la liste de vos workflow depuis l'onglet workflow.

C'est tout à fait normal 😎

Le workflow Empty est juste ici pour vous permettre de terminer une compétence action sans déclencher de "vrais" workflow. Il est vide et ne déclenche aucune action, cependant il vous permet de terminer un process dans une compétence action.

# Sauvegarder les headers d'une API dans la mémoire du bot

Il arrive que les API renvoient des informations intéressantes dans les headers comme la pagination par exemple.

Vous pouvez stocker la valeur du header de la même façon que le body.

save headers in bot memory

TIP

Il faut ABSOLUMENT que le premier terme du "chemin pour récupérer la valeur" soit headers comme dans l'image ci-dessus.

# Créer une action de type webhook protégé pour une api protégée par Oauth2

Si vous ne souhaitez pas ajouter toutes les actions d'une API, vous pouvez vous simplifiez la vie et en créer une seule action de type "webhook" que vos utilisateurs pourront personnaliser pour exécuter toutes les actions.

Voici un exemple

  • Créer l'intégration API en suivant le guide sur la création d'une intégration voir la doc

  • Ajouter une première (et dernière) action.

  • Renseigner tous les champs comme ci dessous

    • path: vous pouvez définir le path comme étant une variable. Etant donné qu'il va très certainement contenir des "/" ne pas oublier de mettre 3 accolades.
    • method: Sélectionnez {{request_type}\ pour laisser la possibilité à vos utilisateurs de modifier le type de requête
    • Pour le payload, indiquez simplement body pour permettre à l'utilisateur de formatter lui même le body de la requête.
    • Enfin laissez vide le champ de réponse car la réponse sera différente en fonction du chemin API utilisé.

Ensuite cliquez sur Voir les paramètres de l'action pour personnaliser le type de champs de:

  • path (input type: input, vendor type: string)
  • request_type (Input type: input, vendor type: string)
  • body (input type: json, vendor type: object)

Une fois validée vous pouvez profitez de la connection à l'API Oauth2 pour toutes les routes API.

# Utiliser un JSON dans le body d'un webhook depuis la mémoire (attribut)

Vous souhaitez renseigner le body du json via la mémoire du chatbot vizir.

Pour vous assurez que celle ci soit bien passée en JSON, vous pouvez maintenant rajouter l'indication | vzToJSON pour vous assurer que Vizir envoie un JSON à l'api.

Voici un exemple

JSON in api call

← Mémoire: Attributs, tags, et events (push test here) →