Telegram bot API

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

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

Элементы управления

В Бот Телеграмм API все элементы управления представляют собой объекты, которые представлены в JSON, то есть в виде строки, заданной по определенным правилам. Это позволяет производить обмен данными по сети максимально быстро и наименее затратно, так как передается не программный код, а набор пар «ключ:значение» в текстовом виде. В таблице приведены все типы API. Большая часть объектов предназначена для создания команд бота. Ключи дадут более расширенное представление о возможностях объекта.

Название Описание Ключи
User Пользователь в Телеграмм
Chat Чат
Message Сообщение
MessageEntity Отдельная сущность в текстовом сообщении (хештег, ссылка и пр.)
PhotoSize Изображение заданного размера или превью фото, файла или стикера
Audio Аудиозапись
Document Любой файл, не являющийся изображением, аудиозаписью или голосовой записью
Sticker Стикер
Video Видеозапись
Voice Голосовое сообщение
Contact Телефонный контакт
Location Точка на карте
Venue Объект на карте
UserProfilePhotos Фото профиля пользователя
File Готовый к загрузке файл
ReplyKeyboardMarkup Клавиатура с возможностью ответа
KeyboardButton Кнопка клавиатуры для ответа
ReplyKeyboardHide Заменяет клавиатуру бота на стандартную клавиатуру Telegram
InlineKeyboardMarkup Встроенная клавиатура, появляющаяся под сообщением inline_keyboard
InlineKeyboardButton Одна кнопка на встроенной клавиатуре
CallbackQuery Входящий запрос обратной связи для встроенной кнопки с заданным параметром callback_data
ForceReply Эмулирует действия пользователя: выбор сообщения и нажатия кнопки «Ответить»
ResponseParameters Сообщает, почему запрос не выполнился успешно

Результирующие строки, которые присылает мессенджер, представлены в виде тех же объектов API.

Обмен сообщениями происходит в виде запросов. В следующей таблице приведены примеры некоторых из них.

Метод Действие
getMe Позволяет получить информацию о пользователе
sendMessage Отправляет сообщение
sendPhoto Отправляет фото
sendAudio Отправляет аудио
sendDocument Отправляет документ
sendVideo Отправляет видео
sendContact Отправляет контакт
getUpdates Получает обновления из чата

Все методы (а их достаточно много) делятся на группы:

  1. Получение обновлений и информации.
  2. Работа в чате.
  3. Отправка различных элементов.
  4. Работа со стикерами.
  5. Обновление сообщений.
  6. Режим inline.
  7. Платежный функционал.
  8. Для игр.

Полной документации Telegram Bot API на русском пока не существует. Однако стандартный перевод в браузере Google Chrome прекрасно справляется с задачей.

Языки программирования

Telegram API поддерживается множеством языков программирования. Это дает возможность выбора создателю.

Любители JavaScript могут использовать Node.js Telegram Bot API. Здесь необходимо знание не только языка, но и умение обращаться с этим фреймворком, превратившим клиентский язык в полноценный серверный интерфейс.

Одним из самых популярных для написания ботов с использованием Telegram Bot API является PHP. Этот язык изначально был предназначен для создания серверных web-приложений. Он отличается простотой, логичностью и специализированностью именно для web-среды.

Пример использования

Кроме объектов API имеет набор методов, которые позволяют отправлять сообщения, файл, фото стикеры, редактировать и многое другое. Все эти команды можно найти в описании API на официальном сайте.

Для создания в Telegram существует специальный сервис @Botfather. Зайдите в него и увидите набор команд, с помощью которых создается новый робот. Для начала наберите команду /newbot. Далее последовательно введите имя для пользователей и название. Последнее обязательно заканчивается на «bot». После того, как вам пришлют токен (идентификатор), новый бот создан. Авторизация осуществляется через токен. Чтобы запустить программу в Телеграмм, найдите свое детище и нажмите кнопку «Старт». Это запустит преопределённую команду /start. Также для каждого робота зарезервированы команды /settings и /help.

Все запросы имеют вид:

https://api.telegram.org/bot/КОМАНДА

Всего существует 4 способа подачи запроса:

  1. Запрос в URL
  2. application/x-www-form-urlencoded
  3. application/json (не подходит для загрузки файлов)
  4. 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":"u044bu0443u0442u0430u043bu043eu0430u043cu0440"}}]}

Параметр 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"}}

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

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

