Vous pouvez créer des bots qui interagissent avec d'autres services via des API. Par exemple, les bots peuvent envoyer des requêtes pour vérifier la disponibilité à une date spécifique ou trouver un produit dans une boutique en ligne.
Comment interagir avec des API tierces en prenant l'exemple de Dadata
Prenons comme exemple une API de suggestion d'adresse : https://dadata.ru/api/suggest/address/ le lien sera différent
Lisez attentivement la documentation des API tierces.
Veuillez noter ! Les API tierces nécessitent les adresses IP à partir desquelles les requêtes seront envoyées : 158.160.49.208 – site web.
Dans le champ "URL de la requête", saisissez 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", saisissez la requête elle-même : {"query": "#{CurrencyType}"}.
Pour obtenir le résultat de la requête, remplissez le champ "Valeurs enregistrées".
Un exemple de la requête est illustré ci-dessous.
Comment enregistrer des valeurs à partir de variables
Cela peut ne pas être complètement clair la première fois — il faut vraiment essayer par soi-même.
Tout d'abord, saisissez #{custom_answer} dans le champ "Réponse". (La variable #{custom_answer} contient la réponse reçue du serveur spécifié dans le champ "URL de réponse".)
Exécutez le bloc de requête pour envoyer la requête et obtenir la réponse. La réponse reçue doit être analysée, et vous devez configurer les variables à en extraire. Pour cela, utilisez le champ "Valeurs enregistrées".
Parcourons l'exemple décrit ci-dessus.
La meilleure façon de comprendre comment adresser des données en JSON est par l'exemple. À la suite de notre requête, la réponse reçue dans #{custom_answer} ressemble à ceci :
{ "suggestions": [ { "value": "US Dollar", "unrestricted_value": "US Dollar", "data": { "code": "840", "strcode": "USD", "name": "US Dollar", "country": "United States" } } ] }
Dans le champ "Valeurs enregistrées", saisissez VALEUR -> VARIABLE :
suggestions|0|value->CurrencyType;
suggestions|0|data|code->CurrencyDigCode;
suggestions|0|data|strcode->CurrencyStrCode;
suggestions|0|data|country->CurrencyCountry
suggestions - clé pour le tableau [{"value": "US Dollar", "unrestricted_value": "US Dollar", "data": {"code": "840", "strcode": "USD", "name": "US Dollar", "country": "United States"}}]
suggestions|0 - clé pour le premier élément du tableau {"value": "US Dollar", "unrestricted_value": "US Dollar", "data": {"code": "840", "strcode": "USD", "name": "US Dollar", "country": "United States"}}
suggestions|0|value - clé pour la valeur "US Dollar"
La clé la plus longue dans ce JSON :
suggestions|0|data|strcode - clé pour la valeur "USD"
Les clés sont séparées par une barre verticale (|). Si un élément JSON est un tableau, vous accédez à ses éléments par index, en commençant par 0, et cela s'écrit également avec une barre verticale.
Vous devez répéter toute l'imbrication. Pour plus de commodité, vous pouvez visualiser le JSON à l'aide d'une application de visualisation JSON.
Le niveau d'imbrication est séparé par une barre verticale. C'est-à-dire que vous devez lister toutes les clés pour atteindre la valeur, en les séparant par une barre verticale.
Si le JSON contient un tableau, utilisez l'index de l'élément au lieu d'une clé, en commençant par zéro.
Séparez les expressions pour obtenir nos variables par un point-virgule ;.
Chaque expression se compose du chemin vers les données dans la réponse et du nom de la variable pour l'enregistrer, séparés par ->.
La requête de recherche représente le chemin dans le JSON vers la valeur requise.
Développement d'API pour les bots
Le bot prend en charge les requêtes GET et POST, qui sont les principaux types utilisés dans la plupart des API publiques.
GET est une requête qui se produit lorsque vous cliquez sur un lien ou ouvrez une URL dans un navigateur. Les paramètres de cette requête sont passés dans l'URL.
Syntaxe pour passer des paramètres : après l'URL, placez un point d'interrogation ?, puis séparez chaque paramètre par une esperluette &. Chaque paramètre se compose d'un nom suivi de = et de sa valeur.
Exemple d'URL avec un paramètre :
Ici, un seul paramètre q est passé avec la valeur "good music". %20 représente un espace.
Lorsque vous travaillez avec le constructeur, vous pouvez simplement utiliser un espace — le bot le remplacera automatiquement.
POST est une requête le plus souvent envoyée lors de la soumission d'un formulaire sur un site web. Les paramètres sont envoyés dans le corps de la requête. Bien qu'ils puissent également être envoyés dans l'URL comme dans les requêtes GET, cela est rare. Les paramètres dans le corps peuvent être au format JSON ou sous forme de paires clé-valeur. Les formulaires envoient généralement des paires clé-valeur, tandis que les API utilisent le plus souvent JSON.
En-tête de la requête - vous pouvez ajouter un en-tête à chaque requête. Le plus souvent, il spécifie le format des données et les clés d'accès. Habituellement, ce champ est laissé vide, mais dans de rares cas, vous devez inclure un jeton API ou un type de requête, par exemple, "Content-Type": "application/json".
JSON (JavaScript Object Notation, généralement prononcé /ˈdʒeɪsən/ JAY-sən) est un format d'échange de données textuel basé sur JavaScript. Comme beaucoup d'autres formats textuels, JSON est facile à lire pour les humains. Pour travailler avec des API dans le bot, vous devez comprendre ce format, car il sous-tend toutes les interactions.
Avant de continuer, lisez les articles suivants :
https://www.json.org/json-ru.html
https://developer.mozilla.org/ru/docs/Learn/JavaScript/%D0%9E%D0%B1%D1%8A%D0%B5%D0%BA%D1%82%D1%8B/JSON
Essayez également de créer votre propre fichier JSON sur ce site web :
Pratique
Les requêtes peuvent être exécutées par blocs et conditions. Les requêtes conditionnelles sont conçues pour vérifier si un dialogue peut suivre une certaine branche sur le site. Dans ce cas, la requête est envoyée chaque fois que la condition de la branche est évaluée. Les requêtes dans les blocs, en revanche, ne sont exécutées que lorsque le dialogue entre dans cet état.
Avant de créer une requête, vous devez choisir son type :
POST-data et POST-JSON diffèrent par la manière dont les paramètres sont envoyés, comme mentionné précédemment (soit au format JSON, soit sous forme de paires clé-valeur). Si vous choisissez JSON, les paramètres ne peuvent être envoyés que dans le corps de la requête. Un champ supplémentaire apparaîtra pour les paramètres JSON POST.
Important ! Les paramètres doivent être écrits uniquement au format JSON, car le bot ne travaille qu'avec celui-ci. Vous avez déjà pratiqué l'écriture de JSON.
La réponse du serveur peut être analysée et enregistrée dans des variables.
Vous ne pouvez analyser une réponse que si elle est au format JSON.
Les variables enregistrées sont consignées dans le dernier formulaire non rempli. Si le formulaire est soumis via un bloc rouge, les variables sont ignorées. Par conséquent, si vous devez enregistrer ces données, passez les variables au système CRM via un bloc jaune.
Vous pouvez également voir ce que le bot a enregistré dans les variables dans la section "Leads".
Passage de variables non sous forme de chaîne
Par défaut, les valeurs des variables doivent être des chaînes au format "#{}", mais dans ce cas, la variable est envoyée sous forme de chaîne. Pour passer une variable sous forme de nombre, vous devez désactiver la vérification du format des paramètres dans les paramètres du projet :
Ensuite, vous pouvez simplement utiliser le nom de la variable, par exemple : {"key": #{variable_name}}, où variable_name est la variable elle-même — sans guillemets environnants.
Il est recommandé de réactiver la vérification du format après avoir défini les paramètres.