Телеграмм апи. Telegram API и его использование. Приступаем к кодированию

Развитие Телеграмм во многом определяется наличием большого числа ботов – небольших сервисных программ-роботов. Их может создать каждый пользователь, знакомый с программированием на среднем уровне. 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"}}

А в чате Телеграмм вы увидите приветствие от созданного робота.

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

В последнее время 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 выглядит вот так.

Для всеобщего использования платформы системы Телеграмм программистами и разработчиками предлагается целых два варианта взаимодействия: Telegram API (помогает делать индивидуальные клиенты внутри программы) и бот API (позволяет очень просто производить всевозможные программы для работы в Телеграмм с использованием его чат-сообщений как интерфейса и метода ввода информации).

Телеграм АПИ и боты

АПИ Телеграмма полностью открыт для внешнего рассмотрения и использования в своих программных разработках.

Чтобы сделать программу, полезную для вас или других пользователей мессенджера, не нужно обладать всем спектром знаний о том методе шифрования, который применяется тут. Для взаимодействия с сервером в данном случае применяется простой протокол https. Версия, используемая в рассматриваемом случае, является упрощенной, поэтому доступна всем.

Если говорить о втором варианте взаимодействия, который предлагается пользователям, бот АПИ, то он позволяет включать в работу системы ботов, причем без предоставления для них отдельного номера телефона, так как для бота он не нужен.

Важные моменты

Есть несколько важных моментов, которые стоит учитывать при использовании Телеграмм АПИ:

При создании приложений на русском или любом другом языке для выполнения полезных действий на базе платформы этого мессенджера необходимо, чтобы все пользователи данного программного продукта знали, что он является частью всей системы и в то же время разработан на ее базе.
Владельцы рекомендуют перед началом разработок ботов и других приложений получить собственный ID для использования АПИ Telegram.
Чтобы получить ИД-номер, нужно войти (сделать) свой аккаунт на https://my.telegram.org и, перейдя к папке инструментов по разработке АПИ, вписать все требующиеся данные в анкету на сайте.
Перед разработчиком, который собирается написать приложение для интеграции в Телеграмм, открывается масса возможностей. Вот, например, он может создать программу (бота) как на php, так и на языке python.
Несмотря на полную прозрачность и открытость, все же не разрешается в свои личных прогах, ботах, которые делаются для использования в Телеграмм-просторах, использовать для названия (или как часть названия) логотип и само наименование компании.

Создание игр

Одной из самых привлекательных сторон возможности участвовать в создании такой «махины», как Телеграмм с ее ботами, приложениями и другими встроенными функциями, безусловно, является чрезвычайно популярное направление - создание с помощью Телеграмма и его открытого АПИ игр.

Желающий поучаствовать в этом даже не должен будет все делать сам - есть специальные боты, которые помогают делать игру и значительно убыстряют этот процесс. После ее создания можно посылать готовый продукт в чаты и вообще весело проводить время.

Если новичок только приходит в мессенджер Телеграм, то у него сразу возникает вопрос, как пользоваться или, даже, как зарегистрироваться на сервисе. Для этого понадобится номер мобильного телефона и одно из приложений для Телеграм, которое можно будет найти и скачать на любую платформу и операционную систему по адресу: https://www.telegram.org. После того, как все это проделано, мы получаем в сети нового пользователя Телеграм и потенциального клиента наших каналов, раскручиваемых с помощью сервиса ВТопе.

Telegram.me скачать или открыть для доступа в канал

По мере того, как новичок продолжает свой путь по Телеграм, ему открывается, постепенно, неведомый доселе мир различных каналов. Ссылки вида Telegram.me нужно скачать или открыть на своем устройстве, чтобы попасть в заинтересовавший канал. Там, в чат ленте с другими пользователями и служебными ботами, просматривая новости, картинки, видео, пользователь (теперь уже подписчик канала) будет временами видеть рекламные сообщения, на которых и зарабатывает данный канал. Конечно, каждый из нас хотел бы иметь такой канал, но не все знают как.

Telegram API на русском доступен даже для новичков

Создать свой бизнес в Телеграм сейчас не так сложно как раньше. Открытые Telegram API давно уже на русском языке и позволяют, с помощью шаблонов и конструкторов, создать свой канал ботов к нему даже не очень опытным программистам.
Самую тяжелую часть работы – накрутку подписчиков возьмет на себя сервис по накрутке ВТопе. Зачем нужны подписчики? Чем их больше, тем больше стоит рекламный пост и тем больше денег он принесет владельцу канала. Такие дела в мире Телеграм.

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. Этой мой первый пост, буду признателен за конструктивную обратную связь!

Теги: