Intégration avec des API tierces

Vous pouvez créer des bots qui interagissent avec d'autres ressources via une API. Par exemple, les bots peuvent répondre à des demandes 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 sur l'exemple de DaData

Prenons l'exemple des conseils API de https://dadata.ru/api/suggest/address

Lisez attentivement la documentation des API tierces

Ouvrez votre projet dans Salebot et ouvrez les paramètres avancés dans les paramètres d'un bloc ; vous devez y modifier 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 les « Paramètres JSON », insérez 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 requête est ci-dessous :

Comment enregistrer les valeurs des variables

Tout le monde ne comprend pas du premier coup, jusqu'à ce que vous essayiez de le faire vous-même.

Pour commencer, saisissez #{custom_answer} dans le champ de réponse. (La variable #{custom_answer} contient la réponse obtenue 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 ».

Examinons un exemple pour mieux comprendre le processus.

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

{"suggestions": [{"value": "British pound", "unrestricted_value": "British pound", "data": {"code": "826", "strcode": "GBP", "name": "British pound", "country": "The UK"}}]}

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

suggestions - la clé du tableau [{"value": "British pound", "unrestricted_value": "British pound", "data": {"code": "826", "strcode": "GBP", "name": "British pound", "country": "The UK"}}]

suggestions|0 - la clé du premier élément du tableau {"value": "British pound", "unrestricted_value": "British pound", "data": {"code": "826", "strcode": "GBP", "name": "British pound", "country": "The UK"}}

suggestions|0|value - la clé de la valeur « British pound »

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, l'accès à son élément est numéroté, en commençant par le nombre 0, et il est également écrit avec la barre verticale.

Il est nécessaire de répéter toute l'imbrication. Pour plus de commodité, 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, au lieu de la clé, vous devez mentionner 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 sont composées du lien vers les données dans la réponse et du nom de la variable pour l'enregistrer, qui sont 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 nécessaire.

Développement d'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 le nôtre. L'hébergement lui-même est gratuit, vous ne paierez que pour le développement.

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

Le bot prend en charge les requêtes GET et POST, 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 un lien ou lors de l'ouverture d'un lien dans le navigateur. Les paramètres d'une telle requête sont transférés dans les URL-requêtes.

La syntaxe des paramètres transférés : 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 est l'espace entre les mots ; lorsque vous travaillez avec le logiciel d'édition, vous pouvez simplement laisser les espaces – le bot les modifiera lui-même.

POST est un type de requête qui est le plus souvent envoyé lors du remplissage d'un formulaire sur un site web. La requête transfère 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 de cette façon. Le paramètre dans le corps peut être au format JSON ou sous forme de clé-valeur. En tant que clés-valeurs, les paramètres partagent des formulaires, le format JSON est celui qui est le plus souvent utilisé pour l'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. Habituellement, nous laissons cet onglet vide, mais il est nécessaire de 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 du 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 aux 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, en revanche, ne sont exécutées que lorsque le déplacement dans le bloc se produit.

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

POST-data et POST-json se différencient par la méthode de transfert des paramètres comme mentionné ci-dessus (format JSON ou sous forme de clé-valeur). Si vous choisissez JSON, les paramètres peuvent être transférés uniquement dans la requête. Un champ supplémentaire s'ouvre pour le post : Paramètres JSON POST. Important ! Les paramètres doivent être écrits uniquement au format JSON, le bot ne fonctionne que de cette façon.

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

Vous ne pouvez traiter la réponse que si elle est au format JSON.

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

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

Transfert de données non pas comme une ligne

Par défaut, la valeur de la variable vient au format #{} mais ensuite elle vient comme une ligne. Pour que la variable soit transférée comme un 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.