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

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

Как обращаться к сторонними API на примере Dadata

Для примера возьмем API подсказки по адресам https://dadata.ru/api/suggest/address/

В поле "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 до требуемого значения.

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

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

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

Синтаксис передачи параметров: после url ставится знак вопроса(?), дальше каждый параметр разделен знаком амперсанда(&). Параметр состоит из имени и после знака равно его значения. Пример URL с параметром:

Здесь передается один параметр 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.

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

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

Кстати, увидеть что бот записал в переменные можно в разделе Лиды:

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

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

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