Создание бота с интеграцией с сервисом погоды

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

Термины, используемые в статье

Внешний запрос — запрос из Платформа в какую-либо внешнюю систему.Контекстная переменная — переменные, хранящиеся в Чате и доступные для чтения и изменения системой по заложенной в Сценарий агента или Платформа логике.Пользовательские контекстные переменные — Контекстная переменная, которые создаются пользователем.

Создание Внешних запросов

Первым делом необходимо создать Внешний запрос — это функционал, позволяющий Агенту обращаться во внешние системы по API. С помощью них мы будем отправлять данные в сервис погоды и получать необходимую в Сценарий агента информацию.

Зарегистрируйтесь в сервисе погоды по адресу https://home.openweathermap.org/users/sign_up. Этот сервис позволяет делать до 1000 обращений к API в день бесплатно.
Нужные нам запросы находятся по адресу https://openweathermap.org/api/geocoding-api#direct — этот запрос позволяет найти координаты города, и https://openweathermap.org/api/one-call-3#current — этот запрос позволяет узнать погоду по координатам места.
Зарегистрируйтесь на Платформа или войдите в уже существующий аккаунт по ссылке https://admin.chatme.ai/. Вы окажетесь на странице Папок вашей Компания. Подробнее о регистрации и авторизации: Регистрация и авторизация на Платформе.
Создадим первый Внешний запрос. Для этого перейдите на Вкладка Ресурсов, нажав кнопку Resources на верхней панели.
Зайдите в раздел с Внешний запрос. Подробнее о вкладке: Вкладка внешних запросов — External Requests.
Создайте новый Внешний запрос, нажав кнопку Create new.
Задайте ему имя “погода”, метод запроса оставьте GET, а в поле Endpoint (это URL-адрес, куда будет отправляться запрос) пропишите {{ url }} — так указываются Пользовательские контекстные переменные в этом поле. О том, что такое Контекстная переменная и какие они бывают: Контекстные переменные чата. О том, что такое Пользовательские контекстные переменные как корректно задать для них имя: Пользовательские контекстные переменные. Позже мы создадим эту Контекстная переменная в Сценарий агента нашего Агента.
В Платформа существует Лимит на размер получаемого тела в ответ на Внешний запрос — если тело ответа превышает лимиты, то в переменную raw_response, которая содержит ответ внешней системы на Внешний запрос, записывается не ответ, а текст ошибки. Чтобы получить текст ответа, необходимо настроить его парсинг — записать его в Пользовательские контекстные переменные — на вкладке Response. Для этого перейдите на вкладку Response, предназначенную для парсинга ответа на запрос, и задайте в поле Variable значение result, а в поле Value — значение {{ body }}. Таким образом, все тело ответа будет сохранено в переменной result и будет доступно для использования в Сценарий агента Агента. Подробнее о парсинге на вкладке Response: Вкладка внешних запросов — External Requests
Сохраните запрос, нажав кнопку CREATE.
Создайте еще один Внешний запрос, нажав кнопку Create new. Задайте ему имя “погода 2”, метод запроса оставьте GET, а в поле Endpoint пропишите {{ url2 }}. Позже мы создадим эту Контекстная переменная в Сценарий агента нашего Агента.
Перейдите на вкладку Response и задайте в поле Variable значение result2, а в поле Value — значение {{ body }}, чтобы сохранить все тело ответа в переменной result2 и использовать его в Сценарий агента Агента.
Сохраните запрос, нажав кнопку CREATE.

Создание Сценария Агента

Внешний запрос готовы, теперь необходимо создать Агента и его Сценарий агента.

