Intégration avec des API tierces

Cet article présente un exemple de création d’un bot fonctionnant avec l’API interne Wilfire (il envoie et reçoit des informations)

Vous pouvez créer des bots qui interagissent avec d’autres ressources via une API. Par exemple, les bots peuvent répondre à des requêtes en vérifiant s’il est possible de créer un rendez-vous à une certaine date, ou trouver un produit dans une boutique en ligne.

Comment gérer une API tierce à l’exemple de DaData

Prenons les conseils d’API de https://dadata.ru/api/suggest/address comme exemple

Lisez attentivement la documentation des API tierces

Ouvrez votre projet dans Salebot et ouvrez les paramètres avancés dans les réglages d’un bloc ; là, vous devez changer le type de requête en POST-json.

Dans le champ « URL de la requête » saisissez l’URL suivante : https://suggestions.dadata.ru/suggestions/api/4_1/rs/suggest/address

Dans le champ « En-tête de la requête » saisissez l’en-tête au format JSON :

{ "Content-Type": "application/json", "Accept": "application/json", "Authorization": "Token " + token }

Dans le champ «Paramètres JSON » insérez dans la requête elle-même - { "query": "#{CurrencyType}" }

Pour obtenir les résultats, vous devrez également remplir l’onglet « Valeurs stockées ».

Un exemple de la requête est ci-dessous :

Comment enregistrer des valeurs à partir de variables

Tout le monde ne comprend pas cela immédiatement, jusqu’à ce qu’on essaie de le faire soi-même.

Pour commencer, saisissez #{custom_answer} dans le champ de réponse. (La variable #{custom_answer} contient la réponse reçue du serveur mentionnée dans le champ « URL pour une réponse du serveur »)

Lancez le bloc avec la requête pour envoyer la requête et obtenir une réponse. Vous devez analyser la réponse et configurer l’accès aux variables qu’elle contient. Pour cela, vous devez travailler avec l’onglet « Valeurs stockées ».

Regardons un exemple pour mieux comprendre le processus.

À la suite de notre requête #{custom_answer}, une réponse du format suivant est arrivée :

{"suggestions": [{"value": "Livre sterling", "unrestricted_value": "Livre sterling", "data": {"code": "826", "strcode": "GBP", "name": "Livre sterling", "country": "Le Royaume-Uni"}}]}

Maintenant, écrivons dans le champ « Valeurs stockées » notre VALEUR->VARIABLE

suggestions|0|value->CurrencyType; suggestions|0|data|code->CurrencyDigCode; suggestions|0|data|strcode->CurrencyStrCode; suggestions|0|data|country->CurrencyCountry

suggestions - la clé du tableau [{"value": "Livre sterling", "unrestricted_value": "Livre sterling", "data": {"code": "826", "strcode": "GBP", "name": "Livre sterling", "country": "Le Royaume-Uni"}}]

suggestions|0 - la clé du premier élément du tableau {"value": "Livre sterling", "unrestricted_value": "Livre sterling", "data": {"code": "826", "strcode": "GBP", "name": "Livre sterling", "country": "Le Royaume-Uni"}}

suggestions|0|value - la clé de la valeur « Livre sterling »

La clé la plus longue dans ce JSON :

suggestions|0|data|strcode - la clé de la valeur « GBP »

Les clés sont séparées par une barre verticale (|). S’il y a un tableau dans le JSON, alors l’accès à son élément est numéroté, en commençant par le numéro 0, et il est également écrit avec la barre verticale.

Il est nécessaire de répéter tout l’imbrication. Pour plus de confort, vous pouvez visualiser le JSON dans une application JSON-viewer.

Les niveaux d’imbrication sont séparés par des barres verticales. Vous devez donc lister toutes les clés séparées par la barre pour accéder à la valeur.

S’il y a un tableau dans le JSON, alors au lieu de la clé, vous devez indiquer le numéro de l’élément en commençant par 0.

Séparez les phrases d’obtention des variables par le symbole point-virgule (;). Les phrases se composent du lien vers les données dans la réponse et du nom de la variable dans laquelle les enregistrer, séparés par les symboles -> (tiret + chevron).

La requête de recherche est, en quelque sorte, un chemin dans le JSON vers la valeur recherchée.

Développer une API pour les bots

