Вы можете создавать ботов, которые взаимодействуют с другими сервисами через API. Например, боты могут отправлять запросы для проверки доступности на определенную дату или поиска товара в интернет-магазине.

Как взаимодействовать со сторонними API на примере Dadata

Возьмем в качестве примера API подсказок адресов: https://dadata.ru/api/suggest/address/ ссылка будет другая

Внимательно читайте документацию сторонних API.

Обратите внимание! Сторонние API требуют указания IP-адресов, с которых будут отправляться запросы: 158.160.49.208 – сайт.

В поле «URL запроса» введите https://suggestions.dadata.ru/suggestions/api/4_1/rs/suggest/address.

В поле «Заголовок запроса» введите заголовок в формате JSON: {"Content-Type": "application/json", "Accept": "application/json", "Authorization": "Token " + token}.

В поле «JSON-параметры» введите сам запрос: {"query": "#{CurrencyType}"}.

Чтобы получить результат запроса, заполните поле «Сохраненные значения».

Пример запроса показан на иллюстрации ниже.

Как сохранять значения из переменных

С первого раза может быть не совсем понятно — нужно попробовать самому.

Сначала введите #{custom_answer} в поле «Ответ». (Переменная #{custom_answer} содержит ответ, полученный от сервера, указанного в поле «URL ответа».)

Запустите блок запроса, чтобы отправить запрос и получить ответ. Полученный ответ нужно проанализировать и настроить, какие переменные из него извлекать. Для этого используйте поле «Сохраненные значения».

Разберем описанный выше пример.

Лучший способ понять, как обращаться к данным в JSON, — это пример. В результате нашего запроса ответ, полученный в #{custom_answer}, выглядит так:

{ "suggestions": [ { "value": "US Dollar", "unrestricted_value": "US Dollar", "data": { "code": "840", "strcode": "USD", "name": "US Dollar", "country": "United States" } } ] }

В поле «Сохраненные значения» введите ЗНАЧЕНИЕ -> ПЕРЕМЕННАЯ:

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

suggestions - ключ для массива [{"value": "US Dollar", "unrestricted_value": "US Dollar", "data": {"code": "840", "strcode": "USD", "name": "US Dollar", "country": "United States"}}]

suggestions|0 - ключ для первого элемента массива {"value": "US Dollar", "unrestricted_value": "US Dollar", "data": {"code": "840", "strcode": "USD", "name": "US Dollar", "country": "United States"}}

suggestions|0|value - ключ для значения "US Dollar"

Самый длинный ключ в этом JSON:

suggestions|0|data|strcode - ключ для значения "USD"

Ключи разделяются вертикальной чертой (|). Если элемент JSON является массивом, вы обращаетесь к его элементам по индексу, начиная с 0, и это также записывается через вертикальную черту.

Нужно повторить всю вложенность. Для удобства можно визуализировать JSON с помощью приложения для просмотра JSON.

Уровень вложенности разделяется вертикальной чертой. То есть нужно перечислить все ключи, чтобы добраться до значения, разделяя их вертикальной чертой.

Если JSON содержит массив, используйте индекс элемента вместо ключа, начиная с нуля.

Разделяйте выражения для получения наших переменных точкой с запятой ;.

Каждое выражение состоит из пути к данным в ответе и имени переменной для сохранения, разделенных ->.

Поисковый запрос представляет собой путь в JSON к нужному значению.

Разработка API для ботов

Бот поддерживает GET и POST запросы, которые являются основными типами, используемыми в большинстве публичных API.

GET — это запрос, который происходит при нажатии на ссылку или открытии URL в браузере. Параметры в этом запросе передаются в URL.

Синтаксис передачи параметров: после URL ставится вопросительный знак ?, затем каждый параметр отделяется амперсандом &. Каждый параметр состоит из имени, за которым следует = и его значение.

Пример URL с параметром:

Рис. 3

Здесь передается один параметр q со значением "good music". %20 обозначает пробел.

При работе с конструктором можно просто использовать пробел — бот заменит его автоматически.

POST — это запрос, который чаще всего отправляется при отправке формы на сайте. Параметры передаются в теле запроса. Хотя их также можно передавать в URL, как в GET-запросах, это встречается редко. Параметры в теле могут быть в формате JSON или в виде пар ключ-значение. Формы обычно отправляют пары ключ-значение, а API чаще всего используют JSON.

Заголовок запроса — вы можете добавить заголовок к каждому запросу. Чаще всего в нем указывается формат данных и ключи доступа. Обычно это поле оставляют пустым, но в редких случаях нужно указать токен API или тип запроса, например, "Content-Type": "application/json".

JSON (JavaScript Object Notation, обычно произносится /ˈdʒeɪsən/ JAY-sən) — это текстовый формат обмена данными, основанный на JavaScript. Как и многие другие текстовые форматы, JSON легко читается человеком. Для работы с API в боте необходимо понимать этот формат, так как он лежит в основе всех взаимодействий.

Прежде чем продолжить, прочитайте следующие статьи:

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

Также попробуйте создать свой собственный JSON-файл на этом сайте:

https://jsoneditoronline.org/

Практика

Запросы могут выполняться блоками и условиями. Условные запросы предназначены для проверки того, может ли диалог следовать по определенной ветке на сайте. В этом случае запрос отправляется каждый раз, когда оценивается условие ветки. Запросы в блоках, напротив, выполняются только тогда, когда диалог входит в это состояние.

Перед созданием запроса необходимо выбрать его тип:

POST-data и POST-JSON различаются способом передачи параметров, как упоминалось ранее (в формате JSON или в виде пар ключ-значение). Если вы выберете JSON, параметры могут передаваться только в теле запроса. Для JSON POST-параметров появится дополнительное поле.

Важно! Параметры должны быть записаны только в формате JSON, так как бот работает исключительно с ним. Вы уже попрактиковались в написании JSON.

Ответ от сервера можно разобрать и сохранить в переменные.

Разобрать ответ можно только в том случае, если он в формате JSON.

Сохраненные переменные записываются в последнюю незаполненную форму. Если форма отправляется через красный блок, переменные отбрасываются. Поэтому, если вам нужно сохранить эти данные, передайте переменные в CRM-систему через желтый блок.

Вы также можете увидеть, что бот записал в переменные, в разделе «Лиды».

Рис. 8

Передача переменных не в виде строки

По умолчанию значения переменных должны быть строками в формате "#{}", но в этом случае переменная передается как строка. Чтобы передать переменную как число, необходимо отключить проверку формата параметров в настройках проекта:

Затем можно просто использовать имя переменной, например: {"key": #{variable_name}}, где variable_name — это сама переменная, без окружающих кавычек.

Рекомендуется снова включить проверку формата после настройки параметров.