Создайте нового Агента, как описано в статье Создание простого бота-опросника.
Перейдите в БотБилдер Агента и создайте Слот Text с текстом “Привет! Я бот-метеоролог, я могу сообщить тебе погоду в любом городе. Хочешь попробовать?”.
Далее добавьте кнопки “Да” и “Нет”.
После кнопки “Нет” добавьте Слот Text с текстом “Ты можешь вернуться в любой момент.” и Слот Wait For Reaction.
После Подслота fallback добавьте Слот Text с текстом “Пожалуйста, выбери одну из кнопок.” и Слот Jump с переходом обратно в кнопочное меню.
После кнопки “Да” добавьте Слот Text с текстом “Тогда напиши название города.” и Слот Wait For Reaction.
Затем добавьте Слот Memory — этот Слот позволяет записывать данные в Пользовательские контекстные переменные. Подробнее о Слоте Memory: Создание и сохранение переменных контекста | Слот Memory.
Найдите ваш ключ API key, перейдя по ссылке https://home.openweathermap.org/api_keys, и скопируйте значение из поля Key.
В данном Слоте Memory будет составляться Endpoint для первого из наших Внешний запрос. Формат URL-адреса для первого запроса следующий: http://api.openweathermap.org/geo/1.0/direct?q={название города}&appid={API key}. Нам необходимо составить URL-адрес, подставив туда название города, введенного Собеседником и наш личный ключ API key.
1. Задайте Слоту имя “составление url для запроса”.
2. Пропишите в поле Key значение url, в поле Value — значение 'http://api.openweathermap.org/geo/1.0/direct?q={{ client_message }}&appid=API key', где API key — это значение ключа из предыдущего шага, а {{ client_message }} — это Контекстная переменная client_message, которая содержит сообщение Собеседника. Контекстная переменная для подстановки в Слоте Memory указываются именно в таком формате — обрамленные двумя фигурными кавычками. Все значение поля необходимо заключить в кавычки, чтобы оно записалось в переменную в качестве строки. Таким образом будет составлен URL-адрес для первого запроса и сохранен в Контекстная переменная url, которую мы ранее уже указали в Внешний запрос в качестве Endpoint.
3. Сохраните Слот.
После Слота Memory добавьте Слот External Request — с помощью него будет происходить интеграция с сервисом погоды. В нем пропишите в поле Name название “получение координат”. В поле Request выберите Внешний запрос под названием “погода”.
Если Собеседник укажет несуществующее название города, мы получим пустой ответ от сервиса погоды, т.е. Контекстная переменная raw_response будет иметь значение []. Мы используем это в Сценарий агента, чтобы предложить Собеседнику ввести другое название. Для этого добавьте после Слота External Request Слот Transition Rule — он позволяет делать разветвления Сценарий Агента в зависимости от указанных условий. Подробнее: Разветвление сценария в зависимости от условий | Слот Transition Rule и под-слот Condition. Задайте Слоту имя “проверка города”.
При создании Transition Rule будут автоматически созданы два Подслота condition, эти Подслоты содержат в себе условие, при значении true которого, Агент перейдет в Ветка сценария, идущую после этого Подслота condition.
Нам необходимо проверить, содержит ли Контекстная переменная raw_response значение []. Для этого откройте Подслот со значением main и пропишите в нем в поле Condition условие {{ raw_response == '[]' }}. Поле Name очистите, тогда в Дерево сценария на Подслоте condition будет отображаться выражение из поля Condition.
После данного Подслота добавьте Слот Text с текстом “Я не знаю такого города. Пожалуйста, введите другое название.” и Слот Jump с переходом в Слот Wait For Reaction, где Агент ожидает получить название города.
Если город будет найден в сервисе погоды, то будет получен ответ формата:
[ { "name":"название города", "local_names":{ названия города на доступных языках }, "lat": широта, "lon": долгота, "country":"код страны, где находится город", "state":"название страны, где находится город" }]
После Подслота condition с названием FALLBACK_CONDITION поставьте Слот Memory, где из полученного от сервиса ответа будут извлекаться координаты города, необходимые для получения информации о погоде в нем.
1. Задайте Слоту имя “сохранение координат”.
2. Пропишите в поле Key значение lat, а в поле Value — значение {{ result[0].lat }}.
3. Затем добавьте еще одну пару Key - Value, нажав кнопку Add new field.
4. Пропишите в поле Key значение lon, а в поле Value — значение {{ result[0].lon }}.
5. Так задаются обращения к первому элементу массива result (нумерация элементов массива начинается с нуля) и содержащимся в нем переменным lat и lon — значениям широты и долготы. Подробнее о синтаксисе Платформа: Синтаксис.
В этом же Слоте мы можем собрать и Endpoint для второго Внешний запрос. Формат URL-адреса для второго запроса следующий: https://api.openweathermap.org/data/2.5/weather?lat={lat}&lon={lon}&appid={API key}. Нам необходимо составить URL-адрес, подставив туда координаты города, введенного Собеседником и наш личный ключ API key.
1. Добавьте еще одну пару Key - Value. Пропишите в поле Key значение url2, в поле Value — значение 'https://api.openweathermap.org/data/2.5/weather?lat={{ lat }}&lon={{ lon }}&appid=API key', где API key — это значение ключа из шага 8, а {{ lat }} и {{ lon }} — переменные с координатами. Таким образом будет составлен URL-адрес для второго запроса и сохранен в Контекстная переменная url2, которую мы ранее уже указали в Внешний запрос в качестве Endpoint.
2. Сохраните Слот.
Далее создайте Слот External Request с названием “получение погоды”, выберите в нем Внешний запрос “погода 2”.
В ответ на запрос мы должны получить ответ следующего формата (ответ имеет формат данных — Словари) :

