Интеграция со сторонними API

В данной статье описан пример создания бота, работающего с внутренним API Wifire. (получает и отправляет информацию)
Вы можете создавать ботов, которые взаимодействуют с другими ресурсами по API. Например, боты могут выполнять запросы с проверкой возможности записаться на определенную дату или найти товар в интернет магазине. 
Как обращаться к сторонними API на примере Dadata
Для примера возьмем API подсказки по адресам https://dadata.ru/api/suggest/address/​
Внимательно читайте документацию в сторонних API
В поле "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 для ответа с сервера')
Запустите блок с запросом, чтобы отправить запрос и получить ответ на него. Полученный ответ надо проанализировать и настроить получение переменных из него. Для этого в поле "Сохраняемые значения" 
Разберем пример, описанный выше:
Лучше всего можно понять принцип адресации при работе с JSON на примере. В результате нашего запроса в #{custom_answer} пришел ответ формата:
{"suggestions": [{"value": "Белорусский рубль", "unrestricted_value": "Белорусский рубль", "data": {"code": "933", "strcode": "BYN", "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": "933", "strcode": "BYN", "name": "Белорусский рубль", "country": "Беларусь"}}]
suggestions|0 - ключ для первого элемента массива {"value": "Белорусский рубль", "unrestricted_value": "Белорусский рубль", "data": {"code": "933", "strcode": "BYN", "name": "Белорусский рубль", "country": "Беларусь"}}
suggestions|0|value - ключ для значения "Белорусский рубль"
Самый длинный ключ в этом JSON:
suggestions|0|data|strcode - ключ для значения BYN
Ключи разделяются вертикальной чертой. Если в JSON есть массив, то доступ к его элементу идет по номеру, начиная с 0 и также записывается через вертикальную черту.
Необходимо повторить всю вложенность. Для удобства можно визуализировать JSON через приложение JSON-viewer.
Уровень вложенности разделяется вертикальной чертой. То есть вам нужно перечислить все ключи, для того чтобы дойти до значения разделив их вертикальной чертой.
Если в json присутствует массив, вместо ключа нужно указать номер элемента массива, начиная с нуля.
Разделяем выражения получения наших переменных символом " ; "(точка с запятой). Выражения состоят из ссылки к данным в ответе на запрос и названия переменной для сохранения разделенных символами -> (минус больше).
Поисковой запрос представляет собой путь в JSON до требуемого значения. 
Разработка API для ботов
Для того, чтобы разработать API, нужен хостинг, на котором оно будет размещено. Если у вас его нет или вы не умеете программировать, можете обратиться к нам, и мы разработаем API для вашего бота и разместим все у себя. Хостинг API бесплатный, вы платите только за разработку.
А пока немного теории.
Бот поддерживает запросы GET и POST, это основные типы запроса, которые используются в большинстве публичных API. 
GET - это тот запрос, который происходит по клику по ссылке или при открытии ссылки в браузере. Параметры в данном запросе передаются в URL-запроса.
Синтаксис передачи параметров: после url ставится знак вопроса(?), дальше каждый параметр разделен знаком амперсанда(&). Параметр состоит из имени и после знака равно его значения. Пример URL с параметром:
Рисунок 3
Здесь передается один параметр q со значением “хорошая музыка”. %20 - пробел. При работа с конструктором, вы можете писать просто пробел, бот сам заменит его.
POST - это запрос, который чаще всего отправляется при заполнении формы на сайте. Параметры запрос передает в body, конечно они могут быть переданы также как и в GET, но так делают редко. Параметры в body могут идти в формате JSON, либо в виде ключ-значение. В виде ключ-значение параметры передают формы, для api чаще всего используется формат JSON.
Заголовок запроса. К каждому запросу можно добавить заголовок. Чаще в него пишется формат передаваемых данных и ключи доступа. Обычно это поле оставляем пустым, в редких случаях требуется вставить API Token или типа запроса "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": #{имя_переменной}}, имя_переменной — переменная. То есть без обрамляющих кавычек.
После установки параметров, рекомендуется обратно включить проверку.
API конструктора
Интеграции
Last modified 10mo ago