Развитие Телеграмм во многом определяется наличием большого числа ботов – небольших сервисных программ-роботов. Их может создать каждый пользователь, знакомый с программированием на среднем уровне. Telegram API Bot – это программный интерфейс, позволяющий программировать собственного бота.
API включает в себя объекты и команды, предназначенные для установки поведения бота Telegram. Используя интерфейс, вы можете создавать собственные программные коды, которые при запуске в Telegram начинают работать как боты.
Элементы управления
В Бот Телеграмм API все элементы управления представляют собой объекты, которые представлены в JSON, то есть в виде строки, заданной по определенным правилам. Это позволяет производить обмен данными по сети максимально быстро и наименее затратно, так как передается не программный код, а набор пар «ключ:значение» в текстовом виде. В таблице приведены все типы API. Большая часть объектов предназначена для создания команд бота. Ключи дадут более расширенное представление о возможностях объекта.
Название | Описание | Ключи |
---|---|---|
User | Пользователь в Телеграмм | id first_name last_name username |
Chat | Чат | id type title username first_name last_name all_members_are_administrators |
Message | Сообщение | message_id from date chat forward_from forward_date reply_to_message text entities audio document photo sticker video voice caption contact location venue new_chat_member left_chat_member new_chat_title new_chat_photo delete_chat_photo group_chat_created supergroup_chat_created channel_chat_created migrate_to_chat_id migrate_from_chat_id pinned_message |
MessageEntity | Отдельная сущность в текстовом сообщении (хештег, ссылка и пр.) | type length url offset |
PhotoSize | Изображение заданного размера или превью фото, файла или стикера | file_id width height file_size |
Audio | Аудиозапись | file_id duration performer title mime_type file_size |
Document | Любой файл, не являющийся изображением, аудиозаписью или голосовой записью | file_id thumb file_name mime_type file_size |
Sticker | Стикер | file_id width height thumb file_size |
Video | Видеозапись | file_id width height duration thumb mime_type file_size |
Voice | Голосовое сообщение | file_id duration mime_type file_size |
Contact | Телефонный контакт | phone_number first_name last_name user_id |
Location | Точка на карте | longitude latitude |
Venue | Объект на карте | location title address foursquare_id |
UserProfilePhotos | Фото профиля пользователя | total_count photos |
File | Готовый к загрузке файл | file_id file_size file_path |
ReplyKeyboardMarkup | Клавиатура с возможностью ответа | keyboard resize_keyboard one_time_keyboard selective |
KeyboardButton | Кнопка клавиатуры для ответа | text request_contact request_location |
ReplyKeyboardHide | Заменяет клавиатуру бота на стандартную клавиатуру Telegram | hide_keyboard selective |
InlineKeyboardMarkup | Встроенная клавиатура, появляющаяся под сообщением | inline_keyboard |
InlineKeyboardButton | Одна кнопка на встроенной клавиатуре | text url callback_data switch_inline_query switch_inline_query_current_chat callback_game |
CallbackQuery | Входящий запрос обратной связи для встроенной кнопки с заданным параметром callback_data | id from message inline_message_id data |
ForceReply | Эмулирует действия пользователя: выбор сообщения и нажатия кнопки «Ответить» | force_reply selective |
ResponseParameters | Сообщает, почему запрос не выполнился успешно | migrate_to_chat_id retry_after |
Результирующие строки, которые присылает мессенджер, представлены в виде тех же объектов API.
Обмен сообщениями происходит в виде запросов. В следующей таблице приведены примеры некоторых из них.
Все методы (а их достаточно много) делятся на группы:
- Получение обновлений и информации.
- Работа в чате.
- Отправка различных элементов.
- Работа со стикерами.
- Обновление сообщений.
- Режим inline.
- Платежный функционал.
- Для игр.
Полной документации Telegram Bot API на русском пока не существует. Однако стандартный перевод в браузере Google Chrome прекрасно справляется с задачей.
Языки программирования
Telegram API поддерживается множеством языков программирования. Это дает возможность выбора создателю.
Любители JavaScript могут использовать Node.js Telegram Bot API. Здесь необходимо знание не только языка, но и умение обращаться с этим фреймворком, превратившим клиентский язык в полноценный серверный интерфейс.
Одним из самых популярных для написания ботов с использованием Telegram Bot API является PHP. Этот язык изначально был предназначен для создания серверных web-приложений. Он отличается простотой, логичностью и специализированностью именно для web-среды.
Часто используется Telegram Bot API в Python. Этот язык отличается минимализмом и достаточно прост в изучении. Он очень популярен за счет своей производительности.
Классикой является применение Telegram Bot API в С++. Язык нельзя назвать простым, но он является базой, на которой были созданы все остальные вышеперечисленные ЯП. Соответственно в нем не заложена определенная специализация. Инструменты позволяют создавать любые приложения.
Пример использования
Кроме объектов API имеет набор методов, которые позволяют отправлять сообщения, файл, фото стикеры, редактировать и многое другое. Все эти команды можно найти в описании API на официальном сайте.
Для создания в Telegram существует специальный сервис @Botfather. Зайдите в него и увидите набор команд, с помощью которых создается новый робот. Для начала наберите команду /newbot. Далее последовательно введите имя для пользователей и название. Последнее обязательно заканчивается на «bot». После того, как вам пришлют токен (идентификатор), новый бот создан. Авторизация осуществляется через токен. Чтобы запустить программу в Телеграмм, найдите свое детище и нажмите кнопку «Старт». Это запустит преопределённую команду /start. Также для каждого робота зарезервированы команды /settings и /help.
Все запросы имеют вид:
Https://api.telegram.org/bot
Всего существует 4 способа подачи запроса:
- Запрос в URL
- application/x-www-form-urlencoded
- application/json (не подходит для загрузки файлов)
- multipart/form-data (для загрузки файлов)
Доступны как GET, так и POST запросы.
Самый простой способ попробовать команды API – адресная строка в браузере. Зайдите в свой бот в web-версии или с мобильного устройства. Затем в браузере наберите команду:
https://api.telegram.org/bot507226896:AAGT_fsEfg1milOkqbNp-VolQDJ0tGjaPvD7/getUpdates
В результате в окне появится JSON-строка
{"ok":true,"result":[{"update_id":231886689,
"message":{"message_id":3,"from":{"id":391911270,"is_bot":false,"first_name":"Irina","last_name":"12345678","language_code":"ru"},"chat":{"id":391911270,"first_name":"Irina","last_name":"12345678","type":"private"},"date":1514900431,"text":"\u044b\u0443\u0442\u0430\u043b\u043e\u0430\u043c\u0440"}}]}
Параметр chat»:{«id – это идентификатор чата. Затем наберите строку:
https://api.telegram.org/ bot507226896:AAGT_fsEfg1milOkqbNp-VolQDJ0tGjaPvD7/sendMessage?chat_id=391911270&text=Hello
В браузере появится строка
{"ok":true,"result":{"message_id":4,"from":{"id":507226896,"is_bot":true,"first_name":"Anna","username":"Annatuola_bot"},"chat":{"id":391911270,"first_name":"Irina","last_name":"12345678","type":"private"},"date":1514900499,"text":"Hello"}}
А в чате Телеграмм вы увидите приветствие от созданного робота.
Как видите, создать с нуля новый элемент для Телеграмм не сложно. Трудности начинаются в момент программирования, но об этом расскажем в других статьях.
Приложение Телеграмм честно может похвастаться открытием новой, абсолютно уникальной базы для создания ботов. Хоть ботовая платформа была разработана еще в начале лета (презентация состоялась 24.06), лишь малая часть активных внешних разработчиков начала усиленно шлифовать и разрабатывать собственные приложения. Сегодня бот — незаменимый помощник для Telegram , ведь с его помощью устанавливается связь с запрашиваемыми серверами TelegramBot API . Кроме этого, сам процесс работы бота направлен на обращения на URL с заданными параметрами, после которого Телеграмм выдает JSON — ответ. Давайте же окунемся вглубь вопроса и рассмотрим пример создания бота (тривиального типа).
Процедура регистрации приложения (бота)
Перед тем, как начать непосредственную разработку и заливку бота в общий интерфейс и чат, необходимо присвоить вашей мини — программе индивидуальный код (типа id ), который является уникальным персонифицирующим токеном. Для того, чтобы осуществить данную операцию, необходимо отправить запрос в специфический бот — @BotFather .
Для того, чтобы осуществить данную операцию, необходимо следовать такому алгоритму действий:
- пишем текстовое сообщение с информационным наполнением «start »;
- после этого, получаем перечень всех возможных опционных команд и функций;
- далее отправляем боту сообщение с текстовым наполнением «newbot » и по входящему запросу существующего бота, придумываем никнейм своему боту (единственное условие: в имени должен быть суффикс/префикс «bot »);
- если все условия и правила учтены, то существующий бот выдает вам запрос и разрешительную ссылку (быстрое добавление созданного бота в список имеющихся контактов).
В принципе, к этому моменту уже можно запускать бот или же, при желании, возможно создать приветственное сообщение для будущих пользователей и описание бота. Возможно, если вы хотите поразить определенную целевую аудиторию, то может добавить созвучную музыкальную композицию или изображение. Важный совет: стоит проверить уникальность и пригодность вашего токена, перейдя по адресной ссылке (api.telegram.org/bot/getMe) . Процесс программирования ботов
Обычно боты создаются в режиме Python3 , но благодаря прогрессивности ИТ — технологий, можете воспользоваться любым удобным и привычным режимом. Телеграмм настроен на автоматическую загрузку сообщений, поэтому уместно создать конфиденциальное облако, которое значительно ускорить процесс выкачки текстовых сообщений (наиболее быстрым и применимым являетсяtornado.web. ). Пусть каркасная часть бота будет отражена в определённой фразе (логичнее использовать ту, которая отражает информационное наполнение запрограммированного бота). Тогда, перед тем, как запустить бот, необходимо провести процедуру активации WebHook с локализацией на собственный адрес. Далее настраиваем привычный сигнал (выход на 6) и отображаем нагружение происходящих событий/ действий.
- словарный запас;
- функциональная особенность отправки (пересылки) текстовых ответов;
- формирование сообщений.
После того, как вы занесли все нюансы в логику бота, необходимо начать разработку основных команд, которыми будет обладать ваша программа.
Создание команд
По правилам программы Телеграмм, абсолютно каждый бот (в не зависимости от специфики, популярности и загруженности) должен реагировать на 2 команды:
- Start ;
- Help .
Первая команда создана для идентификации бота, а не для просмотра заложенной информации. Зачастую, ее использование тесно связано с процедурой авторизации каких — либо программ.
Команда «Help » направлена на отражение основных параметров бота, его специфических характеристик, особенностей и команд.
Для создания команд несменным помощником является основной бот @BotFather , который поможет вам создать необходимый и требуемый по вашей классификации перечень команд.
Всеобщность
Вы уже заметили, что программа Телеграмм присылает абсолютно целостные и значимые в смысловом плане сообщения, не разбивая их на отдельные нелепые части. Поэтому, возникает возможность запрограммировать ваш бота на озвучки человеческой речи (голосовое уведомление). Единственный нюанс в том, что «говорливый» бот будет доступен только в приватных сообщениях, ибо в чате данная особенность невозможна. Для того, чтобы запустить процесс «говорения» бота совершаем ряд связных операций:
- отправляем текстовое сообщение «setprivacy» на адрес @BotFather;
- переключаемся на приватность;
- в перечне команд добавляем опцию «псевдо — речь».
После этого, бот может озвучивать сообщения и предавать информацию в голосовом режиме.
Медиа аспекты и возможности
Боты не многим отличаются от реальных пользователей месседжера Телеграмм, поэтому у них тоже есть возможность общаться с использованием картинок, музыкальных файлов, видеозаписей и стикеров.
Для того, чтобы заполучить пакет стикеров необходимо отправить текстовое сообщение «at_sticker » и провести модификацию к параметрам send_reply . Таким образом, помимо текста ваш бот будет высылать и забавные стикеры и отображать показатели времени.
Потенциал
С помощью надежной платформы API , боты могут стать незаменимыми помощниками и основой для автоматизации процессов, формировании викторин, опросов, конкурсов и отправки уведомительных сообщений. Основной упор можно сделать на специфику CTF, DozoR.
Рамки
Сегодня имеются жёсткие рамки в использование ВебХук . Дело в том, что он функционирует только на основе https (при наличии валидного сертификата). Далёко не каждый разработчик имеет валидный сертификат. А причина в том, что отсутствует поддержка от ДНС. Но, благодаря наличию ручного режима в Telegramm , есть возможность дифференцировать коды и службы имеющихся данных под те, к которым подстроена ваша программа, проводящие выкачку и пересылку сообщений на локальные адреса.
Другие материалы про ботов Telegram:
- Робот Антон — роботы в Telegram
- Возможности разработчиков api Telegram
- Боты Telegram
- Telegram 3.0 имеет функцию запуска полезных Ботов
В последнее время Telegram у всех на слуху. Нужно отдать должное отделу маркетинга этого приложения, шумиху подняли на славу. Одной из основных "фишек" Telegram является его якобы защищённость - по словам Павла Дурова вся переписка между пользователями шифруется. Более того, ни одна спец.служба мира не будет иметь доступ к вашим сообщениям. Но в данной статье речь не об этом. Сегодня хотелось бы поговорить о не менее крутой фишке в Telegram, а именно о ботах. Помимо того, что в сети уже полно информации о различного рода Telegram ботах (github бот, например), мессенджер открыл своё API для разработчиков, и теперь каждый может создать своего собственного бота с блэкджеком и плюшками.
В статье я приведу пример написания онлайн бота с использованием Python и Django фреймворка. То есть мы "запилим" полноценное веб-приложение, которое будет крутиться на удалённом хосте и принимать команды от пользователей. Весь исходный текст доступен в моём github репозитории .
Документация, описывающая процесс взаимодействия с ботами Telegram находится . Чтобы не изобретать велосипед, я нашел неплохую Python библиотеку, реализующую все основные функции ботов - telepot . Как я уже упоминал ранее, для того, чтобы обслуживать пользователей нашего бота мы будет разрабатывать веб-приложение, используя Django фреймворк.
Как создать Telegram бота?
Для начала нам необходимо зарегистрировать в Telegram нашего будущего бота. Это делается следующим образом:
- Необходимо установить приложение Telegram на телефон или компьютер. Скачать приложение можно
- Добавляем к себе в контакт-лист бота с именем BotFather
- Запускаем процедуру "общения" с ботом нажатием кнопки Start . Далее перед нами предстанет список команд точно как на скриншоте.
- Для того, чтобы создать нового бота необходимо выполнить команду /newbot и следовать инструкциям. Обратите внимание, что username для бота должен всегда содержать в конце слово bot . Например, DjangoBot или Django_bot.
- Для нашего бота я выбрал имя PythonPlanetBot, так как его основная функция заключается в парсинге RSS feed сайта Python Planet и выдача информации о последних постах пользователю:)
После создания бота, обратите внимание на строку с текстом:
Use this token to access the HTTP API:
За которой следует т.н. token по которому мы будем манипулировать нашим ботом. Помимо функции создания telegram бота, BotFather также имеет ряд других возможностей:
- Присвоить боту описание
- Установить аватар
- Поменять token
Приступаем к кодированию
Как я ранее уже упоминал, мы будем писать веб-приложение на Django . Но стоит отметить, что это делать необязательно. Можно обойтись и обычным Python скриптом, правда в этом случае необходимо будет периодически опрашивать Telegram на предмет новых запросов от пользователей бота (используя метод getUpdates ) и увеличивая offset для получения самых последних данных без повторений. В Telegram существует два взаимоисключающих метода получения команд/сообщений для вашего бота.
- Использование вызова API метода getUpdates
- Установка Webhook
Установка Webhook заключается в передаче боту специального URL адреса на который будет поступать POST запрос каждый раз, когда кто-то начнёт посылать сообщения боту. Именно этот вариант мы и будем использовать для взаимодействия между ботом и его пользователем. Для того, чтобы задать URL, необходимо использовать API метод setWebhook . Отмечу, что URL должен начинаться с https, то есть иметь защищённое SSL соединение с валидным сертификатом. Telegram разрешает использовать самоподписанный сертификат, правда для этого необходимо в методе setWebhook передавать также публичный ключ в PEM формате (ASCII base64). Либо же можно получить от Let"s Encrypt.
Подробнее о getUpdates и setWebhook можно почитать соответственно и .
Итак, вернёмся к python библиотеке для работы с Telegram - telepot . На текущий момент самой последней её версий является 6.7. Устанавливаем её в виртуальное окружение python virtualenv:
Pip install telepot
Самый простой вариант взаимодействия с Telegram ботом на Python выглядит следующим образом:
Import telepot token = "123456" TelegramBot = telepot.Bot(token) print TelegramBot.getMe()
Переменной token присваиваем значение токена, полученного при создании бота через BotFather. В итоге после выполнения этих команд мы получим:
{u"username": u"PythonPlanetBot", u"first_name": u"Python Planet Bot", u"id": 199266571}
Поздравляю! Мы вызывали самый простой API запрос getMe, который возвращает информацию о боте: username, id, first_name.
Добавим нашего бота к себе в контакт-лист и пошлём ему первую стандартную команду /start
Выполняем код:
TelegramBot.getUpdates() [{u"message": {u"date": 1459927254, u"text": u"/start", u"from": {u"username": u"adilkhash", u"first_name": u"Adil", u"id": 31337}, u"message_id": 1, u"chat": {u"username": u"adilkhash", u"first_name": u"Adil", u"type": u"private", u"id": 7350}}, u"update_id": 649179764}]
Процесс общения с telegram ботом происходит по HTTPS; для передачи данных используется JSON. Метод getUpdates возвращает список/массив из объектов типа Update . Внутри Update находится объект Message . Для стандартного взаимодействия с ботом нас фактически интересует именно объект Message, у которого мы считываем атрибут text, хранящий в себе текст, переданный боту и объект chat, в котором лежит информация о пользователе, инициировавшем общение с нашим Telegram ботом. Также имеется параметр update_id, который служит в качестве offset параметра при вызове метода getUpdates. То есть update_id+1 вернёт все сообщения, поступившие после последнего update_id, при этом все предыдущие сообщения будут удалены.
TelegramBot.getUpdates(649179764+1) [{u"message": {u"date": 1459928527, u"text": u"hello bro", u"from": {u"username": u"adilkhash", u"first_name": u"Adil", u"id": 31337}, u"message_id": 13, u"chat": {u"username": u"adilkhash", u"first_name": u"Adil", u"type": u"private", u"id": 7350}}, u"update_id": 649179765}]
На этапе написания простейшего Telegram бота нам этих вызовов достаточно. Приступим к написанию Django приложения для обслуживания наших пользователей.
Простая функция парсинга RSS фида Planet Python выглядит вот так.
- Tutorial
Чат боты - довольно интересная тема, которой интересуются как гики-энтузиасты, так и компании, которые хотят организовать взаимодействие со своими клиентами наиболее удобным для них способом
Сегодня я опишу вам простой пример создания бота Telegram с использованием платформы для создания разговорных интерфейсов API.AI, который будет приветствовать пользователя и отвечать на вопросы о погоде. По большей части я следовал этим инструкциям , в реальной практике, можно не ограничиваться погодой и реализовать интерфейсы
для автоматизированной поддержки или продаж.
Шаг первый: Подготовка инфраструктуры.
В этом кейсе мы будем использовать только Telegram бота и API.AI, оба сервиса предоставляются бесплатно - нам остается только завести учетные записи.
Создайте бота Telegram
Чтобы создать бота - просто напишите @BotFather (это такой бот, которые умеет создавать и настраивать другие боты):
- Отправьте команду /newbot - так мы сообщаем @BotFather, что нам нужен новый бот
- Теперь @BotFather попросит нас дать имя новому боту. Это имя будут видеть наши
будущие пользователи, поэтому название нужно давать понятное и простое. - Последним шагом укажем для бота username, в конце которого нужно обязательно
написать “bot”. - Если имя не занято, получаем сообщение с подтверждением и токен доступа.
Чтобы было понятнее - ниже скриншот со всеми действиям:
Немного теории
Пришло время создать агента API.AI, который в сущности является проектом или контейнером (как вам удобнее называть). Агент содержит настройки контекстов, сущностей и ответов:
- “контекст” (Intent)
отражает связь между тем, что сказал пользователь
и
тем что должна сделать наша программа - “сущности” (Entities)
- это инструмент извлечения значений параметров для
нашей программы из естественного языка (того что сказал или написал
пользователь) - “ответы
” - это конечный результат работы нашей программы, который мы
отправляем пользователю на его сообщение
Иногда для ответа пользователю достаточно информации из текущего диалога, в таком случае можно можно настроить статичные ответы в контекстах . В реальности для получения конкретного ответа нам может потребоваться внешний сервис или своя бизнес логика, например, чтобы получить информацию о погоде на завтра, нужно вызвать внешний API соответствующего сервиса. Позже я расскажу вам получать информацию из внешних систем, но для начала подготовим базу.
Создайте проект в API.AI
Для регистрации в API.AI вам потребуется аккаунт Google (достаточно завести в почту в Gmail). Теперь перейдите по адресу https://api.ai/ , нажмите на кнопку “SIGN UP FOR FREE”, а за тем выберите аккаунт, от имени которого хотите авторизоваться.
Теперь переходим к созданию самого агента. Нажмите на “Create agent” и укажите как минимум Имя(Name), Язык(Language) и Часовой пояс (Time Zone).
Шаг второй: Настройте агента.
Контекст отражает связь между тем, что говорит пользователь, и что должен сделать наш агент. В нашем случае, рассмотрим случай с прогнозом погоды:
- Кликните на в разделе “Контекст” (Intents). В агенте уже настроены “контексты” на приветствие и ошибки, оставим их пока без изменений.
- Укажите название для “контекста” - любое, главное чтобы оно было понятно вам и вашим коллегам.
- В разделе “Реплики пользователя” (User Says) приведите примеры вопросов, который может ваш пользователь. Так как мы говорим о погоде, человек может задать вопрос в привязке ко времени и место - учтем это. Чем больше примеров вы предоставите в настройках, тем точнее будет работать агент. Некоторые примеры я привел на скриншоте:
В последнем примере слова “завтра” и “Нижнем Тагиле” подсвечены разными цветами - таким образом слова связываются с сущностями (Entities ) (в нашем случае сущности системные). Используя эти параметры агент “поймет” в каком городе и для какой даты нужно узнавать погоду.
Добавьте еще парочку своих примеров и нажмите “Сохранить” (SAVE).
Тестируем!
Проверим работу агента на простых вопросах, например, “Погода в Перми в среду”:
Все это время в правой верхней части экрана маячила надпись “Try it now” - напишите в это поле или произнесите простой вопрос о погоде и нажмите “Ввод”.
Мы еще не настраивали автоматический ответ, но некоторые параметры агент уже научился определять! В разделе INTENT отражено, что по “мнению” агента пользователь интересуется погодой (настроенный нами “контекст”), в PARAMETER - дату и название города в соответствующих переменных.
Добавьте автоматические ответы
Сделаем нашего агента разговорчивей! Пока мы не научились получать информацию о погоде из внешних источников, добавим в качестве ответов простые фразы.
Перейдите в раздел “ Ответы” (Response) и введите простые ответы аналогично тому, как вы заполняли “Реплики пользователя”:
Как видите - в ответах можно использовать ссылки на выявленные сущности, начните набирать $ - и интерфейс предложит вам выбрать конкретную переменную.
При формировании ответа агент учитывает количество определенных сущностей и не использует ответы, данных для которых недостаточно. Например, на вопрос без указания города агент использует ответ из второй строки.
Сохраните настройки и протестируйте еще раз:
Теперь у нас есть еще и ответ!
Шаг третий: Добавьте внешний сервис.
Наш агент уже “понимает” в каких случая пользователь хочет узнать погоду, на какое число и в каком городе. Теперь осталось получить эти данные из подходящего сервиса и передать агенту. Для этого вам нужно написать парочку скриптов на JS и разместить их в облачном сервисе, в нашем случае - Google Cloud Project.
Создайте стартовый JS файл
Для начала, создайте и перейдите в директорию с именем вашего проекта:
Linux или Mac OS X:
mkdir ~/
cd ~/
mkdir %HOMEPATH%
cd %HOMEPATH%
Теперь создайте файл index.js со следующим содержанием:
Код index.js
/* * HTTP Cloud Function. * * @param {Object} req Cloud Function request context. * @param {Object} res Cloud Function response context. */ exports.itsm365Weather = function itsm365Weather (req, res) { response = "This is a sample response from your webhook!" //Default response from the webhook to show it"s working res.setHeader("Content-Type", "application/json"); //Requires application/json MIME type res.send(JSON.stringify({ "speech": response, "displayText": response //"speech" is the spoken version of the response, "displayText" is the visual version }));
Настройте Google Cloud Project
- Выполните настройки “Before you
begin” с 1 по 5 пункты
Разверните функцию в облаке выполнив в консоли:
gcloud beta functions deploy itsm365Weather --stage-bucket --trigger-http
где, itsm365Weather - название функции, а - наименование хранилища
данных для проекта.
После завершения операции вы увидите результат с URL http триггера:
Включите Webhook в API.AI
- Убедитесь, что находитесь в нужном агенте, а затем кликните “Fulfillment ” в левом скрывающемся меню.
- Включите использование Webhook в правой верхней части экрана.
- Введите URL, полученный на предыдущем этапе.
- Сохраните изменения.
Подключите исполнение новой функции в настройках “контекста”
- Перейдите в настройки “контекста” прогноза погоды
- Разверните блок Fulfillment в нижней части страницы
- Отметьте галочкой “Использовать Webhook”
- Сохраните настройки и проверьте результат:
Настройте API для получения погоды
Для простоты, воспользуемся сервисом WWO (World Weather Online), в котором вам нужно получить ключ API (просто зарегистрируйтесь через Facebook или Github).
Обновите код стартового JS файла, не забыв ввести ключ API для получения информации о погоде:
Исходный код сервиса для получения прогноза погоды
// Copyright 2017, Google, Inc. // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. "use strict"; const http = require("http"); const host = "api.worldweatheronline.com"; const wwoApiKey = "98cfb8e40ecc47c4a2f205209172608"; exports.itsm365Weather = (req, res) => { // Get the city and date from the request let city = req.body.result.parameters["geo-city"]; // city is a required param // Get the date for the weather forecast (if present) let date = ""; if (req.body.result.parameters["date"]) { date = req.body.result.parameters["date"]; console.log("Date: " + date); } // Call the weather API callWeatherApi(city, date).then((output) => { // Return the results of the weather API to API.AI res.setHeader("Content-Type", "application/json"); res.send(JSON.stringify({ "speech": output, "displayText": output })); }).catch((error) => { // If there is an error let the user know res.setHeader("Content-Type", "application/json"); res.send(JSON.stringify({ "speech": error, "displayText": error })); }); }; function callWeatherApi (city, date) { return new Promise((resolve, reject) => { // Create the path for the HTTP request to get the weather let path = "/premium/v1/weather.ashx?format=json&num_of_days=1" + "&q=" + encodeURIComponent(city) + "&key=" + wwoApiKey + "&date=" + date + "&lang=ru"; console.log("API Request: " + host + path); // Make the HTTP request to get the weather http.get({host: host, path: path}, (res) => { let body = ""; // var to store the response chunks res.on("data", (d) => { body += d; }); // store each response chunk res.on("end", () => { // After all the data has been received parse the JSON for desired data let response = JSON.parse(body); let forecast = response["data"]["weather"]; let location = response["data"]["request"]; let conditions = response["data"]["current_condition"]; let currentConditions = conditions["lang_ru"]["value"]; // Create response let output = `На ${forecast["date"]} в ${location["query"]} ${currentConditions}, температура воздуха от ${forecast["mintempC"]}°C до ${forecast["maxtempC"]}°C.`; // Resolve the promise with the output text console.log(output); resolve(output); }); res.on("error", (error) => { reject(error); }); }); }); }
Заново разверните функцию в облачном проекте.
Шаг четвертый: настройка ветвей диалога
Взаимодействуя с пользователем мы не можем быть уверены в том, что он предоставит нам всю информацию, необходимую для подготовки ответа во внешнем сервисе сразу в самом первом сообщении. В нашем примере для получения прогноза сервису потребуется дата и город. Если дата не известна, мы можем с успехом предположить, что пользователь подразумевает “сегодня”, но о городе мы можем узнать только от самого пользователя.
Сделайте “расположение” обязательным параметром
Откройте настройки контекста “Прогноз погоды” и укажите параметр geo-city обязательным к заполнению. Затем настройте уточняющий вопрос по ссылке в колонке “Prompts”.
Сохраните настройки и проверьте поведение агента, задав ему простой вопрос “погода”:
Агент задал нам уточняющий вопрос, в консоли отображены параметры текущей
ситуации.
Создайте возвращаемое уточнение для расположения
Чтобы использовать данные полученные на предыдущих этапа взаимодействия с пользователем, вам потребуется настроить соответствующие уточнения.
В настройка контекста “прогноз погоды” вбейте в поле “Add output context” название возвращаемого уточнения “location” и сохраните настройки.
Создайте новый контекст для уточнения
Удобно, когда по одному и тому же расположению можно задавать несколько вопросов, при этом не уточнять у пользователя, какой город он имеет ввиду. Вы уже настроили возвращаемое уточнение, которе как можно использовать для обработки уточняющих вопросов.
- Создайте новый контекст в разделе Intents
или кликните по значку в строке
Intents левого выдвигающегося меню. - Назовите новый контекст “Уточнение погоды” (или любое другое понятное вам название).
- Установите входящие и исходящие уточнения как “location”
- Добавьте реплики пользователя, например, “Что на счет завтра”
- Добавьте параметр сущности со следующими значениями:
- Parameter Name:
geo-city
- Value: #location.geo-city - Добавьте ответ для пользователя в раздел “Response
”:
- “Извини, но я не могу получить прогноз на $date-period в #location.geo-city” - Включите использование webhook в меню Fulfillment .
- Сохраните настройки и протестируйте в консоли:
Шаг пятый: Приветствие и обработка непредвиденных ситуаций
Основной костяк агента готов, теперь неплохо сделать так, чтобы робот
приветствовал пользователя, а также знал что отвечать на непредвиденные вопросы.
Настройте ответы “по умолчанию” для непредвиденных ситуаций
Если пользовать задаст непредвиденный вопрос (в нашем случае - не о погоде) агент включит в работу контекст для обработки непредвиденных ситуаций (Default Fallback Intent ):
Перейдите в настройке этого контекста, при необходимости настройте свои варианты ответов.
Настройте контекст приветствия
Приветствие можно настроить аналогичным способом в соответствующем контенте -
Default Welcome Intent
Шаг шестой: запустите бота
Подключите Telegram бота к агенту
Перейдите в настройки “Интеграций” (Integrations) и включите бота в разделе
“One-click integrations”:
Скопируйте в поле “Telegram token” токен, который вы получили у @botFather и
нажмите на START.
Проверьте работу бота
Перейдите в своего бота и попробуйте ему что-нибудь написать, в моем случае это
@itsm365_weather_bot (я пользовался бесплатными аккаунтами погоды, поэтому после 500 запросов в день бот превратится в тыкву).
Заключение
API.AI уже вполне можно пользоваться для построения диалоговых интерфейсов в мессенджерах, чатах поддержки с соцсетях. С учетом того, что инструмент можно легко интегрировать со своими сервисами - это удобная рабочая лошадка для автоматизации коммуникации с вашими пользователями.
P.S. Этой мой первый пост, буду признателен за конструктивную обратную связь!
Теги:
- api.ai
- telegram
- telegram bots