# 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