Pour développer une API, vous aurez besoin d’un hébergement sur lequel elle sera basée. Si vous n’en avez pas ou si vous n’êtes pas un as de la programmation, vous pouvez nous contacter et nous développerons l’API pour votre bot et la baserons sur la nôtre. L’hébergement lui-même est gratuit, vous ne paierez que le développement.

Mais pour l’instant, un peu de théorie.

Le bot prend en charge les GET et POST requêtes, ce sont les principaux types utilisés dans la plupart des API publiques.

GET est une requête qui se produit lors d’un clic sur le lien ou à l’ouverture du lien dans le navigateur. Les paramètres d’une telle requête sont transmis aux URL-requests.

La syntaxe des paramètres transmis : après l’URL, il y a un point d’interrogation (?) puis chaque paramètre est séparé par une esperluette (&). Un paramètre se compose du nom et de sa valeur après le signe égal (=). Un exemple d’URL avec un paramètre :

Ici, vous pouvez voir qu’un paramètre nommé « search_query » est partagé et que sa valeur est « queen live aid ». Le « + » ici correspond à l’espace entre les mots ; lorsque vous travaillez avec le logiciel d’édition, vous pouvez simplement laisser les espaces — le bot les remplacera lui-même.

POST est un type de requête qui est généralement envoyé lors du remplissage d’un formulaire sur un site web. La requête transmet les paramètres dans le corps ; bien sûr, ils peuvent être partagés de la même manière que GET, mais cela est rarement fait ainsi. Les paramètres dans le corps peuvent être au format JSON ou sous forme clé-valeur. En tant que clé-valeur, les paramètres partagent des formulaires ; le format JSON est celui qui est le plus souvent utilisé pour les API.

En-tête de la requête. Chaque requête peut avoir un en-tête/titre ajouté. Le format des données partagées et les clés d’accès y sont le plus souvent écrits. En général, nous laissons cet onglet vide, mais il est parfois nécessaire d’y mettre le jeton API ou le type de requête « Content-type » : « application/json » dans de rares cas.

JSON - (JavaScript Object Notation) est un format de fichier standard ouvert et un format d’échange de données qui utilise un texte lisible par l’homme pour stocker et transmettre des objets de données composés de paires attribut-valeur et de tableaux. Pour travailler avec l’API dans les bots, vous devez connaître ce format, tout est basé dessus.

Avant de continuer, lisez les articles suivants :

https://www.json.org/json-en.html https://developer.mozilla.org/en-US/docs/learn/javascript/objects/json

Et essayez également de créer votre propre fichier JSON sur ce site :

https://jsoneditoronline.org

Pratique

Les blocs et les conditions peuvent répondre à des requêtes. Les requêtes de condition sont créées pour comprendre sur le site si le dialogue peut suivre un certain chemin ou non. La requête dans ce cas se produit à chaque fois que la condition du chemin est vérifiée. Les requêtes des blocs, au contraire, ne s’exécutent que lorsque l’entrée dans le bloc a lieu.

Avant de créer une requête, vous devez choisir son type :

POST-data et POST-json se distinguent par la méthode de transfert des paramètres, comme mentionné ci-dessus (format JSON ou clé-valeur). Si vous choisissez JSON, alors les paramètres peuvent être transmis uniquement dans la requête. Un champ supplémentaire s’ouvre pour le post : paramètres POST JSON. Important ! Les paramètres doivent être écrits uniquement au format JSON, le bot ne fonctionne que de cette manière.

La réponse du serveur peut être analysée et enregistrée dans les variables.

Vous pouvez analyser la réponse seulement si elle est au format JSON.

Les variables enregistrées sont inscrites dans la dernière soumission non remplie ; si la soumission est transmise via un bloc rouge, les variables sont annulées. Donc, si vous devez enregistrer les données, vous devez transmettre les variables via le bloc jaune.

Au fait, vous pouvez voir ce que le bot a inscrit dans les variables dans la section Leads :

Transfert de données non sous forme de ligne

Par défaut, la valeur de la variable arrive au format #{} mais ensuite elle arrive sous forme de ligne. Pour que la variable soit transmise sous forme de nombre, vous devez désactiver la vérification du format des paramètres post-json.

Ensuite, vous pouvez simplement mentionner le nom de la variable, comme {"key": #{variable_name}}, variable_name est la variable, donc sans utiliser de crochets.

Après avoir configuré les paramètres, il est recommandé de réactiver la vérification.