Sie können Bots erstellen, die über APIs mit anderen Diensten interagieren. Beispielsweise können Bots Anfragen stellen, um die Verfügbarkeit für ein bestimmtes Datum zu prüfen oder ein Produkt in einem Online-Shop zu finden.
So interagieren Sie mit APIs von Drittanbietern am Beispiel von Dadata
Nehmen wir als Beispiel eine API für Adressvorschläge: https://dadata.ru/api/suggest/address/ der Link wird ein anderer sein
Lesen Sie die Dokumentation der APIs von Drittanbietern sorgfältig.
Bitte beachten Sie! APIs von Drittanbietern benötigen die IP-Adressen, von denen Anfragen gesendet werden: 158.160.49.208 – Website.
Geben Sie im Feld „Request URL“ Folgendes ein: https://suggestions.dadata.ru/suggestions/api/4_1/rs/suggest/address.
Geben Sie im Feld „Request header“ den Header im JSON-Format ein: {"Content-Type": "application/json", "Accept": "application/json", "Authorization": "Token " + token}.
Geben Sie im Feld „JSON parameters“ die Anfrage selbst ein: {"query": "#{CurrencyType}"}.
Um das Ergebnis der Anfrage zu erhalten, füllen Sie das Feld „Saved values“ aus.
Ein Beispiel für die Anfrage ist in der folgenden Abbildung dargestellt.
So speichern Sie Werte aus Variablen
Es mag beim ersten Mal nicht ganz klar sein – Sie müssen es wirklich selbst ausprobieren.
Geben Sie zunächst #{custom_answer} in das Feld „Antwort“ ein. (Die Variable #{custom_answer} enthält die Antwort, die vom im Feld „Response URL“ angegebenen Server empfangen wurde.)
Führen Sie den Anfrageblock aus, um die Anfrage zu senden und die Antwort zu erhalten. Die empfangene Antwort muss analysiert werden, und Sie müssen festlegen, welche Variablen daraus extrahiert werden sollen. Verwenden Sie dazu das Feld „Saved Values“.
Gehen wir das oben beschriebene Beispiel durch.
Der beste Weg, um zu verstehen, wie man auf Daten in JSON zugreift, ist ein Beispiel. Als Ergebnis unserer Anfrage sieht die in #{custom_answer} empfangene Antwort wie folgt aus:
{ "suggestions": [ { "value": "US Dollar", "unrestricted_value": "US Dollar", "data": { "code": "840", "strcode": "USD", "name": "US Dollar", "country": "United States" } } ] }
Geben Sie im Feld „Saved values“ WERT -> VARIABLE ein:
suggestions|0|value->CurrencyType;
suggestions|0|data|code->CurrencyDigCode;
suggestions|0|data|strcode->CurrencyStrCode;
suggestions|0|data|country->CurrencyCountry
suggestions - Schlüssel für das Array [{"value": "US Dollar", "unrestricted_value": "US Dollar", "data": {"code": "840", "strcode": "USD", "name": "US Dollar", "country": "United States"}}]
suggestions|0 - Schlüssel für das erste Element des Arrays {"value": "US Dollar", "unrestricted_value": "US Dollar", "data": {"code": "840", "strcode": "USD", "name": "US Dollar", "country": "United States"}}
suggestions|0|value - Schlüssel für den Wert „US Dollar“
Der längste Schlüssel in diesem JSON:
suggestions|0|data|strcode - Schlüssel für den Wert „USD“
Schlüssel werden durch einen senkrechten Strich (|) getrennt. Wenn ein JSON-Element ein Array ist, greifen Sie über den Index darauf zu, beginnend bei 0, und dies wird ebenfalls mit einem senkrechten Strich geschrieben.
Sie müssen die gesamte Verschachtelung wiederholen. Der Einfachheit halber können Sie das JSON mit einer JSON-Viewer-Anwendung visualisieren.
Die Verschachtelungsebene wird durch einen senkrechten Strich getrennt. Das heißt, Sie müssen alle Schlüssel auflisten, um zum Wert zu gelangen, und sie durch einen senkrechten Strich trennen.
Wenn das JSON ein Array enthält, verwenden Sie anstelle eines Schlüssels den Index des Elements, beginnend bei Null.
Trennen Sie die Ausdrücke zum Abrufen unserer Variablen durch ein Semikolon ;.
Jeder Ausdruck besteht aus dem Pfad zu den Daten in der Antwort und dem Namen der Variable, in die sie gespeichert werden soll, getrennt durch ->.
Die Suchanfrage stellt den Pfad im JSON zum erforderlichen Wert dar.
API-Entwicklung für Bots
Der Bot unterstützt GET- und POST-Anfragen, die wichtigsten Typen, die in den meisten öffentlichen APIs verwendet werden.
GET ist eine Anfrage, die erfolgt, wenn Sie auf einen Link klicken oder eine URL in einem Browser öffnen. Parameter werden in dieser Anfrage in der URL übergeben.
Syntax für die Übergabe von Parametern: Nach der URL ein Fragezeichen ? setzen, dann jeden Parameter durch ein kaufmännisches Und & trennen. Jeder Parameter besteht aus einem Namen, gefolgt von = und seinem Wert.
Beispiel einer URL mit einem Parameter:
Hier wird ein einzelner Parameter q mit dem Wert „good music“ übergeben. %20 steht für ein Leerzeichen.
Bei der Arbeit mit dem Builder können Sie einfach ein Leerzeichen verwenden – der Bot ersetzt es automatisch.
POST ist eine Anfrage, die am häufigsten beim Absenden eines Formulars auf einer Website gesendet wird. Die Parameter werden im Body der Anfrage gesendet. Obwohl sie auch wie bei GET-Anfragen in der URL gesendet werden können, ist dies unüblich. Parameter im Body können im JSON-Format oder als Schlüssel-Wert-Paare vorliegen. Formulare senden normalerweise Schlüssel-Wert-Paare, während APIs am häufigsten JSON verwenden.
Request header - Sie können jeder Anfrage einen Header hinzufügen. Meistens wird darin das Datenformat und die Zugriffsschlüssel angegeben. Normalerweise bleibt dieses Feld leer, aber in seltenen Fällen müssen Sie einen API-Token oder einen Anforderungstyp angeben, z. B. „Content-Type“: „application/json“.
JSON (JavaScript Object Notation, normalerweise /ˈdʒeɪsən/ JAY-sən ausgesprochen) ist ein textbasiertes Datenaustauschformat, das auf JavaScript basiert. Wie viele andere Textformate ist JSON für Menschen leicht lesbar. Um mit APIs im Bot zu arbeiten, müssen Sie dieses Format verstehen, da es allen Interaktionen zugrunde liegt.
Lesen Sie vor dem Fortfahren die folgenden Artikel:
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
Versuchen Sie auch, Ihre eigene JSON-Datei auf dieser Website zu erstellen:
Übung
Anfragen können durch Blöcke und Bedingungen ausgeführt werden. Bedingte Anfragen dienen dazu, zu prüfen, ob ein Dialog einem bestimmten Zweig auf der Website folgen kann. In diesem Fall wird die Anfrage jedes Mal gesendet, wenn die Zweigbedingung ausgewertet wird. Anfragen in Blöcken hingegen werden nur ausgeführt, wenn der Dialog in diesen Zustand eintritt.
Bevor Sie eine Anfrage erstellen, müssen Sie deren Typ auswählen:
POST-Daten und POST-JSON unterscheiden sich in der Art und Weise, wie Parameter gesendet werden, wie bereits erwähnt (entweder im JSON-Format oder als Schlüssel-Wert-Paare). Wenn Sie JSON wählen, können Parameter nur im Body der Anfrage gesendet werden. Für JSON-POST-Parameter wird ein zusätzliches Feld angezeigt.
Wichtig! Parameter müssen nur im JSON-Format geschrieben werden, da der Bot ausschließlich damit arbeitet. Sie haben bereits das Schreiben von JSON geübt.
Die Antwort vom Server kann analysiert und in Variablen gespeichert werden.
Sie können eine Antwort nur analysieren, wenn sie im JSON-Format vorliegt.
Gespeicherte Variablen werden im letzten unausgefüllten Formular aufgezeichnet. Wenn das Formular über einen roten Block übermittelt wird, werden die Variablen verworfen. Wenn Sie diese Daten speichern müssen, übergeben Sie die Variablen daher über einen gelben Block an das CRM-System.
Sie können auch sehen, was der Bot in den Variablen aufgezeichnet hat, im Bereich „Leads“.
Variablen nicht als Zeichenfolge übergeben
Standardmäßig müssen Variablenwerte Zeichenfolgen im Format „#{}" sein, aber in diesem Fall wird die Variable als Zeichenfolge gesendet. Um eine Variable als Zahl zu übergeben, müssen Sie die Formatprüfung in den Projekteinstellungen deaktivieren:
Dann können Sie einfach den Variablennamen verwenden, zum Beispiel: {"key": #{variable_name}}, wobei variable_name die Variable selbst ist – ohne umgebende Anführungszeichen.
Es wird empfohlen, die Formatprüfung nach dem Festlegen der Parameter wieder zu aktivieren.