Добро пожаловать в мир Telegram-ботов! Оригинал документации уже много лет помогает разработчикам создавать умных помощников. Здесь вы найдете адаптированный перевод с акцентом на практические кейсы — идеально для старта или углубленной работы с Bot API. Не забудьте заглянуть в Руководство по Bot API для полного погружения!
Если вы новичок в Telegram-ботах, мы рекомендуем сначала ознакомиться с Введением в ботов.
Вам также может пригодиться Руководство по Bot API.
Общие вопросы
Как создать бота?
Создание ботов для Telegram очень простое, но вам понадобятся хотя бы некоторые навыки программирования. Для того чтобы бот работал, создайте аккаунт бота с помощью @BotFather, а затем подключите его к вашему серверу через наше API.
К сожалению, нет готовых решений для создания рабочего бота, если вы не являетесь разработчиком. Но мы уверены, что вскоре вы найдете множество ботов, созданных другими пользователями, с которыми можно поиграть.
Я разработчик. Где я могу найти примеры?
Вот два примера ботов, оба написаны на PHP:
- Hello Bot демонстрирует основы Telegram bot API.
- Simple Poll bot является более полным примером, он поддерживает как long-polling, так и Webhooks для обновлений.
Многие члены нашего сообщества создают ботов и публикуют исходные коды.
Мы собираем их на этой странице »
Напишите нам в @BotSupport, если вы создали бота и хотите поделиться им с другими.
Добавите ли вы X в Bot API?
Bot API все еще довольно молод. Существует множество потенциальных функций, которые можно рассмотреть и реализовать. Мы будем изучать, что люди делают со своими ботами, чтобы понять, какие направления будут наиболее важными для платформы.
Все разработчики ботов могут делиться идеями для нашего Bot API через наш @BotSupport аккаунт.
Какие сообщения будет получать мой бот?
1. Все боты, независимо от настроек, будут получать:
- Все служебные сообщения.
- Все сообщения из личных чатов с пользователями.
- Все сообщения из каналов, в которых они являются участниками.
2. Администраторы ботов и боты с отключенным режимом конфиденциальности будут получать все сообщения, кроме сообщений, отправленных другими ботами.
3. Боты с включенным режимом конфиденциальности будут получать:
- Команды, явно предназначенные для них (например, /command@this_bot).
- Общие команды от пользователей (например, /start) если бот был последним ботом, отправившим сообщение в группу.
- Сообщения, отправленные через этого бота.
- Ответы на любые сообщения, явно или неявно предназначенные для этого бота.
Обратите внимание, что каждое конкретное сообщение может быть доступно только одному боту с включенным режимом конфиденциальности в одно и то же время, т.е. ответ на бота A, содержащий явную команду для бота B или отправленный через бота C, будет доступен только боту A. Ответы имеют наивысший приоритет.
Почему мой бот не видит сообщения от других ботов?
Боты, общающиеся друг с другом, могут застрять в нежелательных циклах. Чтобы избежать этого, мы решили, что боты не смогут видеть сообщения от других ботов, независимо от режима.
Получение обновлений
Как я могу получать обновления?
В настоящее время существует два способа получения обновлений. Вы можете использовать долгий опрос или Webhooks. Обратите внимание, что невозможно получать обновления через долгий опрос, если установлен исходящий Webhook.
Долгий опрос возвращает одни и те же обновления снова и снова!
Метод getUpdates возвращает первые 100 неподтвержденных обновлений. Чтобы подтвердить обновление, используйте параметр offset при вызове getUpdates следующим образом:
offset = update_id последнего обработанного обновления + 1Все обновления с update_id, меньшими или равными offset, будут помечены как подтвержденные на сервере и больше не будут возвращаться.
У меня проблемы с Webhooks.
Если вы успешно настроили свой вебхук, но не получаете обновления, пожалуйста, помните:
- Вам нужен действительный SSL-сертификат для работы вебхуков.
- Чтобы использовать самоподписанный сертификат, вам необходимо загрузить свой публичный ключ с помощью параметра certificate в setWebhook. Пожалуйста, загружайте как InputFile, отправка строки не сработает.
- Порты, которые в настоящее время поддерживаются для Webhooks: 443, 80, 88, 8443.
- Wildcard-сертификаты могут не поддерживаться.
- Перенаправления не поддерживаются.
- CN должен точно соответствовать вашему домену.
Пожалуйста, ознакомьтесь с новым РУКОВОДСТВОМ ПО WEBHOOK, чтобы узнать все, что нужно знать о вебхуках!
У меня проблемы с моим самоподписанным сертификатом!
Пожалуйста, ознакомьтесь с нашим руководством по самоподписанным сертификатам, которое мы подготовили специально для вас. Если вы уже прочитали его и у вас все еще есть вопрос, напишите нам в botsupport.
Как я могу убедиться, что запросы Webhook приходят от Telegram?
Если вы хотите убедиться, что запрос Webhook приходит от Telegram, мы рекомендуем использовать секретный путь в URL, который вы нам предоставляете, например www.example.com/your_token. Поскольку никто другой не знает токен вашего бота, вы можете быть уверены, что это мы.
Как я могу делать запросы в ответ на обновления?
Это возможно, если вы используете вебхуки. Плюс в том, что вам нужно меньше запросов, минус — в этом случае невозможно узнать, был ли такой запрос успешным, или получить его результат.
Когда вы получаете обновление вебхука, у вас есть два варианта:
1. Выполните POST на https://api.telegram.org/bot<token>/method
2. Ответьте напрямую и укажите метод в JSON полезной нагрузке в ответе
Вы также можете ознакомиться с нашим примером HelloBot, он предлагает реализацию на PHP.
Обработка медиафайлов
Как мне скачать файлы?
Используйте метод getFile. Обратите внимание, что это будет работать только с файлами размером до 20 МБ.
Как мне загрузить большой файл?
Боты в настоящее время могут отправлять файлы любого типа размером до 50 МБ, поэтому да, очень большие файлы пока не будут работать. Извините. Этот лимит может быть изменен в будущем.
Могу ли я рассчитывать на то, что file_ids будут постоянными?
Да, file_ids можно считать постоянными.
Рассылка пользователям
Мой бот достигает лимитов, как мне этого избежать?
По умолчанию боты могут отправлять сообщения своим пользователям бесплатно – но имеют ограничения на количество сообщений, которые они могут отправить за один интервал:
- В одном чате старайтесь не отправлять более одного сообщения в секунду. Мы можем разрешить короткие всплески, превышающие этот лимит, но в конечном итоге вы начнете получать ошибки 429.
- В группе боты не могут отправлять более 20 сообщений в минуту.
- Для массовых уведомлений боты не могут отправлять более 30 сообщений в секунду, если они не включат платные рассылки для увеличения лимита.
Как я могу отправить сообщение всем подписчикам моего бота сразу?
Включение платных трансляций в @BotFather позволяет боту транслировать до 1000 сообщений в секунду. Каждое сообщение, отправленное сверх бесплатного лимита в 30 сообщений в секунду, будет стоить 0.1 Stars за сообщение, оплачиваемое с помощью Telegram Stars из баланса бота. Чтобы включить эту функцию, у бота должно быть как минимум 100,000 Stars на балансе и как минимум 100,000 активных пользователей в месяц.
Боты с увеличенными лимитами оплачиваются только за сообщения, которые были успешно транслированы.
Если вы не хотите включать платные трансляции, подумайте о том, чтобы распределить их на более длительные интервалы (например, 8-12 часов), чтобы избежать превышения лимита. API не позволит отправлять массовые уведомления более чем ~30 пользователям в секунду – если вы превысите этот лимит, вы начнете получать ошибки 429.
Если у вас есть вопросы, на которые не ответили на этой странице, напишите нам в @BotSupport в Telegram.
Мы приветствуем любые предложения по платформе ботов и API.