Вы можете создавать ботов, которые взаимодействуют с другими ресурсами через API. Например, боты могут обрабатывать запросы с возможностью проверки возможности создания записи на определенную дату или поиска товара в интернет-магазине.
Как работать со сторонним API на примере DaData
Возьмем в качестве примера API подсказок от https://dadata.ru/api/suggest/address
Внимательно читайте документацию сторонних API
Откройте свой проект в Mavibot и перейдите в расширенные настройки блока; там необходимо изменить тип запроса на POST-json.
В поле «URL запроса» введите следующий 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 для ответа от сервера»)
Запустите блок с запросом, чтобы отправить запрос и получить на него ответ. Вам нужно проанализировать ответ и настроить доступ к переменным в нем. Для этого необходимо работать с вкладкой «Сохраняемые значения».
Давайте рассмотрим пример, чтобы лучше понять процесс.
В результате нашего запроса #{custom_answer} пришел ответ следующего формата:
{"suggestions": [{"value": "Британский фунт", "unrestricted_value": "Британский фунт", "data": {"code": "826", "strcode": "GBP", "name": "Британский фунт", "country": "Великобритания"}}]}
Теперь запишем в поле «Сохраняемые значения» наши ЗНАЧЕНИЕ->ПЕРЕМЕННАЯ
suggestions|0|value->CurrencyType;
suggestions|0|data|code->CurrencyDigCode;
suggestions|0|data|strcode->CurrencyStrCode;
suggestions|0|data|country->CurrencyCountry
suggestions - ключ массива [{"value": "Британский фунт", "unrestricted_value": "Британский фунт", "data": {"code": "826", "strcode": "GBP", "name": "Британский фунт", "country": "Великобритания"}}]
suggestions|0 - ключ первого элемента в массиве {"value": "Британский фунт", "unrestricted_value": "Британский фунт", "data": {"code": "826", "strcode": "GBP", "name": "Британский фунт", "country": "Великобритания"}}
suggestions|0|value - ключ к значению «Британский фунт»
Самый длинный ключ в этом JSON:
suggestions|0|data|strcode - ключ к значению «GBP»
Ключи разделяются вертикальной чертой (|). Если в JSON есть массив, то доступ к его элементу нумеруется, начиная с числа 0, и также записывается через вертикальную черту.
Необходимо повторять всю вложенность. Для удобства можно визуализировать JSON в приложении JSON-viewer.
Уровни вложенности разделяются вертикальными чертами. Таким образом, нужно перечислить все ключи, разделенные чертой, чтобы добраться до значения.
Если в JSON есть массив, то вместо ключа нужно указать номер элемента, начиная с 0.
Разделяйте фразы получения переменных точкой с запятой (;). Фразы состоят из ссылки на данные в ответе и имени переменной для сохранения, которые разделяются символами -> (тире + угловая скобка).
Поисковый запрос, по сути, представляет собой путь в JSON к нужному значению.
Разработка API для ботов
Для разработки API вам понадобится хостинг, на котором он будет размещен. Если у вас его нет или вы не являетесь экспертом в программировании, вы можете обратиться к нам, и мы разработаем API для вашего бота и разместим его на нашем хостинге. Сам хостинг бесплатный, вы будете платить только за разработку.
А пока немного теории.
Бот поддерживает запросы GET и POST — это основные типы, которые используются в большинстве публичных API.
GET — это запрос, который происходит при клике по ссылке или при открытии ссылки в браузере. Параметры в таком запросе передаются в URL-запросе.
Синтаксис передаваемых параметров: после URL ставится вопросительный знак (?), затем каждый параметр отделяется амперсандом (&). Параметр состоит из имени и его значения после знака равенства (=). Пример URL с параметром:
Здесь видно, что передается один параметр с именем «search_query» и его значением «queen live aid». Знак «+» здесь обозначает пробел между словами; при работе с редактором можно просто оставлять пробелы — бот заменит их сам.
POST — это тип запроса, который чаще всего отправляется при заполнении формы на веб-сайте. Запрос передает параметры в теле; конечно, их можно передавать так же, как и в GET, но это делается редко. Параметр в теле может быть в формате JSON или в виде ключ-значение. В виде ключ-значение передаются параметры форм, формат JSON чаще всего используется для API.
Заголовок запроса. К каждому запросу можно добавить заголовок. В нем чаще всего указываются формат передаваемых данных и ключи доступа. Обычно мы оставляем эту вкладку пустой, но в редких случаях необходимо указать API-токен или тип запроса «Content-type»: «application/json».
JSON — (JavaScript Object Notation) — это открытый стандартный формат файлов и формат обмена данными, который использует читаемый человеком текст для хранения и передачи объектов данных, состоящих из пар атрибут-значение и массивов. Для работы с API в ботах необходимо знать этот формат, все на нем основано.
Прежде чем продолжить, прочитайте следующие статьи:
https://www.json.org/json-en.html
https://developer.mozilla.org/en-US/docs/learn/javascript/objects/json
А также попробуйте создать свой собственный JSON-файл на этом сайте:
Практика
Блоки и условия могут выполнять запросы. Условные запросы создаются для того, чтобы понять на сайте, может ли диалог следовать определенному пути или нет. В этом случае запрос выполняется каждый раз при проверке условия пути. Запросы блоков, наоборот, выполняются только при переходе в блок.
Перед созданием запроса необходимо выбрать его тип:
POST-data и POST-json различаются способом передачи параметров, как упоминалось выше (формат JSON или в виде ключ-значение). Если вы выберете JSON, то параметры могут передаваться только в запросе. Для POST открывается дополнительное поле: JSON-параметры POST. Важно! Параметры должны быть записаны только в формате JSON, бот работает только так.
Ответ от сервера можно разобрать и сохранить в переменные.
Разобрать ответ можно только в том случае, если он в формате JSON.
Сохраненные переменные записываются в последнюю незаполненную заявку; если заявка передается через красный блок, переменные аннулируются. Поэтому, если вам нужно сохранить данные, необходимо передавать переменные через желтый блок.
Кстати, вы можете увидеть, что бот записал в переменные, в разделе Лиды:
Передача данных не в виде строки
По умолчанию значение переменной передается в формате #{} , но затем оно передается как строка. Чтобы переменная передавалась как число, необходимо отключить проверку формата параметров post-json.
Затем вы можете просто указать имя переменной, например {"key": #{variable_name}}, где variable_name — это переменная, то есть без использования скобок.
После настройки параметров рекомендуется снова включить проверку.