{

"coord": {

координаты города

"weather": [

{ "id": 501,

"main": "погода",

"description": "описание погоды",

"icon": "10d"

}

"base": "stations",

"main": {

"temp": фактическая температура в Кельвинах,

"feels_like": ощущаемая температура в Кельвинах,

"temp_min": минимальная температура в Кельвинах,

"temp_max": максимальная температура в Кельвинах,

"pressure": атмосферное давление,

"humidity": влажность воздуха,

"sea_level": атмосферное давление над уровнем моря,

"grnd_level": атмосферное давление над уровнем суши

"visibility": видимость в метрах,

"wind": {

данные о ветре

"rain": {

данные об осадках

"clouds": {

данные об облачности

"dt": 1661870592,

"sys": {

системные параметры

"timezone": часовой пояс,

"id": 3163858,

"name": "название города",

"cod": системный параметр

}

Агент будет выводить Собеседнику данные о температуре. Для этого добавьте после Слота External Request Слот Memory.
1. Дайте Слоту название “сохранение погоды”.
2. Для начала сохраним значение элемента "main", который содержит данные о температуре, в переменную. Ответ сервиса содержится в переменной result2, которая имеет формат словаря. Обращение к элементу словаря происходит через квадратные скобки с указанием названия элемента. Пропишите в поле Key значение “var1”, а в поле Value — значение {{ result2['main'] }}.
3. Далее сохраним значения фактической и ощущаемой температуры воздуха. Для этого добавьте еще две пары Key - Value. В полях Key пропишите значения var2 и var3, а в полях Value — {{ var1['temp'] }} и {{ var1['feels_like'] }} соответственно.
4. Поскольку сервис возвращает данные о температуре в градусах Кельвина, переведем их в градусы Цельсия. Температура в градусах Цельсия вычисляется по формуле {температура в градусах Кельвина}-273.15. Добавьте еще две пары Key - Value, в полях Key укажите значения “temperature” и “feels_like”, а в полях Value соответственно {{ var2 - 273.15 }} и {{ var3 - 273.15 }}. Подробнее о математических операциях в синтаксисе: Математические операции.
После Слота Memory добавьте Слот Text с текстом “Температура в городе {{ client_message }} на данный момент {{ temperature }} ºC. Ощущается как {{ feels_like }}ºC. Хотите попробовать с другим городом?” и Слот Jump с переходом в кнопочное меню.
На этом создание Сценарий агента Агента закончено. У вас должен получиться следующий Сценарий агента:

Обучение и тестирование Агента

После создания Сценарий агента Агента необходимо обучить Агента и протестировать его Сценарий агента.

Обучите Агента, нажав кнопку TRAIN, расположенную в правом верхнем углу БотБилдера. После этого начнется процесс Валидация сценария, по окончании которого, если Сценарий агента соответствует требованиям, то Агент будет обучен. В противном случае Валидация сценария завершится неудачно и в правом нижнем углу появится текст ошибки. Подробнее: Требования для успешного обучения Агента
Если в Сценарий агента будут обнаружены ошибки, найдите проблемные места Сценарий агента с помощью информации в статье Требования для успешного обучения Агента и исправьте ошибки. После этого снова обучите Агента.
После успешного Обучение Агента откройте Дебаг виджет, нажав кнопку Debug.
Пообщайтесь с Агентом, пройдя все шаги Сценарий агента, попутно проверяя, что в текстах нет ошибок и логика Сценарий агента верна.
Если вы обнаружите ошибки, исправьте их, не забывая переобучать Агента после каждого изменения, чтобы оно вступило в силу. Если же все корректно — поздравляем, ваш Агент готов!