Как пользоваться api telegram

Telegram API и его использование

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

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

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

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

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

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

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

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

Создание игр

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

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

Телеграм API

У нас уже есть готовый коннектор по api с сервисом Телеграм! Вы можете подключится к нашей системе и не тратить время на написание кода.

Через 5 минут после регистрации, можно начать пользоваться доступными функциями, не привлекая программистов. Принцип работы смотрите ниже!

разных систем

Принцип работы

Наши разработчики уже разобрались как работает API для системы Телеграм и создали готовый коннектор. По такому же принципу мы сделали коннекторы с другими онлайн сервисами, всего их у нас уже более 200!

Теперь Вам не нужно тратить время на написание программного кода самостоятельно, связать 2 и более сервиса можно через наш онлайн интерфейс в несколько кликов!

Вот как выглядит работа нашей системы с другими системам

Сразу после регистрации, Вам будет доступна возможность «соединять» между собой более 200 разных онлайн сервисов. Не привлекая программистов и без специальных знаний в области программирования! Для того чтобы начать, пройдите регистрацию в 1 клик!

Без ограничений
Получите 14-ти дневный
пробный доступ

Как интегрировать Телеграм и другие системы
c помощью ApiX Drive по API

Теперь Вам не нужно привлекать программистов или интеграторов для автоматизации Телеграм с другими системами.
С ApiX-Drive вы свяжете и автоматизируете работу этих систем за 5 минут, самостоятельно.

Выберите онлайн системы которые нужно «связать»
Укажите какие действия будут происходить между системами
Включите автообновление
Вся настройка займет не более 5-ти минут

Возможности автоматизации Телеграм
с другими системами по API

Настройте один раз правила, по которым будут работать системы.
С заданным интервалом обменивайтесь данными Телеграм и другими системами

Приемник данных: Телеграм, доступные действия:

• Отправить СООБЩЕНИЕ

Популярные вопросы про интеграцию с Телеграм

Как происходит интеграция Телеграм?

• Для начала нужно зарегистрироваться в ApiX-Drive
• Далее выбираете в веб интерфейсе с каким сервисом нужно сделать интеграцию Телеграм (на данный момент доступно 300 готовых коннекторов)
• Выбираете какие данные из одной системы передавать в другую
• Включаете автообновление
• Теперь данные будут автоматически передаваться из одной системы в другую

Сколько времени нужно на интеграцию?

В зависимости от системы, с которой вы будете делать интеграцию, время настройки может отличаться и составлять от 5-ти до 30-минут. В среднем настройка занимает 10-15 минут.

Сколько стоит интеграция Телеграм с другими системами?

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

Сколько готовых интеграций доступно для Телеграм?

На данный момент у нас готово 300 интеграций Телеграм c другими системами
Информация по API для Телеграм

Одно из несомненных достоинств Telegram заключается в том, что это не просто обычный мессенджер, но скорее социальная платформа, открытая для различных сторонних приложений, предоставляющих дополнительные возможности пользователям.

При этом разработчикам доступны два вида API – Bot API и Telegram API. Первый, как можно догадаться уже из названия, служит для создания ботов, в то время как второй позволяет вам создавать собственные Telegram-клиенты. В обоих используется формат запроса JSON, значения передаются в кодировке UTF-8. Подробная документация, необходимая для того, чтобы разобраться со всеми нюансами использования API, доступна на этой странице: https://core.telegram.org/api

Если вы обладаете навыками программирования, то разобраться во всех тонкостях, описанных в документации, не составит труда. Другой вариант, экономящий время, но более дорогой – прибегнуть к услугам профессионального разработчика. Иными словами, для использования всех возможностей API, нужно потратить либо время, либо деньги.

Но существует ещё и третий путь – прибегнуть к услугам сервиса ApiX-Drive. Он специально создавался для того, чтобы упростить процедуру налаживания связей между самыми разными системами. Не нужно обладать какими-либо знаниями или обращаться к тем, кто ими уже обладает. Всё очень просто и интуитивно понятно, налаживание любой связи потребует минимум времени. Немаловажно и то, что использование ApiX-Drive обходится совсем недорого, в отличие от услуг профессионального разработчика.