11 July 2018, 20:13 MSK
Итак, снова пост про Телеграм. Я уже рассказывал, как отправлять сообщения от имени бота (в том числе, через прокси) и как сделать бота, который умеет принимать сообщения.
Отправлять сообщения в Телеграм от бота очень просто, но есть крайне неудобная проблема: из-за ограничений Telegram Bot API бот не может писать первым. То есть, сначала пользователь, которому вы собрались что-нибудь отправить, должен первым написать вашему боту любое сообщение. Это ограничение вполне разумно и предотвращает спам сообщениями от ботов, но очень мешает честным людям. Например, отправлять сервисные сообщения с информацией о заказе в интернет-магазине.
Решение этой проблемы только одно: не использовать ботов. Придётся всё делать с обычного аккаунта.
Копаться в подробностях телеграмовского протокола MTProto не нужно, как оказалось, всё уже сделано до нас. Для PHP существует чудесная библиотека MadelineProto. Её мы и будем использовать, ниже пошаговая инструкция.
1. Регистрируем аккаунт, с которого будет осуществляться отправка сообщений. Можно использовать существующий (но лучше сделать новый).
2. Нужно зарегистрировать приложение. Просто формальная процедура. Для этого идём на сайт https://my.telegram.org/, логинимся через ваш аккаунт в Телеграме. Лучше всего, чтобы этот аккаунт не совпадал с акаунтом из пункта 1. Далее переходим на страницу https://my.telegram.org/apps, заполняем поля (платформа — Web, остальное не так важно), отправляем форму. Всё готово — приложение создано. Вас перенаправит на страницу настроек, запоминаем оттуда поля App api_id и App api_hash, остальное не нужно.
3. Теперь нужно установить библиотеку MadelineProto. Делается это очень легко. Создаём на веб-сервере папку, в неё помещаем php-файл (например, index.php) со следующим содержимым:
 if (!file_exists('madeline.php')) {     copy('https://phar.madelineproto.xyz/madeline.php', 'madeline.php'); } include 'madeline.php'; $MP = new danogMadelineProtoAPI('session.madeline'); $MP->start();
Созданный скрипт должен иметь права на запись в папку. Библиотека требует PHP 7, но у меня всё завелось на PHP 5.6.
4. Запускаем созданный php-файл из браузера. На первом шаге выбираем Manually, затем вставляем значения полей App api_id и App api_hash из пункта 2, ждём, выбираем User, указываем телефонный номер акаунта из пункта 1, получаем на него смс, вводим код, готово — вы залогинились в Телеграме из вашего веб-приложения.
5. Переходим непосредственно к программированию. Весь код мы будем дописывать в имеющийся php-файл из пункта 3. У библиотеки MadelineProto есть хорошая документация, но некоторые моменты не очень понятны с первого раза.
Для отправки сообщений нужно использовать метод sendMessage
:
$MP->messages->sendMessage(['peer' => '', 'message' => '']);
Здесь peer
 — ID получателя, message
 — текст сообщения. И вот тут есть загвоздка: а где, собственно, взять айдишник пользователя, которому мы будем слать сообщения, если мы знаем только номер телефона?
Для этого проще всего добавить телефон получателя во внутренний список контактов. Делается это так:
$contact = ['_' => 'inputPhoneContact', 'client_id' => 0, 'phone' => '+79xxxxxxxxx', 'first_name' => '', 'last_name' => '']; $import = $MP->contacts->importContacts(['contacts' => [$contact]]); // $import['imported'][0]['user_id'] - ID пользователя
Здесь мы указываем phone
 — номер телефона, first_name
и last_name
 — имя и фамилия (можно указать любые, это не важно). В переменной $import[’imported’][0][’user_id’]
будет содержаться ID нашего получателя. Хорошо бы его куда-нибудь сохранить у себя, чтобы можно было использовать дальше.
После этого мы вызываем метод sendMessage
и передаём ему полученный ID. Также в качестве peer
можно передать никнейм (например, @name). Собственно, это всё!
Использовать данный метод для рассылки спама бесполезно — аккаунт довольно быстро заблокируют по жалобам пользователей.
  • Tutorial

Чат боты — довольно интересная тема, которой интересуются как гики-энтузиасты, так и компании, которые хотят организовать взаимодействие со своими клиентами наиболее удобным для них способом

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

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

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

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

  1. Отправьте команду /newbot — так мы сообщаем @BotFather, что нам нужен новый бот
  2. Если имя не занято, получаем сообщение с подтверждением и токен доступа.

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

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

Пришло время создать агента 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:

  • Windows:

Теперь создайте файл 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

  • Разверните функцию в облаке выполнив в консоли:

    gcloud beta functions deploy itsm365Weather —stage-bucket [BUCKET_NAME] —trigger-http

После завершения операции вы увидите результат с 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({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'][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 = `На ${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” и сохраните настройки.

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

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

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

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

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

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

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

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

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

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

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

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

Заключение

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

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

Рейтинг автора
5
Подборку подготовил
Андрей Ульянов
Наш эксперт
Написано статей
168
Ссылка на основную публикацию
Похожие публикации