├── CUSTOMER.md ├── DEVELOPER.md ├── README.md └── referral system example ├── README.md ├── main.py └── models.py /CUSTOMER.md: -------------------------------------------------------------------------------- 1 | ## Главное правило звучит так: **Без ТЗ результат _хз_** 2 | 3 | Вы можете разместить заказ в канале [@tgram_jobs](https://t.me/tgram_jobs) через бота [@thordersbot](https://t.me/thordersbot). Заказ подвергнется модерации и будет опубликован или удалён. Вам сообщат причину в случае удаления. 4 | -------------------------------------------------------------------------------- /DEVELOPER.md: -------------------------------------------------------------------------------- 1 | ## Telegram Bot API 2 | Боты — специальные аккаунты в Telegram, созданные для того, чтобы автоматически обрабатывать и отправлять сообщения. 3 | Пользователи могут взаимодействовать с ботами при помощи сообщений, отправляемых через обычные или групповые чаты. 4 | Логика бота контролируется при помощи HTTPS запросов к [API для ботов](https://api.telegram.org) 5 | 6 | **НЕОФИЦИАЛЬНЫЙ** вольный перевод о том, что из себя представляют боты https://tlgrm.ru/docs/bots 7 | 8 | ### Полезные ссылки: 9 | 10 | - Список интересных групп/каналов, а также список чатов для программистов: https://github.com/goq/telegram-list 11 | 12 | - Заказать бота / стать исполнителем: https://t.me/tgram_jobs 13 | 14 | - Официальная актуальная английская документация по методам API: https://core.telegram.org/bots/api 15 | 16 | (плохо с английским - идём за переводчиком http://translate.google.com) 17 | 18 | - Текстовые уроки "Пишем бота для Telegram на языке Python" с использованием библиотеки [pyTelegramBotAPI](https://github.com/eternnoir/pyTelegramBotAPI): 19 | 20 | http://mastergroosha.github.io/telegram-tutorial/ 21 | 22 | - Текстовые уроки "Асинхронный Telegram бот на языке Python 3" с использованием библиотеки [aiogram](https://github.com/aiogram/aiogram): 23 | 24 | https://surik00.gitbooks.io/aiogram-lessons/content/ 25 | 26 | - [Реализация реферальной системы на Python с pyTelegramBotApi.](referral%20system%20example/) 27 | 28 | - Деплой бота на различных бесплатных серверах: https://github.com/deploy-your-bot-everywhere/deploy-your-bot-everywhere 29 | 30 | - Видеоуроки "Разработка Телеграм бота на Python" с использованием библиотеки [aiogram](https://github.com/aiogram/aiogram): 31 | 32 | https://www.youtube.com/playlist?list=PLwVBSkoL97Q3phZRyInbM4lShvS1cBl-U 33 | 34 | ### Список популярных библиотек: 35 | + Python 36 | - [pyTelegramBotAPI](https://github.com/eternnoir/pyTelegramBotAPI) - отлично подходит для начинающих, желающих понять основы работы с Bot API. Имеет подробную документацию (на английском языке) и обширное комьюнити. 37 | - [aiogram](https://github.com/aiogram/aiogram) - продвинутая библиотека для создания высокопроизводительных ботов. Библиотека постоянно обновляется и имеет крутые фишки, например [FSM](https://ru.wikipedia.org/wiki/Конечный_автомат), установку стандартного типа разметки и прочие мелочи, полезные при разработке. Комьюнити библиотеки на данный момент небольшое. 38 | - [python-telegram-bot](https://github.com/python-telegram-bot/python-telegram-bot) 39 | - [twx.botapi](https://github.com/datamachine/twx.botapi) 40 | - [Telepot](https://github.com/nickoala/telepot) 41 | - [Telegram Bot Service](https://github.com/sourcesimian/txTelegramBot) 42 | - [telebot](https://github.com/yukuku/telebot) 43 | - [Keyboa](https://github.com/torrua/keyboa) - дополнение к библиотеке [pyTelegramBotAPI](https://github.com/eternnoir/pyTelegramBotAPI), позволяющее быстро создавать inline-клавиатуры любой сложности, объединять несколько клавиатур в одну или генерировать их динамически. Имеет подробное описание с примерами. 44 | 45 | + JavaScript 46 | - [telegraf](https://github.com/telegraf/telegraf) 47 | - [node-telegram-bot-api](https://github.com/yagop/node-telegram-bot-api) 48 | - [urban-bot](https://github.com/urban-bot/urban-bot) - написание бота через React.js компоненты. 49 | + Java 50 | - [TelegramBots](https://github.com/rubenlagus/TelegramBots) 51 | - [Java Telegram Bot API](https://github.com/pengrad/java-telegram-bot-api) - библиотека, которая регулярно обновляется и имеет приятные дополнения, например поддержку шифрования для Telegram Passport. Автор призывает подключаться к разработке, отвечает на все вопросы и пулл-реквесты. 52 | + Kotlin 53 | - [TelegramBotAPI](https://github.com/InsanusMokrassar/TelegramBotAPI) - не самая простая библиотека, использует объектно-ориентированный подход 54 | + PHP 55 | - [PHP Telegram Bot](https://github.com/php-telegram-bot/core) 56 | + C# 57 | - [Telegram.bot](https://github.com/TelegramBots/Telegram.Bot) 58 | + Ruby 59 | - [TelegramBot](https://github.com/eljojo/telegram_bot) 60 | + Go 61 | - [tgbotapi](https://github.com/go-telegram-bot-api/telegram-bot-api) 62 | + Lua 63 | - [lua-telegram-bot](https://github.com/cosmonawt/lua-telegram-bot) 64 | + Haskell 65 | - [haskell-telegram-api](https://github.com/klappvisor/haskell-telegram-api) 66 | + Rust 67 | - [teloxide](https://github.com/teloxide/teloxide) 68 | - [carapax](https://github.com/tg-rs/carapax) 69 | + Nim 70 | - [telebot.nim](https://github.com/ba0f3/telebot.nim) 71 | 72 | 73 | --- 74 | 75 | ## ЧаВо 76 | 77 | **Q:** Могу ли я посмотреть список всех пользователей канала? 78 | 79 | **A:** Нет, если пользователей более 200 80 | 81 | _ 82 | 83 | **Q:** Где захостить бота? 84 | 85 | **A:** Бесплатно можно на Heroku, есть [инструкция](https://github.com/Kylmakalle/heroku-telegram-bot). 86 | Более удобный способ - купить VPS \(Virtual Private Server\). Это виртуальная машина, на которой можно запустить бота ровно так же, как и на своём компьтере. 87 | 88 | Список некоторых хостинг-провайдеров: 89 | - [OVH](https://www.ovh.ie/) 90 | - [DigitalOcean](https://www.digitalocean.com/) 91 | - [Aruba](https://www.arubacloud.com/) 92 | - [Vultr](https://www.vultr.com/) 93 | - [Hetzner](https://www.hetzner.com/cloud) 94 | 95 | Таблица сравнения минимальных тарифов 96 | 97 | _В 202X году каждый адекватный провайдер имеет бесплатный внешний ipv4 адрес и SSD диски вместо HDD._ Бесплатные купоны и кредиты позволяют сильно сэкономить на сервере. Например, купоны из [Github Student Pack](https://education.github.com/pack) позволяют получить $50 на DigitalOcean, а это почти год бесплатного сервера. Гугл в помощь! 98 | 99 | | | OVH (Starter) | DigitalOcean (Standard) | Aruba (Small) | Vultr | Hetzner (CX11) | 100 | |---------------------------|----------------|-------------------------|-------------------------------------------------------------------------------------------------------------------|--------------------|----------------------------------------------------------------------------------------------------| 101 | | Цена, в Месяц | $3.50 | (~$6) $5 + НДС | **(~$3) €2.79** | (~$6) $5 + НДС | (~$3.25) €2.99 | 102 | | Бесплатные купоны/кредиты | ? | **Есть** | ? | **Есть** | ? | 103 | | Процессор, ядра | 1 | 1 | 1 | 1 | 1 | 104 | | ОЗУ, Гб | **2** | 1 | 1 | 1 | **2** | 105 | | ПЗУ, Гб | 20 | **25** | 20 | **25** | 20 | 106 | | Трафик, Гб | **Безлимитно** | 1000 | 2000 | 1000 | **20 000** | 107 | | Ширина канала, Mbps | 100 | 1000 | 1000 | 1000 | 1000 | 108 | | При превышении трафика | - | $10/Тб Автобиллинг | (?) [Ручной апгрейд тарифа](https://kb.arubacloud.com/en/computing/use-and-technology/bandwidth-and-traffic.aspx) | $10/Тб Автобиллинг | **€1/Тб Автобиллинг** ИЛИ [Лимит скорости 10 Mbit/s](https://wiki.hetzner.de/index.php/Traffic/ru) | 109 | 110 | Чтобы контрибьютить в таблицу, воспользуйтесь [Сервисом](https://www.tablesgenerator.com/markdown_tables), не мучайте себя! 111 | 112 | Чуть более сложный, но интересный вариант — запустить бота на servlerless стеке. Например, в AWS каждый аккаут [получает](https://aws.amazon.com/free) бесплатно NoSQL БД на 25 GB и 1M API-вызовов в месяц, чего вполне хватит для нескольких несложных ботов. 113 | 114 | **Q:** Как сделать, чтобы бот _ждал_ от пользователя следующее сообщение? 115 | 116 | **A:** Используйте FSM (машины состояний). В некоторых библиотеках эта возможность уже встроена: [пример aiogram](https://github.com/aiogram/aiogram/blob/dfcc59d349e5387ff59ead32bd8f20d4ae064568/examples/finite_state_machine_example.py) 117 | 118 | _ 119 | 120 | **Q:** Как хранить данные от пользователей? 121 | 122 | **A:** Для долгосрочного хранения есть базы данных. Скорее всего, вашему небольшому проекту хватит мощностей SQLite. Если же проект подразумевает подключение к БД с разных ресурсов - взгляните на MySQL и PostgreSQL. 123 | 124 | 125 | --- 126 | 127 | 128 | ### Особенности работы с Bot API 129 | 130 | ##### В этом разделе описаны различные хитрости и неочевидные способы работы с Bot API, которые помогут вам упростить разработку или восполнить какое-либо ограничение в API. 131 | 132 | #### Отправка Фото с большой подписью 133 | 134 | Ранее этот способ использовался из-за ограничения подписи к фото в 200 символов, на данный момент лимит составляет 1024 символа. Если вам этого всё ещё мало или хотите разместить фото под текстом, то вы можете воспользоваться _предпросмотром_ ссылки. Делается это путем гиперссылки, где в качестве текста ссылки будет скрытый символ (`parse_mode=HTML`): 135 | ```HTML 136 | "​​​ 137 | Lorem ipsum dolor sit amet..." 138 | ``` 139 | ![](http://telegra.ph/file/ef107beda6880867f0348.png) 140 | 141 | #### Бесплатный хостинг картинок 142 | POST HTTP запрос `http://telegra.ph/upload` 143 | 144 | Поддерживаемые типы медиафайлов: 145 | `image/gif, image/jpeg, image/jpg, image/png, video/mp4, video/ogg, video/mpeg` 146 | 147 | Максимальный размер файла: 5 242 880 байт/5 МБайт 148 | 149 | **Примеры:** 150 | - Python 151 | 152 | ```python 153 | import requests 154 | 155 | 156 | with open('/Users/python273/Desktop/123345.jpeg', 'rb') as f: 157 | print( 158 | requests.post( 159 | 'https://telegra.ph/upload', 160 | files={'file': ('file', f, 'image/jpeg')} 161 | ).json() 162 | ) 163 | ``` 164 | 165 | #### Убираем часики на inline-кнопках 166 | ![](http://telegra.ph/file/b61e25a0a3f81f157eecf.png) 167 | 168 | Причина возникновения этих _часиков_ - ожидание Телеграмом ответа от бота после нажатия пользователем на кнопку. Чтобы эти часики не зависали, после обработки нажатия нужно вызвать метод [answerCallbackQuery](https://core.telegram.org/bots/api#answercallbackquery) 169 | 170 | 171 | --- 172 | 173 | ### Лимиты Telegram Bot API 174 | 175 | + Сообщения: 176 | - При отправке сообщений внутри определенного чата избегайте отправки более одного сообщения в секунду. Telegram может разрешить короткие всплески, которые превышают этот предел, но в итоге вы начнете получать 429 ошибку. 177 | 178 | - Если вы отправляете массовые уведомления нескольким пользователям, API не будет разрешать более 30 сообщений в секунду или около того. Рассмотрите возможность распространения уведомлений на большие интервалы в 8-12 часов для достижения наилучших результатов. 179 | 180 | - Ваш бот сможет редактировать посты других администраторов на каналах старше 48 часов только используя метод **editMessageReplyMarkup**, а также сможет их удалить, но другие методы изменения сообщений будут недоступны 181 | 182 | - Также обратите внимание, что ваш бот не сможет отправлять более 20 сообщений в минуту в одну группу. 183 | + Файлы: 184 | - Максимальный размер файла для скачивания 20 MB. 185 | 186 | - Максимальный размер файла для отправки 50 MB. 187 | + Инлайн-клавиатура (InlineKeyboardMarkup): 188 | - Максимальное число кнопок в строке - 8. 189 | 190 | - Максимальное число кнопок всего - 100. 191 | + Кнопка инлайн-клавиатуры (InlineKeyboardButton): 192 | - Максимальная длина колбека (callback_data) - 64 байта. 193 | 194 | --- 195 | 196 | 197 | ## Telegram client API (он же MTProto, он же tgcli) 198 | Клиентское API телеграма - это API позволяющее вам выполнять автоматизированные действия от лица клиента. 199 | Иными словами, всё, что может делать пользователь в телеграме, можно запрограммировать на tgcli \(получить всю историю сообщений в группе, 200 | получить список всех пользователей группы, сделать поиск в группе по словам, взаимодействовать с ботами и [т.д и т.п](http://stek29.rocks/tl-schema/latest/)\). 201 | Так как Telegram client api предполагает написание скриптов на tl \(поверьте, вы не хотите на нём [писать](https://tlgrm.ru/docs/mtproto/TL)\), то получили распространение обёртки над tgcli для разных языков. 202 | 203 | 204 | ### Список популярных клиентских библиотек: 205 | + Python: 206 | - [Telethon](https://github.com/LonamiWebs/Telethon) 207 | - [pyrogram](https://github.com/pyrogram/pyrogram) 208 | + JavaScript: 209 | - [telegram-mtproto](https://github.com/zerobias/telegram-mtproto) 210 | + Rust: 211 | - [Vail](https://github.com/JuanPotato/Vail) 212 | - [mtproto-rs](https://github.com/Connicpu/mtproto-rs) 213 | + PHP: 214 | - [MadelineProto](https://github.com/danog/MadelineProto) 215 | + Kotlin: 216 | - [kotlogram](https://github.com/badoualy/kotlogram) 217 | + C: 218 | - [tg](https://github.com/vysheng/tg) 219 | - [tdcli](https://bitbucket.org/vysheng/tdcli) 220 | + Elixir: 221 | - [1664390](https://gitlab.com/snippets/1664390) 222 | - [telegram-mt-elixir](https://github.com/Fnux/telegram-mt-elixir) 223 | - [telegram-tl-elixir](https://github.com/Fnux/telegram-tl-elixir) 224 | + C#: 225 | - [TLSharp](https://github.com/sochix/TLSharp) 226 | + Go: 227 | - [mtproto](https://github.com/sdidyk/mtproto) 228 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # FAQ 2 | Русскоязычный краудсорсинговый проект о разработке Telegram ботов 3 | 4 | 5 | ## Я заказчик (и я хочу чтобы мне сделали бота/соориентировали по стоимости и т. п.) 6 | 7 | [FAQ для заказчиков](CUSTOMER.md) 8 | 9 | ## Я разработчик (и мне нужна помощь в разработке бота/информация по лимитам/документации и т. п.) 10 | [FAQ для разработчиков](DEVELOPER.md) 11 | 12 | ## Содержание: 13 | 14 | - ### [Полезные ссылки](https://github.com/Telegram-Bot-FAQ/FAQ/blob/master/DEVELOPER.md#%D0%BF%D0%BE%D0%BB%D0%B5%D0%B7%D0%BD%D1%8B%D0%B5-%D1%81%D1%81%D1%8B%D0%BB%D0%BA%D0%B8) 15 | 16 | - ### [Список популярных библиотек](https://github.com/Telegram-Bot-FAQ/FAQ/blob/master/DEVELOPER.md#%D1%81%D0%BF%D0%B8%D1%81%D0%BE%D0%BA-%D0%BF%D0%BE%D0%BF%D1%83%D0%BB%D1%8F%D1%80%D0%BD%D1%8B%D1%85-%D0%B1%D0%B8%D0%B1%D0%BB%D0%B8%D0%BE%D1%82%D0%B5%D0%BA) 17 | 18 | - ### [ЧаВо](https://github.com/Telegram-Bot-FAQ/FAQ/blob/master/DEVELOPER.md#%D1%87%D0%B0%D0%B2%D0%BE) 19 | 20 | + ### [Особенности работы с Bot API](https://github.com/Telegram-Bot-FAQ/FAQ/blob/master/DEVELOPER.md#%D0%BE%D1%81%D0%BE%D0%B1%D0%B5%D0%BD%D0%BD%D0%BE%D1%81%D1%82%D0%B8-%D1%80%D0%B0%D0%B1%D0%BE%D1%82%D1%8B-%D1%81-bot-api) 21 | - #### [Отправка Фото с большой подписью](https://github.com/Telegram-Bot-FAQ/FAQ/blob/master/DEVELOPER.md#%D0%BE%D1%82%D0%BF%D1%80%D0%B0%D0%B2%D0%BA%D0%B0-%D1%84%D0%BE%D1%82%D0%BE-%D1%81-%D0%B1%D0%BE%D0%BB%D1%8C%D1%88%D0%BE%D0%B9-%D0%BF%D0%BE%D0%B4%D0%BF%D0%B8%D1%81%D1%8C%D1%8E) 22 | - #### [Бесплатный хостинг картинок](https://github.com/Telegram-Bot-FAQ/FAQ/blob/master/DEVELOPER.md#%D0%B1%D0%B5%D1%81%D0%BF%D0%BB%D0%B0%D1%82%D0%BD%D1%8B%D0%B9-%D1%85%D0%BE%D1%81%D1%82%D0%B8%D0%BD%D0%B3-%D0%BA%D0%B0%D1%80%D1%82%D0%B8%D0%BD%D0%BE%D0%BA) 23 | 24 | - ### [Лимиты Telegram Bot API](https://github.com/Telegram-Bot-FAQ/FAQ/blob/master/DEVELOPER.md#%D0%BB%D0%B8%D0%BC%D0%B8%D1%82%D1%8B-telegram-bot-api) 25 | 26 | + ### [Telegram client API (он же MTProto, он же tgcli)](https://github.com/Telegram-Bot-FAQ/FAQ/blob/master/DEVELOPER.md#telegram-client-api-%D0%BE%D0%BD-%D0%B6%D0%B5-mtproto-%D0%BE%D0%BD-%D0%B6%D0%B5-tgcli) 27 | - #### [Список популярных клиентских библиотек](https://github.com/Telegram-Bot-FAQ/FAQ/blob/master/DEVELOPER.md#%D1%81%D0%BF%D0%B8%D1%81%D0%BE%D0%BA-%D0%BF%D0%BE%D0%BF%D1%83%D0%BB%D1%8F%D1%80%D0%BD%D1%8B%D1%85-%D0%BA%D0%BB%D0%B8%D0%B5%D0%BD%D1%82%D1%81%D0%BA%D0%B8%D1%85-%D0%B1%D0%B8%D0%B1%D0%BB%D0%B8%D0%BE%D1%82%D0%B5%D0%BA) 28 | 29 | -------------------------------------------------------------------------------- /referral system example/README.md: -------------------------------------------------------------------------------- 1 | ### referral system example 2 | -------------------------------------------------------------------------------- /referral system example/main.py: -------------------------------------------------------------------------------- 1 | from models import * 2 | from telebot import TeleBot 3 | 4 | bot = TeleBot('') 5 | # заготовка для реферальной ссылки 6 | ref_link = 'https://telegram.me/{}?start={}' 7 | 8 | 9 | @bot.message_handler(commands=['start']) 10 | def start(message): 11 | user_id = message.chat.id 12 | # в случае с реферальными системами, нужно передать параметр 13 | # к команде /start=PARAM. Этот переметр будет передан боту 14 | # при вводе команды, например /start=1337 15 | # где 1337 -- ID пользователя который отправил приглашение 16 | # боту будет передано /start 1337 17 | # именно по этому мы разбиваем сообщение по пробелу 18 | # и смотрим есть ли там этот параметр 19 | splited = message.text.split() 20 | # проверяем наличие пользователя в базе данных 21 | if not Users.user_exists(user_id): 22 | # если его нет -- создаём 23 | Users.create_user(user_id) 24 | # проверяем перешел ли пользователь по реферальной ссылке 25 | if len(splited) == 2: 26 | # увеличиваем счетчик тому кто пригласил 27 | Users.increase_ref_count(splited[1]) 28 | bot.reply_to(message, text='hello') 29 | 30 | 31 | @bot.message_handler(commands=['get_my_link']) 32 | def get_my_ref(message): 33 | # получаем username нашего бота и отпрявляем ссылку 34 | bot_name = bot.get_me().username 35 | bot.reply_to(message, text=ref_link.format(bot_name, message.chat.id)) 36 | 37 | 38 | @bot.message_handler(commands=['ref_count']) 39 | def get_my_refs(message): 40 | # запрашиваем кол-во рефералов пользователя и отправляем ему 41 | count = Users.get_ref_count(message.chat.id) 42 | bot.reply_to(message, text=f'Count: {count}') 43 | 44 | 45 | if __name__ == '__main__': 46 | bot.polling(none_stop=True) -------------------------------------------------------------------------------- /referral system example/models.py: -------------------------------------------------------------------------------- 1 | from peewee import * 2 | 3 | db = SqliteDatabase('users.db') 4 | 5 | 6 | class BaseModel(Model): 7 | class Meta: 8 | database = db 9 | 10 | 11 | class Users(BaseModel): 12 | user_id = IntegerField(unique=True) 13 | ref = IntegerField(default=0) 14 | 15 | @classmethod 16 | def get_user(cls, user_id): 17 | return cls.get(user_id = user_id) 18 | 19 | @classmethod 20 | def get_ref_count(cls, user_id): 21 | return cls.get_user(user_id).ref 22 | 23 | @classmethod 24 | def increase_ref_count(cls, user_id): 25 | user = cls.get_user(user_id) 26 | user.ref += 1 27 | user.save() 28 | 29 | @classmethod 30 | def user_exists(cls, user_id): 31 | query = cls().select().where(cls.user_id == user_id) 32 | return query.exists() 33 | 34 | @classmethod 35 | def create_user(cls, user_id): 36 | user, created = cls.get_or_create(user_id=user_id) 37 | 38 | db.create_tables([Users], safe=True) 39 | --------------------------------------------------------------------------------