Telegram API: наглядный разбор с примерами

Для любого бизнеса важно установить канал общения с клиентами. Но сделать это не так просто. Психология людей такова, что они не хотят захламлять память своего смартфона новым фирменным приложением из того места, которое они посетили. Совсем другое дело — чат-бот. Ненавязчивый и дружелюбный. А кроме того — со всеми необходимыми фишками: рекламными акциями, скидками и быстрым заказом. И уведомления в одном единственном удобном мессенджере. Почему бы его не реализовать в своем бизнесе? Тем более, что это не так сложно, как вы думаете.

Курс Англійської.
Подолай мовний бар’єр та розширюй коло друзів на розмовних клубах.

Сегодня мы поговорим о ботах и их API ( telegram api ) на базе популярного мессенджера Telegram.

Содержание

Telegram Bot API и Telegram API

Все началось с того, что Николай Дуров совместно с командой программистов создал криптографический протокол. Его движок задействовал комбинацию симметричного шифрования AES , протокол Диффи-Хеллмана для обмена ключами шифрования между клиентами и ряд хеш-функций. На основе этого протокола был построен MTProto — механизм, позволяющий пользователям сегодня использовать Telegram-мессенджеры.

На данный момент есть два основных инструмента API, с помощью которых можно задействовать сервисы Telegram — Telegram Bot API и Telegram API . Первый служит для разработки чат-ботов, второй позволяет делать полностью кастомные Telegram-клиенты. Разработчикам также доступна открытая библиотека TDLib (Telegram Database Library), с помощью которой можно создавать свою версию мессенджера с уникальными опциями (как например, Telegram X, построенный именно на TDLib). Telegram Bot API является надстройкой над Telegram API , поэтому пользоваться Bot API можно без знаний о механизме используемого протокола MTProto .

Курс Front-end Basic.

Оволодій навичками розробки веб-інтерфейсів та стань справжнім Front-end розробником! Заробляй від 800$ на початку карʼєри.

Бизнес активно использует чат-боты при работе с клиентами, это направление будет приоритетным в ближайшее время в особенности для интернет-маркетинга. Наши друзья из Laba организовали хорошие курсы по лидогенерации, они будут полезны как владельцам бизнеса, так и маркетологам.

Для его работы задействован промежуточный сервер с HTTPS-интерфейсом, который шифрует трафик и обеспечивает связь с Telegram API. Bot API позволяет легко создавать программы, которые используют интерфейс Telegram для выполнения кода на локальном сервере. Пользователи могут взаимодействовать с ботами, отправляя им сообщения, команды и встроенные запросы.

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

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

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

