Содержание

Bot API: часто задаваемые вопросы

Внимание!
Если вы незнакомы с ботами в Telegram, рекомендуется сначала прочитать ознакомительную статью.
Также, возможно, вас заинтересует описание Bot API.
Общие вопросы
Получение обновлений
Обработка фото и видео
Массовая рассылка

Общие вопросы

Как я могу создать бота?

Создание бота для Telegram крайне простое, однако, вам понадобится кое-какой опыт в программировании. Для работы вашего бота вам необходимо осуществить первоначальную настройку через робота @BotFather, а затем подключить его к вашему серверу через API.

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

Можно посмотреть примеры кода?

Вот два бота-образца, написанных на PHP:

  • Hello Bot: демонстрация основных возможностей Bot API.
  • Simple Poll bot: более сложный бот, поддерживающий оба способа получения обновлений (long-polling и вебхуки).
Многие разработчики создают своих ботов с открытым исходным кодом.
Мы собираем их на специальной странице »

Добавьте в ботов X!

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

Если у вас есть мысли по этому поводу, вы можете высказать их пользователю @BotSupport (на английском).

Какие сообщения может получать мой бот?

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

  • Сообщение было ответом боту или нажатием на его клавиатуру;
  • В сообщении есть @упоминание бота по его имени пользователя;
  • В сообщении содержится общая команда (напр., /start) или команда, предназначающаяся вашему боту (напр., /start@YourBot);
  • Сообщение является служебным (о смене названия группы, выходе кого-либо из чата, и т. д.).

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

  • Сообщений от других ботов;
  • Команд для других ботов (напр., /start@NotYourBot);
  • Ответов на сообщения от других ботов за исключением случаев, когда в сообщении содержится @упоминание вашего бота.

Почему мой бот не видит сообщений от других ботов?

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

Получение обновлений

Как можно получать обновления?

На текущий момент доступно два способа. Вы можете использовать либо long polling, либо вебхуки. Обратите внимание: если вы используете вебхуки, метод getUpdates работать не будет.

Принципиальное отличие: при long polling вашему приложению самому нужно запрашивать обновления у API, а используя вебхуки — сервера Telegram будут отправлять на ваш сервер каждое обновление с помощью HTTPS POST-запроса.

Важно:
Вебхуки могут работать только через HTTPS, допустимо использование самозаверенного сертификата. Доступные порты: 443, 80, 88, 8443.
Совет:
В «боевых» условиях рекомендуется использовать вебхуки из-за большей надёжности.

Опрос всегда выдаёт один и тот же результат

Метод getUpdates выдаёт 100 последних неподтверждённых обновлений. Чтобы подтвердить обновление, используйте параметр offset при вызове getUpdates вот так:

offset = update_id последнего обработанного обновления + 1

Все обновления с update_id меньшим или равным offset будут отмечены как подтверждённые и не будут больше возвращаться сервером.

Проблема с вебхуками

Если вы успешно задали адрес вебхука, но не получаете обновлений, убедитесь, что:

  • SSL-сертификат вашего вебхука валиден и корректен.
  • При использовании самозаверенного сертификата, вы передаёте его публичный ключ в поле certificate метода setWebhook. Необходимо загружать InputFile, отправка строки не сработает.
  • Ваш вебхук работает на одном из допустимых портов: 443, 80, 88 или 8443.

Проблема с самозаверенным сертификатом

Ознакомьтесь с инструкцией по созданию сертификатов. Если после прочтения у вас остались вопросы, напишите пользователю @botsupport.

Как мне убедиться, что запросы идут с серверов Telegram?

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

https://example.com/your_token

Так как никто посторонний не знает вашего токена, запросы на этот адрес смогут отсылать только сервера Telegram.

Как делать запросы в HTTP-ответах к обновлениям?

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

Всякий раз при получении обновления на вебхук, у вас есть два варианта:

1. Отправить POST-запрос к https://api.telegram.org/bot<token>/МЕТОД

Прямой запрос

2. Ответить напрямую, указав метод в виде JSON в HTTP-ответе:

Ответ в запросе
Пример реализации этой возможности на PHP можно посмотреть тут:
https://github.com/telegram-cis/hello-bot.

Обработка медиафайлов

Как скачивать файлы?

Для этого используйте метод getFile.

Этот метод работает только для файлов объёмом до 20 МБ.

Как закачать большой файл?

На текущий момент боты могут отправлять файлы объёмом до 50 МБ, так что крупные файлы отправить не получится. Возможно, это ограничение будет снято в будущем.

Как долго хранится file_id у файлов?

file_id у отправленных вашим ботом файлов будут удалены после отправления нескольких тысяч файлов.

Для принятых файлов file_id можно считать вечным и неизменным.

Массовая рассылка

Каков лимит сообщений в секунду?

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

При рассылке уведомлений нескольким пользователям, API не позволит отправлять более 30 сообщений в секунду. Для преодоления этого лимита вам необходимо разбить отправку на части с большим интервалом между собой (около 8-12 часов).

При работе с группой ограничение установлено на 20 сообщений в минуту.

Как получить список всех подписчиков моего бота?

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

Чтобы максимально эффективно рассылать сообщения, вам необходимо разбивать отправку на несколько частей с интервалом в 8-12 часов. Также недопустимо отправление более 30 сообщений разным пользователям в секунду — иначе вы будете получать ошибку 429.

См. также: Каков лимит сообщений в секунду?

Комментарии