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

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

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

Внешний запрос — запрос из Платформа в какую-либо внешнюю систему.

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

Пользовательские контекстные переменные — Контекстная переменная, которые создаются пользователем.

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

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

  1. Зарегистрируйтесь в сервисе погоды по адресу https://home.openweathermap.org/users/sign_up. Этот сервис позволяет делать до 1000 обращений к API в день бесплатно.

  2. Нужные нам запросы находятся по адресу https://openweathermap.org/api/geocoding-api#direct — этот запрос позволяет найти координаты города, и https://openweathermap.org/api/one-call-3#current — этот запрос позволяет узнать погоду по координатам места.

  3. Зарегистрируйтесь на Платформа или войдите в уже существующий аккаунт по ссылке https://admin.chatme.ai/. Вы окажетесь на странице Папок вашей Компания. Подробнее о регистрации и авторизации: Регистрация и авторизация на Платформе.

  4. Создадим первый Внешний запрос. Для этого перейдите на Вкладка Ресурсов, нажав кнопку Resources на верхней панели.

  5. Зайдите в раздел с Внешний запрос. Подробнее о вкладке: Вкладка внешних запросов — External Requests.

  6. Создайте новый Внешний запрос, нажав кнопку Create new.

  7. Задайте ему имя “погода”, метод запроса оставьте GET, а в поле Endpoint (это URL-адрес, куда будет отправляться запрос) пропишите {{ url }} — так указываются Пользовательские контекстные переменные в этом поле. О том, что такое Контекстная переменная и какие они бывают: Контекстные переменные чата. О том, что такое Пользовательские контекстные переменные как корректно задать для них имя: Пользовательские контекстные переменные. Позже мы создадим эту Контекстная переменная в Сценарий агента нашего Агента.

  8. В Платформа существует Лимит на размер получаемого тела в ответ на Внешний запрос — если тело ответа превышает лимиты, то в переменную raw_response, которая содержит ответ внешней системы на Внешний запрос, записывается не ответ, а текст ошибки. Чтобы получить текст ответа, необходимо настроить его парсинг — записать его в Пользовательские контекстные переменные — на вкладке Response. Для этого перейдите на вкладку Response, предназначенную для парсинга ответа на запрос, и задайте в поле Variable значение result, а в поле Value — значение {{ body }}. Таким образом, все тело ответа будет сохранено в переменной result и будет доступно для использования в Сценарий агента Агента. Подробнее о парсинге на вкладке Response: Вкладка внешних запросов — External Requests

  9. Сохраните запрос, нажав кнопку CREATE.

  10. Создайте еще один Внешний запрос, нажав кнопку Create new. Задайте ему имя “погода 2”, метод запроса оставьте GET, а в поле Endpoint пропишите {{ url2 }}. Позже мы создадим эту Контекстная переменная в Сценарий агента нашего Агента.

  11. Перейдите на вкладку Response и задайте в поле Variable значение result2, а в поле Value — значение {{ body }}, чтобы сохранить все тело ответа в переменной result2 и использовать его в Сценарий агента Агента.

  12. Сохраните запрос, нажав кнопку CREATE.

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

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

  1. Перейдите на вкладку Папкаов, нажав кнопку Dashboard на верхней панели.

  2. Создайте нового Агента, как описано в статье Создание простого бота-опросника.

  3. Перейдите в БотБилдер Агента и создайте Слот Text с текстом “Привет! Я бот-метеоролог, я могу сообщить тебе погоду в любом городе. Хочешь попробовать?”.

  4. Далее добавьте кнопки “Да” и “Нет”.

  5. После кнопки “Нет” добавьте Слот Text с текстом “Ты можешь вернуться в любой момент.” и Слот Wait For Reaction.

  6. После Подслота fallback добавьте Слот Text с текстом “Пожалуйста, выбери одну из кнопок.” и Слот Jump с переходом обратно в кнопочное меню.

  7. После кнопки “Да” добавьте Слот Text с текстом “Тогда напиши название города.” и Слот Wait For Reaction.

  8. Затем добавьте Слот Memory — этот Слот позволяет записывать данные в Пользовательские контекстные переменные. Подробнее о Слоте Memory: Создание и сохранение переменных контекста | Слот Memory.

  9. Найдите ваш ключ API key, перейдя по ссылке https://home.openweathermap.org/api_keys, и скопируйте значение из поля Key.

  10. В данном Слоте 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. Сохраните Слот.

  11. После Слота Memory добавьте Слот External Request — с помощью него будет происходить интеграция с сервисом погоды. В нем пропишите в поле Name название “получение координат”. В поле Request выберите Внешний запрос под названием “погода”.

  12. Если Собеседник укажет несуществующее название города, мы получим пустой ответ от сервиса погоды, т.е. Контекстная переменная raw_response будет иметь значение []. Мы используем это в Сценарий агента, чтобы предложить Собеседнику ввести другое название. Для этого добавьте после Слота External Request Слот Transition Rule — он позволяет делать разветвления Сценарий Агента в зависимости от указанных условий. Подробнее: Разветвление сценария в зависимости от условий | Слот Transition Rule и под-слот Condition. Задайте Слоту имя “проверка города”.

  13. При создании Transition Rule будут автоматически созданы два Подслота condition, эти Подслоты содержат в себе условие, при значении true которого, Агент перейдет в Ветка сценария, идущую после этого Подслота condition.

  14. Нам необходимо проверить, содержит ли Контекстная переменная raw_response значение []. Для этого откройте Подслот со значением main и пропишите в нем в поле Condition условие {{ raw_response == '[]' }}. Поле Name очистите, тогда в Дерево сценария на Подслоте condition будет отображаться выражение из поля Condition.

  15. После данного Подслота добавьте Слот Text с текстом “Я не знаю такого города. Пожалуйста, введите другое название.” и Слот Jump с переходом в Слот Wait For Reaction, где Агент ожидает получить название города.

  16. Если город будет найден в сервисе погоды, то будет получен ответ формата:

  17. [ { "name":"название города", "local_names":{ названия города на доступных языках }, "lat": широта, "lon": долгота, "country":"код страны, где находится город", "state":"название страны, где находится город" }]

  18. После Подслота 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 — значениям широты и долготы. Подробнее о синтаксисе Платформа: Синтаксис.

  19. В этом же Слоте мы можем собрать и 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. Сохраните Слот.

  20. Далее создайте Слот External Request с названием “получение погоды”, выберите в нем Внешний запрос “погода 2”.

  21. В ответ на запрос мы должны получить ответ следующего формата (ответ имеет формат данных — Словари) :