На GitHub ( https://github.com/tdlib/telegram-bot-api ) можно найти исходники сервера Bot API. Развернув такой сервер вы получите HTTP URL с возможностью организации работы через вебхуки. Также сможете загружать файлы (до двух терабайт) на локальный сервер. Сервер Bot API имеет возможность настройки порта и локального IP-адреса для вебхука, а также поддерживает до 100000 одновременных подключений — более чем достаточно для большинства задач.

BotFather: быстрый Start

Чтобы приступить к созданию собственного бота, необходимо получить токен для авторизации и подключения через API. Делается это при помощи служебного бота. Введите в поиске Telegram его имя — BotFather. Далее следует выбрать команду /newbot и дать имя боту.

Затем BotFather спросит вас имя, которое обязательно должно заканчиваться на bot , например, shop_serge_bot . Далее для бота будет сгенерирован уникальный токен, который будет выглядеть примерно так — 2093336709:AAGiH64Ec1R8r222sM9IywvlIGFkb7wFqyo .

Всего можно генерировать не более 20 ботов на одного пользователя. Управление ботами также происходит через меню команд служебного бота BotFather. Например, если вам потребуется настроить какой-то из ваших ботов, вы должны перейти по командам / mybots и затем нажать на кнопку Edit Bot . Здесь вы сможете настроить имя — Edit Name и указать описание — Edit Description .

Курс Python.

Цю мову програмування використовують від базових концепцій до складних застосувань у сферах штучного інтелекту. Після проходження курсу гарантовано отримай роботу в ІТ.

Настраивая description для бота вы задаете текст, который будет показываться пользователям под сообщением « Что может делать этот бот? » когда они его будут подключать. В профиле бота также будут показаны сведения, которые вы задали в поле « About » (команда Edit About). В меню команд имеется возможность установить аватар — BotPic .

В меню настроек BotSettings включается режим встроенных запросов (по умолчанию эта опция отключена). Когда встроенные запросы активированы, пользователи могут вызвать вашего бота, просто введя имя пользователя в поле для ввода текста в любом чате, группе или канале.

Если Telegram использовать в коммерческих целях, чат-бот можно вооружить средствами для приема платежей. Стоит обратить внимание, что сам Telegram не занимается проведением транзакций, он лишь дает возможность подключить услуги длинного списка провайдеров.

В их числе такие платежные системы, как Stripe, YooMoney, Сбербанк, PayMaster, PSB, Tranzzo, Payme, CLICK, LiqPay, Portmone, Paymega, ECOMMPAY и др. Разумеется, чтобы использовать эти платежные системы, нужно быть юридическим лицом.

aiogram — асинхронная библиотека

Реализовывать свой проект удобнее при помощи библиотек, таких как aiogram — это, пожалуй, лучшая стабильная асинхронная библиотека для Python ( https://pypi.org/project/aiogram/ ).

Относительно асинхронности нужно сказать несколько слов. Python — язык однопоточный, и любые команды в нем выполняются только после того, как завершилось выполнение предыдущей команды. Однако в случае с ботом программе необходимо отвечать на множество сообщений и делать это очень быстро. Можно, конечно, плодить множество потоков выполнений, но такой вариант чаще всего неприемлем, и альтернативой выступает асинхронная реализация задачи.

Когда в потоке выполнения команды возникает какая-то пауза, например, работает функция и у нее при этом есть какой-то таймаут ожидания, мы получаем участок времени, который не занят решением алгоритма. Асинхронность в aiogram позволяет заполнить эти промежутки, ускоряя работу нашего бота и быстро отвечая на сообщения. Устанавливается эта библиотека следующей командой :

pip install -U aiogram.

Создаем эхо-бот

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

Курс UI/UX для геймдеву.

Під час навчання ви розробите проекти для портфоліо, що складається з 5 ключових аспектів UX/UI-дизайну, та отримаєш необхідні навички для професійного росту.

Создаем конфигурационный файл config.py и указываем в нем значение, сгенерированное ботом BotFather. Приступаем к написанию кода самого чат-бота.

Для начала импортируем конфигурацию и систему логирования. Затем подключаем все необходимые модули из aiogram . Указываем уровень логирования, а затем инициализируем бота, создав две переменные — Bot и Dispatcher .

Первая отвечает за прямой доступ к методам API и обеспечивает общее взаимодействие с ботом. Вторая, Dispatcher — простой обработчик событий. Мы обращаемся к этому обработчику событий и вызываем декоратор message_handler , который будет вызываться тогда, когда приходит событие о новом сообщении.

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

import config import logging from aiogram import Bot, Dispatcher, executor, types logging.basicConfig(level=logging.INFO) bot = Bot(token=config.TOKEN) dp = Dispatcher(bot) @dp.message_handler() async def echo(message: types.Message): await message.answer(message.text) if __name__ == "__main__": executor.start_polling(dp, skip_updates=True)

Как уже говорилось ранее, обработка событий в Telegram может происходить двумя способами — long polling , когда мы со своей стороны постоянно запрашиваем сервер, а второй вариант — более мощное и быстрое решение вебхук . Реализация long polling на Linux имеет большой минус — бот часто зависает и его приходится постоянно перезапускать.

В случае с webhook бот загружается на сервер, у бота появляется API с url-адресом, сервер Teleram посылает нашему боту сообщения, как только они появляются. По сути, бот на вебхуках постоянно не работает, а включается лишь тогда, когда получает запрос с сервера. Этот метод предпочтительнее, он быстрее, но для тестов обычно используется long polling .

Если вы делаете бота, который работает с деньгами или какой-то конфиденциальной информацией, то параметр skip_updates лучше устанавливать в значение Falsе — тогда обработчик не будет пропускать старые события и будет обрабатывать их в любом случае. Если этого не делать, существует вероятность, что какая-нибудь важная транзакция может потеряться и возникнет потенциальная угроза безопасности (или коллизия).

Оформление: кнопки и текст

Все сообщения в Telegram можно форматировать, используя различные варианты оформления текста — жирный, курсив и т.д. В Bot API разметка сообщений может создаваться в HTML и Markdown. Для удобства в ботах применяются кнопки, которые ставят под сообщениями. Их называют инлайн-клавиатурой или инлайн-кнопками, и они бывают разных видов.

Например, URL button — простая кнопка со ссылкой на какой-то веб-ресурс. Вариант кнопки Callback запрашивает обновление. Она может применяться, скажем, для уведомлений или предупреждений (с окном notification или окном alert ). Кнопка для перехода в режим инлайн может открывать меню для выбора чата.

Другой тип кнопок — клавиатурный. Он дают возможность использовать подсказки бота. Например, они могут содержать наиболее частые запросы, ожидаемые от пользователя ( « как к вам проехать » , « время работы » и т.д.)

Один из примеров такой клавиатуры — бот в кафе для дистанционного принятия заказов:

import config import logging from aiogram.dispatcher.filters import Text from aiogram import Bot, Dispatcher, executor, types logging.basicConfig(level=logging.INFO) bot = Bot(token=config.TOKEN) dp = Dispatcher(bot) @dp.message_handler(commands="start") async def cmd_start(message: types.Message): keyboard = types.ReplyKeyboardMarkup(resize_keyboard=True) buttons = ["С сахаром", "Без сахара"] keyboard.add(*buttons) await message.answer("Вам кофе с сахаром?", reply_markup=keyboard) @dp.message_handler(Text(equals="Конечно")) async def with_puree(message: types.Message): await message.reply("Эспрессо с сахаром!") @dp.message_handler(lambda message: message.text == "Без сахара") async def without_puree(message: types.Message): await message.reply("Эспрессо без сахара!") if __name__ == "__main__": executor.start_polling(dp, skip_updates=True)

Инструмент для оформления текста выбирается аргументом функции parse_mode .

from aiogram import types await message.answer("Жирное начертание HTML-разметкой", parse_mode=types.ParseMode.HTML) await message.answer("Оформление *текста MarkdownV2*\!", parse_mode="MarkdownV2")

Когда текст всех сообщений одинаково оформлен, это удобно — при этом можно сразу передать нужный тип Bot . Если все-таки для какого-то сообщения разметка не понадобится, то в этом месте ставится пустое значение parse_mode=»» .

bot = Bot(token="2093336701:AAGiH64eA1R8g222sF9IywvlIGFkb7wFqyo", parse_mode=types.ParseMode.HTML) await message.answer("Текстовый блок с HTML-разметкой") await message.answer("Текстовый блок без применения разметки", parse_mode="")

Используя модуль markdown из aiogram.utils по ходу текста можно менять форматирование. Тип форматирования определяется функцией с дописанной к ней букве h , которая означает поддержку HTML.

import aiogram.utils.markdown as LPT await message.answer( LPT.text( LPT.text(LPT.hunderline("Смартфон Samsаng"), ", год выпуска 2021"), LPT.text("Стоимость без скидки:", LPT.hstrikethrough(888), "долларов"), LPT.text("Новая цена:", LPT.hbold(777), "долларов"), sep="\n"), parse_mode="HTML")

Учим бот-модерации

Как видите, эхо-бот, код которого написан выше, отвечает нам теми же сообщениями, которые мы отсылаем. Однако, если мы добавим бот в какую-нибудь тестовую группу, то возвращать текстовые сообщения он уже не будет. Причина этого очевидна — боты Telegram не имеют доступа к сообщениям в групповых чатах. Чтобы изменить это, необходимо снова вернуться к меню BotFather и разделе меню Group Privacy выбрать Turn OFF .

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

Отредактируем код нашего бота. Если в тексте сообщения содержатся плохие (матерные) слова, наш бот-админ их автоматически распознает и удалит. Для этого вместо нашей echo функции ставим фильтр:

import config import logging from aiogram import Bot, Dispatcher, executor, types logging.basicConfig(level=logging.INFO) bot = Bot(token=config.TOKEN) dp = Dispatcher(bot) @dp.message_handler() async def filter_messages(message: types.Message): if "плохое_слово" in message.text: await message.delete() if __name__ == "__main__": executor.start_polling(dp, skip_updates=True)

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

Кстати, аналогичным образом можно удалять надоедливые информационные сообщения о том, что к чату присоединился какой-то пользователь. В этом случае код будет практически идентичным. Мы вызываем тот же декоратор message_handler , только указываем в аргументах content_types в значении new_chat_memebers .

Мы это сделали, чтобы функция обрабатывала сообщения только каких-то конкретных типов, в данном случае — сервисные сообщения. Также бывают еще текстовые сообщения, медиасообщения, голосовые и пр.

import config import logging from aiogram import Bot, Dispatcher, executor, types logging.basicConfig(level=logging.INFO) bot = Bot(token=config.TOKEN) dp = Dispatcher(bot) @dp message_handler(content_types=["new_chat_members"]) async def on_user joined(message: types.Message): @dp.message_handler() async def filter_messages(message: types.Message): if "плохое_слово" in message.text: await message.delete() if __name__ == "__main__": executor.start_polling(dp, skip_updates=True)

Даем возможность бана в группе

Помимо основного кода нам понадобится сделать файл filters.py , который поместим рядом с главным файлом нашего бота:

from aiogram import types from aiogram.dispatcher.filters import BoundFilter class IsAdminFilter(BoundFilter): key = "is_admin" def __init__(self, is_admin): self.is_admin = is_admin async def check(self, message: types.Message): member = await message.bot.get_chat_member(message.chat.id, message.from_user.id) return member.is_chat_admin()

В коде бота мы его импортируем:

import config import logging from aiogram import Bot, Dispatcher, executor, types from filters import IsAdminFilter logging.basicConfig(level=logging.INFO) bot = Bot(token=config.TOKEN) dp = Dispatcher(bot) dp.filters_factory.bind(IsAdminFilter) @dp.message_handler(is_admin=True, commands=["бан"], commands_prefix="!/") async def cmd_ban(message: types.Message): if not message.reply_to_message: await message.reply("это должен быть ответ на сообщение") return await bot.kick_chat_member(chat_id=message.chat.id, user_id=message.reply_to_message.from_user.id) await message.delete() await message.reply_to_message.reply("пользователь наказан!") @dp.message_handler() async def filter_messages(message: types.Message): if "мат" in message.text: await message.delete() if __name__ == "__main__": executor.start_polling(dp, skip_updates=True)

Также необходимо в конфигурационном файле config.py указать id чата ( GROUP_ID ).

Все пользователи Telegram имеют свой id . Он постоянный, и поэтому по нему можно идентифицировать чаты. Если вдруг вы не знаете id , вы можете воспользоваться ботом @username_to_id_bot , который покажет это значение.

В токене бота первая часть — это его id . Например, токен 110301514:AмHdqTcvCG1vGWDxfyeDfSAs0K5PALDsaw принадлежит боту с id 110301514 . В Bot API перед id супергрупп и каналов добавляется -100 (например, id 1322414430 превращается в -1001322414430 ).

Заключение

Как видите, сложного ничего нет и все трудности при разработке чат-ботов сводятся к тому, чтобы найти оптимальный API и библиотеку под Python, C#, PHP и другие языки программирования. Сегодня это явный тренд, чат-боты могут создавать воронки продаж не хуже опытных менеджеров, а кроме того берут на себя массу функций, требовавших ранее человеческих ресурсов, — запись на прием к врачу, продажа билетов и так далее.

Более сложные боты обладают искусственным интеллектом и умеют использовать нейронные сети. Возможности таких чат-ботов ограничены только вашей фантазией, но об этом — в следующий раз. А пока посмотрите дополнительное видео по технике создания ботов на JavaScript для Telegram API :

Создаем Telegram бота на API.AI

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

Шаг первый: Подготовка инфраструктуры.

В этом кейсе мы будем использовать только Telegram бота и API.AI, оба сервиса предоставляются бесплатно — нам остается только завести учетные записи.

Создайте бота Telegram

Чтобы создать бота — просто напишите @BotFather (это такой бот, которые умеет создавать и настраивать другие боты):

1. Отправьте команду /newbot — так мы сообщаем @BotFather, что нам нужен новый бот
2. Теперь @BotFather попросит нас дать имя новому боту. Это имя будут видеть наши
   будущие пользователи, поэтому название нужно давать понятное и простое.
3. Последним шагом укажем для бота username, в конце которого нужно обязательно
   написать “bot”.
4. Если имя не занято, получаем сообщение с подтверждением и токен доступа.

Чтобы было понятнее — ниже скриншот со всеми действиям:

Немного теории

Пришло время создать агента API.AI, который в сущности является проектом или контейнером (как вам удобнее называть). Агент содержит настройки контекстов, сущностей и ответов:

• “контекст” (Intent) отражает связь между тем, что сказал пользователь и
  тем что должна сделать наша программа
• “сущности” (Entities) — это инструмент извлечения значений параметров для
  нашей программы из естественного языка (того что сказал или написал
  пользователь)
• “ответы” — это конечный результат работы нашей программы, который мы
  отправляем пользователю на его сообщение

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

Создайте проект в API.AI

Для регистрации в API.AI вам потребуется аккаунт Google (достаточно завести в почту в Gmail). Теперь перейдите по адресу https://api.ai/, нажмите на кнопку “SIGN UP FOR FREE”, а за тем выберите аккаунт, от имени которого хотите авторизоваться.

Теперь переходим к созданию самого агента. Нажмите на “Create agent” и укажите как минимум Имя(Name), Язык(Language) и Часовой пояс (Time Zone).

Шаг второй: Настройте агента.

Контекст отражает связь между тем, что говорит пользователь, и что должен сделать наш агент. В нашем случае, рассмотрим случай с прогнозом погоды:

1. Кликните на в разделе “Контекст” (Intents). В агенте уже настроены “контексты” на приветствие и ошибки, оставим их пока без изменений.
2. Укажите название для “контекста” — любое, главное чтобы оно было понятно вам и вашим коллегам.
3. В разделе “Реплики пользователя” (User Says) приведите примеры вопросов, который может ваш пользователь. Так как мы говорим о погоде, человек может задать вопрос в привязке ко времени и место — учтем это. Чем больше примеров вы предоставите в настройках, тем точнее будет работать агент. Некоторые примеры я привел на скриншоте:

В последнем примере слова “завтра” и “Нижнем Тагиле” подсвечены разными цветами — таким образом слова связываются с сущностями (Entities) (в нашем случае сущности системные). Используя эти параметры агент “поймет” в каком городе и для какой даты нужно узнавать погоду.

Добавьте еще парочку своих примеров и нажмите “Сохранить” (SAVE).

Тестируем!

Проверим работу агента на простых вопросах, например, “Погода в Перми в среду”:

Все это время в правой верхней части экрана маячила надпись “Try it now” — напишите в это поле или произнесите простой вопрос о погоде и нажмите “Ввод”.

Мы еще не настраивали автоматический ответ, но некоторые параметры агент уже научился определять! В разделе INTENT отражено, что по “мнению” агента пользователь интересуется погодой (настроенный нами “контекст”), в PARAMETER — дату и название города в соответствующих переменных.

Добавьте автоматические ответы

Сделаем нашего агента разговорчивей! Пока мы не научились получать информацию о погоде из внешних источников, добавим в качестве ответов простые фразы.

Перейдите в раздел “ Ответы” (Response) и введите простые ответы аналогично тому, как вы заполняли “Реплики пользователя”:

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

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

Сохраните настройки и протестируйте еще раз:

Теперь у нас есть еще и ответ!

Шаг третий: Добавьте внешний сервис.

Наш агент уже “понимает” в каких случая пользователь хочет узнать погоду, на какое число и в каком городе. Теперь осталось получить эти данные из подходящего сервиса и передать агенту. Для этого вам нужно написать парочку скриптов на JS и разместить их в облачном сервисе, в нашем случае — Google Cloud Project.

Создайте стартовый JS файл

Для начала, создайте и перейдите в директорию с именем вашего проекта:

• Linux или Mac OS X:
  mkdir ~/[PROJECT_NAME]
  cd ~/[PROJECT_NAME]
• Windows:
  mkdir %HOMEPATH%[PROJECT_NAME]
  cd %HOMEPATH%[PROJECT_NAME]

Теперь создайте файл index.js со следующим содержанием:

Код index.js

/* * HTTP Cloud Function. * * @param req Cloud Function request context. * @param 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 [BUCKET_NAME] —trigger-http

где, itsm365Weather — название функции, а [BUCKET_NAME] — наименование хранилища
данных для проекта.

После завершения операции вы увидите результат с URL http триггера:

Включите Webhook в API.AI

1. Убедитесь, что находитесь в нужном агенте, а затем кликните “Fulfillment” в левом скрывающемся меню.
2. Включите использование Webhook в правой верхней части экрана.
3. Введите URL, полученный на предыдущем этапе.
4. Сохраните изменения.

Подключите исполнение новой функции в настройках “контекста”

1. Перейдите в настройки “контекста” прогноза погоды
2. Разверните блок Fulfillment в нижней части страницы
3. Отметьте галочкой “Использовать Webhook”
4. Сохраните настройки и проверьте результат:

Настройте 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(, (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'][0]; let location = response['data']['request'][0]; let conditions = response['data']['current_condition'][0]; let currentConditions = conditions['lang_ru'][0]['value']; // Create response let output = `На $в $ $, температура воздуха от $°C до $°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” и сохраните настройки.

Создайте новый контекст для уточнения

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

1. Создайте новый контекст в разделе Intents или кликните по значку в строке
   Intents левого выдвигающегося меню.
2. Назовите новый контекст “Уточнение погоды” (или любое другое понятное вам название).
3. Установите входящие и исходящие уточнения как “location”
4. Добавьте реплики пользователя, например, “Что на счет завтра”
5. Добавьте параметр сущности со следующими значениями:
   — Parameter Name:
   geo-city
   — Value: #location.geo-city
6. Добавьте ответ для пользователя в раздел “Response”:
   — “Извини, но я не могу получить прогноз на $date-period в #location.geo-city”
7. Включите использование webhook в меню Fulfillment.
8. Сохраните настройки и протестируйте в консоли:

Шаг пятый: Приветствие и обработка непредвиденных ситуаций

Основной костяк агента готов, теперь неплохо сделать так, чтобы робот
приветствовал пользователя, а также знал что отвечать на непредвиденные вопросы.

Настройте ответы “по умолчанию” для непредвиденных ситуаций

Если пользовать задаст непредвиденный вопрос (в нашем случае — не о погоде) агент включит в работу контекст для обработки непредвиденных ситуаций (Default Fallback Intent):

Перейдите в настройке этого контекста, при необходимости настройте свои варианты ответов.

Настройте контекст приветствия

Приветствие можно настроить аналогичным способом в соответствующем контенте —
Default Welcome Intent

Шаг шестой: запустите бота

Подключите Telegram бота к агенту

Перейдите в настройки “Интеграций” (Integrations) и включите бота в разделе
“One-click integrations”:

Скопируйте в поле “Telegram token” токен, который вы получили у @botFather и
нажмите на START.

Проверьте работу бота

Перейдите в своего бота и попробуйте ему что-нибудь написать, в моем случае это
@itsm365_weather_bot (я пользовался бесплатными аккаунтами погоды, поэтому после 500 запросов в день бот превратится в тыкву).

Заключение

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

P.S. Этой мой первый пост, буду признателен за конструктивную обратную связь!