Регистрируем бот у @BotFather, устанавливаем WebHook

Переходим к сотрудничеству с Telegram. Зарегистрируем своего бота у @BotFather, получим токен для работы с API. Установим WebHook для взаимодействия нашего сервера с Bots API.

Регистрация бота проходит без каких-либо необходимых навыков, путем взаимодействия в "Отцом Ботов" @BotFather.

Последовательность действий для создания любого бота одинаковая:

Открываем @BotFather и запускаем его (Старт/Start). В списке предложенных команд выбираем: /newbot - create a new bot, нажимаем на эту команду, или вводим ее вручную в поле для ввода сообщений.Вам предложат указать как будут звать бота, в дальнейшем название бота можно будет поменять. Вводите название в поле для ввода сообщений.Далее вам предложат указать имя, по которому бот будет доступен для пользователей. Имя пишите, используя латинский алфавит, цифры и нижнее подчеркивание. Еще одно важное условие - имя должно оканчиваться на "bot". Можно также с большой буквы "Bot", или "_bot" или "_Bot".

Если все прошло без замечаний со стороны @BotFather, то по итогу вам выведется на экран Token API, если вы его сразу использовать не будете, то можно его куда-нибудь записать. Также его можно запросить снова если вы его забыли или потеряли. Редактировать бота можно у @BotFather, для этого запросите список ваших ботов /mybots, выберите из списка нужного бота и далее при необходимости вы можете отредактировать его информацию, для этого в меню бота выберите Edit Bot:

Name - Название бота

About - Что умеет этот бот? (выводится при открытии бота по середине экрана)

Description - Описание (доступно при просмотре профиля бота)

Botpic - Картинка - логотип бота

Commands - набор команд (доступно при вызове в диалоге с ботом командой/)

Обратите внимание, что поменять имя бота (@) в настройках возможности нет.

* * *

Методы взаимодействия с Bot API

Есть два взаимоисключающих способа получения обновлений для бота — getUpdates  и webHook. Входящие обновления хранятся на сервере Telegram до тех пор, пока бот не получит их, но они не будут храниться дольше, чем 24 часа.

Независимо от того, какой вариант вы выбрали, вы получите в результате JSON-сериализованные объекты (WIKI).

В случае с getUpdates вам необходимо будет настроить периодическое снятие (например, 1 раз в секунду) с сервера Telegram обновлений (данных полученных от взаимодействия пользователя с ботом - сообщения, картинки ...). 

В случае с webHook обновления вам будут доставляться Bot API по указанному адресу сразу же как только они появятся. Если в ответ API получит статус обработки его запроса не 200 OK, а другой, например, 500 (ошибка сервера) то обновления подвиснут и будут периодически к вам стучатся, и успокоятся только в случае получения в ответ статуса 200 ОК. 

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

* * *

Устанавливаем WebHook

Для установки WebHook есть специальный метод setWebHook. Нам просто необходимо в параметре url передать web-адрес где будут обрабатываться данные отправленные Telegram Bot API. Допустим, что у вас такой же хостинг как у меня, и за работу бота будет отвечать файл index.php, который лежит в директории bots в корне сайта.

public_html
    |__cgi-bin
    |__bots
       |__index.php <-- файл обработчик
    |__index.html

Если структура файлов у вас совпадает, и у вас есть доменное имя, а также установленный SSL сертификат, тогда назначаем webHook используя вот этот URL:

https://api.telegram.org/botВАШ_ТОКЕН/setwebhook?url=https://ВАШ_ДОМЕН/bots/index.php

Вставляем его в адресную строку браузера и переходим, в случае если все прошло без ошибок, на экране у вас выведется вот такая информация:

{"ok":true,"result":true,"description":"Webhook was set"}

Это означает, что все прошло хорошо и WebHook установлен. Теперь можно спокойно начать работать над реализацией бота. 

* * *

Дополнительные настройки WebHook

Также вместе с параметром url в методе setWebHook можно передать:

max_connections - максимальное разрешенное количество одновременных HTTPS-подключений к webhook для доставки обновления, 1-100. По умолчанию 40.

allowed_updates - можно передать типы обновлений, которые будет получать бот. По умолчанию подписка идет на все обновления. 

certificate - сертификат открытого ключа, чтобы проверить используемый корневой сертификат, если у вас например самописный сертификат.

В случае если будет необходимо переназначить webHook, то нужно вызвать метод setWebHook еще раз и указать в качестве значения параметра url новый адрес обработчика данных от Bot API.

Для удаления webHook и перехода к getUpdates используйте метод deleteWebhook, параметры передавать не требуется.

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

Методы вызываются при помощи:

https://api.telegram.org/botВАШ_ТОКЕН/METHOD_NAME