{

"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": системный параметр

}

  1. Агент будет выводить Собеседнику данные о температуре. Для этого добавьте после Слота 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 }}. Подробнее о математических операциях в синтаксисе: Математические операции.

  2. После Слота Memory добавьте Слот Text с текстом “Температура в городе {{ client_message }} на данный момент {{ temperature }} ºC. Ощущается как {{ feels_like }}ºC. Хотите попробовать с другим городом?” и Слот Jump с переходом в кнопочное меню.

  3. На этом создание Сценарий агента Агента закончено. У вас должен получиться следующий Сценарий агента:

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

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

  1. Обучите Агента, нажав кнопку TRAIN, расположенную в правом верхнем углу БотБилдера. После этого начнется процесс Валидация сценария, по окончании которого, если Сценарий агента соответствует требованиям, то Агент будет обучен. В противном случае Валидация сценария завершится неудачно и в правом нижнем углу появится текст ошибки. Подробнее: Требования для успешного обучения Агента

  2. Если в Сценарий агента будут обнаружены ошибки, найдите проблемные места Сценарий агента с помощью информации в статье Требования для успешного обучения Агента и исправьте ошибки. После этого снова обучите Агента.

  3. После успешного Обучение Агента откройте Дебаг виджет, нажав кнопку Debug.

  4. В открывшемся Дебаг виджете напишите что-нибудь Агенту, чтобы начать Сценарий агента.

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

  6. Если вы обнаружите ошибки, исправьте их, не забывая переобучать Агента после каждого изменения, чтобы оно вступило в силу. Если же все корректно — поздравляем, ваш Агент готов!

Вывод Агента в Telegram

После того, как Сценарий агента Агента собран и протестирован, давайте выведем Агента в Telegram.

  1. Воспользуйтесь статьей Telegram для создания Бота в Telegram и подключения в него нашего тестового Агента.

  2. Перейдите в вашего только что созданного Бота в Telegram и протестируйте его работу в мессенджере.

Итак, наш Агент создан, протестирован и готов к общению в Telegram!

Last updated