Telegram bot – web hook installation and simple steps

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

Что нам понадобится дальше

• секретный ключ API, который создали ранее – именно он будет являться визитной карточкой перед Telegram API
• веб-сайт с поддержкой PHP (и желательно MySQL), работающий по HTTPS защищенному протоколу (вполне подойдет и бесплатный Let’s Encrypt)
• стартовый телеграм PHP API с гитхаба – который мы и начнем видоизменять под свои нужды
• настроенный Вебхук API Telegram к нашему сайту

Что же такое вебхук (webhook)

Вебхук – это механизм оповещения о происходящих в системе событиях посредством функций обратных вызовов. Когда случается интересующее клиента событие, сервер отправляет HTTP-запрос на URL-адрес, предоставленный клиентом для приема вебхуков. В нашем случае при помощи вебхука API Telegram будет общаться с областью нашего сайта, где будет расположен PHP код, который описывает поведение бота в зависимости от входящих сообщений.

Создание вебхука

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

Для начала решим, где будет находиться код на вашем сайте, который будет заниматься обработкой команд бота. Скорее всего это будет директория в корне сайта, например:

https://[ИМЯ_ВАШЕГО_САЙТА]/bot/

Далее качаем начальный код бота с гитхаба по ссылке: https://github.com/webportnoy/telegram_bot/archive/master.zip и содержимое архива распаковываем и помещаем в директорию на вашем сайте, которая была описана выше.

После того, как файлы размещены в нужном месте, делаем то, ради чего мы здесь собрались – вебхук. Для этого в любом текстовом редакторе сформируйте строку такого вида:

https://api.telegram.org/bot[ВАШ_API_КЛЮЧ_ТЕЛЕГРАМ_БОТА]/setWebhook?url=https://[ИМЯ_ВАШЕГО_САЙТА]/bot/bot.php

Полученную строку вставляем в адресную строку любого браузера и видим ответ от сервера API Telegram, который явно дает понять, что вебхук успешно установлен:

Существует и другой способ установки вебхука, который можно вычитать в файле README.md, расположенного в корне демонстрационного кода. Рекомендую ознакомиться с содержимым этого файла.

Основные настройки в коде PHP

Теперь, для того, чтобы бот заработал, надо внести некоторые правки в файлах демонстрационного кода. Для этого открываем файл bot.php и меняем код на код ниже, так как для примера и понимания механики работы бота начнем с примера, оставленного разработчиками:

<?php
require_once("example_bot.php");
$bot = new TestBot();
$bot->replyCommand();
?>

Теперь в файле примера необходимо будет также сделать ряд изменений. Открываем файл example_bot.php, ищем строки:

	//protected $token = "";
	//protected $bot_name = "";

Раскомментируем их и задаем значения, соответствующие нашему боту:

	protected $token = "[ВАШ_API_КЛЮЧ_ТЕЛЕГРАМ_БОТА]";
	protected $bot_name = "@TopsitesTestBot";  // имя ВАШЕГО бота

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

Тестовый бот

Пощупать и посмотреть, как работает демонстрационный бот можно по этой ссылке – https://t.me/kpg_test_bot. Если вы все настроили правильно, то ваш бот будет в точности повторять все действия этого бота.

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

Давайте разберемся, что из данной структуры скорее всего понадобится для разработки бота.

1). Текст сообщения, которое прислал пользователь

$this->result["message"]["text"]

Попросту говоря, это то, что пользователь бота присылает чат боту. Если я пишу боту “Привет, как у тебя дела?”, то данны элемент как раз будет иметь такое значение.

$this->result["message"]["text"] = "Привет, как у тебя дела?";

2). Данные о пользователе, который прислал сообщение

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

$this->result["message"]["chat"]["id"]

У телеграм API чат айди пользователя обычно состоит из 9-10 цифр, что-то типа: 320930994 или 1324900345 – примерно такие значения следует ожидать.

Я думаю, что у вас уже возникли мысли о том, как можно использовать данный айди. Конечно же – авторизация. Если по простому, то прежде, чем бот будет присылать какую-то информацию, он может проверять, можно ли что-то присылать этому chat_id.

Также из структуры сообщения можно вытащить имя и фамилию пользователя, которые он указал в информации о своей учетной записи в телеграм имя и фамилия:

$this->result["message"]["from"]["first_name"] // Имя
$this->result["message"]["from"]["last_name"]  // Фамилия

Не следует ожидать, что пользователи будут подписывать свои реальные имя и фамилию, так как всегда найдется какая-то “Пусичка” или “Вася Пупкин”, которые могут подпортить вам красивый список пользователей. При создании приложения сразу же продумывайте вариант именования пользователей внутри системы, без привязки к тому бреду, что они пишут у себя в телеграм)

Данные о сообщении

Часто полезно знать айди сообщения, чтобы потом можно было его, например, удалить.

$a_mess_id = $this->api->message['message_id']; // уникальный айди сообщения в данном чате
$this->api->deleteMessage( $a_mess_id ); // так можно удалить сообщение, зная его айди

Где может понадобиться удалять сообщения? Например, если вы пишите диалоговый интерфейс с ботом, который подразумевает постоянную смену сообщений на экране без накопления истории сообщений. Показали – пользователь что-то выбрал – удалили. Удобно.

К слову сказать этот идентификатор – это по своей сути порядковый номер сообщения, который постоянно увеличивается. Поэтому можно удалять и несколько сообщений “вглубь” чата:

$a_mess_id = $this->api->message['message_id'];
$this->api->deleteMessage( $a_mess_id );
$this->api->deleteMessage( $a_mess_id - 1);
$this->api->deleteMessage( $a_mess_id - 2);
$this->api->deleteMessage( $a_mess_id - 3);

В примере выше удалятся не только текущее сообщение но и три сообщения “выше” в чате, у которых идентификатор меньше на столько, сколько нам надо.

Итоги

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

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

Дальше осталось почитать официальную документацию телеграм и осмыслить все то, что вы уже умеете.

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