Bot

Начиная.

Этот API-интерфейс протестирован с Python 2.6, Python 2.7, Python 3.4, Pypy и Pypy 3. Существует два способа установки библиотеки:

• Установка с использованием pip (менеджер пакетов Python) *:

$ pip install pyTelegramBotAPI

• Установка из источника (требуется git):

$ git clone https://github.com/eternnoir/pyTelegramBotAPI.git
$ cd pyTelegramBotAPI
$ python setup.py install

Как правило, рекомендуется использовать первый вариант.

* Хотя API готов к работе, он все еще находится в стадии разработки и регулярно обновляется, не забывайте регулярно обновлять его, вызываяpip install pytelegrambotapi --upgrade

Написание вашего первого бота

Предпосылки

Предполагается, что вы получили токен API с @BotFather . Мы назовем этот токен TOKEN. Кроме того, у вас есть базовые знания языка программирования Python и, что более важно, Telegram Bot API .

Простой эхо-бот

Класс TeleBot (определенный в _ init _.py) инкапсулирует все вызовы API в одном классе. Он предоставляет такие функции, как send_xyz( send_messageи send_documentт. Д.) И несколько способов прослушивания входящих сообщений.

Создайте файл с именем echo_bot.py. Затем откройте файл и создайте экземпляр класса TeleBot.

импортный телебот

bot = telebot.TeleBot ( " TOKEN " )

Примечание. Обязательно замените TOKEN на собственный токен API.

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

Давайте определим обработчик сообщений, который обрабатывает входящие /startи /helpкоманды.

@ bot.message_handler ( commands = [ ' start ' , ' help ' ])
 def  send_welcome ( message ):
 bot.reply_to (сообщение « Привет, как дела? » )

Функция, которая оформлена обработчиком сообщения, может иметь произвольное имя, однако она должна иметь только один параметр (сообщение) .

Давайте добавим еще один обработчик:

@ bot.message_handler ( func = lambda  m : True )
 def  echo_all ( message ):
 bot.reply_to (message, message.text)

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

Примечание: все обработчики проверяются в том порядке, в котором они были объявлены

Теперь у нас есть базовый бот, который отвечает на статическое сообщение на команды "/ start" и "/ help" и который повторяет остальные отправленные сообщения. Чтобы запустить бота, добавьте следующее в наш исходный файл:

bot.polling ()

Хорошо, вот и все! Наш исходный файл теперь выглядит так:

импортный телебот

bot = telebot.TeleBot ( " TOKEN " )

@ bot.message_handler ( commands = [ ' start ' , ' help ' ])
 def  send_welcome ( message ):
 bot.reply_to (сообщение « Привет, как дела? » )

@ bot.message_handler ( func = лямбда-  сообщение : True )
 def  echo_all ( message ):
 bot.reply_to (message, message.text)

bot.polling ()

Чтобы запустить бота, просто откройте терминал и войдите, python echo_bot.pyчтобы запустить бота! Проверьте это, отправив команды ('/ start' и '/ help') и произвольные текстовые сообщения.

Общая документация API

Типы

Все типы определены в types.py. Все они полностью соответствуют определению типов Telegram API , за исключением fromполя Message , которое переименовано from_user(потому что fromэто зарезервированный токен Python). Таким образом, к таким атрибутам message_idможно обращаться напрямую message.message_id. Обратите внимание, что это message.chatможет быть либо экземпляр, Userлибо GroupChat(см. Как я могу различить пользователя и групповой чат в message.chat? ).

Объект Message также имеет content_typeатрибут, который определяет тип сообщения. content_typeможет быть одним из следующих строк: text, audio, document, photo, sticker, video, video_note, voice, location, contact, new_chat_members, left_chat_member, new_chat_title, new_chat_photo, delete_chat_photo, group_chat_created, supergroup_chat_created, channel_chat_created, migrate_to_chat_id, migrate_from_chat_id, pinned_message.

Вы можете использовать несколько типов в одной функции. Пример:

content_types=["text", "sticker", "pinned_message", "photo", "audio"]

методы

Все методы API находятся в классе TeleBot. Они переименованы в соответствии с общими соглашениями об именах Python. Например getMe, переименован в get_meи sendMessageк send_message.

Общее использование API

Ниже приведены некоторые общие случаи использования API.

Обработчики сообщений

Обработчик сообщений - это функция, украшенная message_handlerдекоратором экземпляра TeleBot. Обработчики сообщений состоят из одного или нескольких фильтров. Каждый фильтр возвращает True для определенного сообщения, чтобы обработчик сообщений мог обработать это сообщение. Обработчик сообщений объявляется следующим образом (предоставляется botэкземпляр TeleBot):

@ bot.message_handler (фильтры)
 Защита  function_name ( сообщение ):
 bot.reply_to (сообщение « Это обработчик сообщений » )

function_nameне связан никакими ограничениями. Любое имя функции разрешено с обработчиками сообщений. Функция должна принимать не более одного аргумента, который будет сообщением, которое должна обработать функция. filtersсписок ключевых аргументов Фильтр объявляются следующим образом: name=argument. Один обработчик может иметь несколько фильтров. TeleBot поддерживает следующие фильтры:

названиеАргумент (ы)СостояниеContent_Typesсписок строк (по умолчанию ['text'])True если message.content_type находится в списке строк.регулярное выражениерегулярное выражение в виде строкиTrueесли re.search(regexp_arg)возвращается Trueиmessage.content_type == 'text'(см. Регулярные выражения Pythonкомандысписок строкTrueif message.content_type == 'text'и message.textначинается с команды, которая находится в списке строк.FUNCфункция (лямбда или ссылка на функцию)True если лямбда или ссылка на функцию возвращает True

Вот несколько примеров использования фильтров и обработчиков сообщений:

импортный телебот
bot = telebot.TeleBot ( " TOKEN " )

# Обрабатывает все текстовые сообщения, содержащие команды «/ start» или «/ help». 
@ bot.message_handler ( commands = [ ' start ' , ' help ' ])
 def  handle_start_help ( message ):
  pass

# Обрабатывает все отправленные документы и аудиофайлы 
@ bot.message_handler ( content_types = [ ' document ' , ' audio ' ])
 def  handle_docs_audio ( message ):
  pass

# Обрабатывает все текстовые сообщения, которые соответствуют регулярному выражению 
@ bot.message_handler ( regexp = " SOME_REGEXP " )
 def  handle_message ( message ):
  pass

# Обрабатывает все сообщения, для которых лямбда возвращает True 
@ bot.message_handler ( func = lambda  message : message.document.mime_type ==  ' text / plain ' , content_types = [ ' document ' ])
 def  handle_text_doc ( message ):
  pass

# Который также может быть определен как: 
def  test_message ( message ):
  вернуть message.document.mime_type ==  ' text / plain '

@ bot.message_handler ( func = test_message, content_types = [ ' document ' ])
 def  handle_text_doc ( message )
  pass

# Обработчики могут быть сложены, чтобы создать функцию, которая будет вызываться, если любой из message_handler является приемлемым 
# Этот обработчик будет вызываться, если сообщение начинается с '/ hello' ИЛИ ​​- это несколько 
emoji @ bot.message_handler ( commands = [ ' hello ' ])
 @ bot.message_handler ( func = лямбда-  сообщение : msg.text.encode ( " utf-8 " ) ==  SOME_FANCY_EMOJI )
 def  send_something ( message ):
     pass

Важно: все обработчики проверяются в том порядке, в котором они были объявлены

Обработчики обработанных сообщений

То же, что и обработчики сообщений

channel_post_handler

То же, что и обработчики сообщений

edited_channel_post_handler

То же, что и обработчики сообщений

Обработчик запросов обратного вызова

В бот2.0 обновление. Вы можете получить callback_queryв обновлении объекта. В Telebot используется callback_query_handlerдля обработки callback_querys.

@ bot.callback_query_handler ( func = лямбда-  вызов : True )
 def   test_callback ( вызов ):
    logger.info (вызов)

TeleBot

импортный телебот

ЗНАК  =  ' <token_string> ' 
Т.Б. = telebot.TeleBot ( ЗНАК )  # создать новый объект Телеграмма Bot

# После вызова этой функции TeleBot начинает опрашивать серверы Telegram на наличие новых сообщений. 
# - none_stop: True / False (по умолчанию False) - не прекращать опрос при получении ошибки от серверов Telegram 
# - интервал: True / False (по умолчанию False) - интервал между запросами на опрос 
#            Примечание: редактирование этого параметра наносит вред время ответа бота 
# - время ожидания: целое число (по умолчанию 20) - время ожидания в секундах для длинного опроса. 
tb.polling ( none_stop = False , интервал = 0 , тайм-аут = 20 )

# getMe 
user = tb.get_me ()

# setWebhook 
tb.set_webhook ( url = " http://example.com " , Certificate = Open ( ' mycert.pem ' )))
 # unset webhook
tb.remove_webhook ()

# getUpdates 
updates = tb.get_updates ()
updates = tb.get_updates ( 1234 , 100 , 20 ) # get_Updates (смещение, лимит, время ожидания):

# sendMessage
tb.send_message (chatid, текст)

# forwardMessage
tb.forward_message (to_chat_id, from_chat_id, message_id)

# Все функции send_xyz, которые могут принимать файл в качестве аргумента, также могут принимать file_id вместо файла. 
# sendPhoto 
photo =  open ( ' /tmp/photo.png ' , ' rb ' )
tb.send_photo (chat_id, фото)
tb.send_photo (chat_id, " FILEID " )

# sendAudio 
audio =  open ( ' /tmp/audio.mp3 ' , ' rb ' )
tb.send_audio (chat_id, audio)
tb.send_audio (chat_id, " FILEID " )

# # sendAudio с продолжительностью, исполнителем и названием. 
tb.send_audio ( CHAT_ID , file_data, 1 , ' eternnoir ' , ' pyTelegram ' )

# sendVoice 
voice =  open ( ' /tmp/voice.ogg ' , ' rb ' )
tb.send_voice (chat_id, voice)
tb.send_voice (chat_id, " FILEID " )

# sendDocument 
doc =  open ( ' /tmp/file.txt ' , ' rb ' )
tb.send_document (chat_id, doc)
tb.send_document (chat_id, " FILEID " )

# sendSticker 
sti =  open ( ' /tmp/sti.webp ' , ' rb ' )
tb.send_sticker (chat_id, sti)
tb.send_sticker (chat_id, " FILEID " )

# sendVideo 
video =  open ( ' /tmp/video.mp4 ' , ' rb ' )
tb.send_video (chat_id, видео)
tb.send_video (chat_id, " FILEID " )

# sendVideoNote 
videonote =  open ( ' /tmp/videonote.mp4 ' , ' rb ' )
tb.send_video_note (chat_id, videonote)
tb.send_video_note (chat_id, " FILEID " )

# sendLocation
tb.send_location (chat_id, lat, lon)

# sendChatAction 
# action_string может быть одной из следующих строк: «typing», «upload_photo», «record_video», «upload_video», 
# «record_audio», «upload_audio», «upload_document» или «find_location».
tb.send_chat_action (chat_id, action_string)

# getFile 
# Загрузка файла проста 
# Возвращает
 запросы на импорт объекта File
file_info = tb.get_file (file_id)

file  = reports.get ( ' https://api.telegram.org/file/bot {0} / {1} ' .format ( API_TOKEN , file_info.file_path))

Разметка ответа

Все send_xyzфункции TeleBot принимают необязательный reply_markupаргумент. Этот аргумент должен быть экземпляром ReplyKeyboardMarkup, ReplyKeyboardRemoveили ForceReply, которые определены в types.py.

от telebot импортных типов

# Использование класса ReplyKeyboardMarkup 
# Его конструктор может принимать следующие необязательные аргументы: 
# - resize_keyboard: True / False (по умолчанию False) 
# - one_time_keyboard: True / False (по умолчанию False) 
# - выборочный: True / False (по умолчанию False) 
# - row_width: integer (по умолчанию 3) 
# row_width используется в сочетании с функцией add (). 
# Определяет, сколько кнопок помещается в каждом ряду, прежде чем перейти к следующему ряду. 
markup = types.ReplyKeyboardMarkup ( row_width = 2 )
itembtn1 = types.KeyboardButton ( ' a ' )
itembtn2 = types.KeyboardButton ( ' v ' )
itembtn3 = types.KeyboardButton ( ' d ' )
markup.add (itembtn1, itembtn2, itembtn3)
tb.send_message (chat_id, « Выберите одну букву: » , reply_markup = markup)

# или добавьте KeyboardButton по одной строке за раз: 
markup = types.ReplyKeyboardMarkup ()
itembtna = types.KeyboardButton ( ' a ' )
itembtnv = types.KeyboardButton ( ' v ' )
itembtnc = types.KeyboardButton ( ' c ' )
itembtnd = types.KeyboardButton ( ' d ' )
itembtne = types.KeyboardButton ( ' e ' )
markup.row (itembtna, itembtnv)
markup.row (itembtnc, itembtnd, itembtne)
tb.send_message (chat_id, « Выберите одну букву: » , reply_markup = markup)

Последний пример дает этот результат:

# ReplyKeyboardRemove: скрывает ранее отправленный ReplyKeyboardMarkup 
# Принимает необязательный выборочный аргумент (True / False, по умолчанию False) 
markup = types.ReplyKeyboardRemove ( selective = False )
tb.send_message (chat_id, message, reply_markup = markup)
# ForceReply: заставляет пользователя отвечать на сообщение 
# Принимает необязательный селективный аргумент (True / False, по умолчанию False) 
markup = types.ForceReply ( selective = False )
tb.send_message (chat_id, « Отправьте мне другое слово: » , reply_markup = markup)

ForceReply:

Встроенный режим

Подробнее о встроенном режиме .

inline_handler

Теперь вы можете использовать inline_handler для получения inline_query в telebot.

@ bot.inline_handler ( лямбда-  запрос : query.query ==  ' text ' )
 def  query_text ( inline_query ):
     # Сообщение запроса является текстовым

chosen_inline_handler

Используйте selected_inline_handler, чтобы получить selected_inline_result в telebot. Не забудьте добавить команду / setinlinefeedback для @Botfather.

Больше информации: сбор отзывов

@ bot.chosen_inline_handler ( func = lambda  selected_inline_result : True )
 def  test_chosen ( selected_inline_result ):
     # Обрабатывать все selected_inline_result.

answer_inline_query

@ bot.inline_handler ( лямбда-  запрос : query.query ==  ' текст ' )
 def  query_text ( inline_query ):
     try :
        r = types.InlineQueryResultArticle ( ' 1 ' , ' Result ' , types.InputTextMessageContent ( ' Result message. ' ))
        r2 = types.InlineQueryResultArticle ( ' 2 ' , ' Result2 ' , types.InputTextMessageContent ( ' Result message2. ' ))
        bot.answer_inline_query (inline_query.id, [r, r2])
    за исключением  исключения  как e:
         print (e)

Работа с сущностями:

Этот объект представляет одну особую сущность в текстовом сообщении. Например, хэштеги, имена пользователей, URL и т. Д. Атрибуты:

• type
• url
• offset
• length
• user

Вот пример:message.entities[num].<attribute>

Вот numномер объекта или порядок объекта в ответе, если в ответе / сообщении есть несколько объектов. 

message.entitiesвозвращает список объектов объекта. 

message.entities[0].typeдаст тип первой сущности. 

Обратитесь к Bot Api за дополнительной информацией.

Расширенное использование API

Асинхронная доставка сообщений

Существует реализация TeleBot, которая выполняет все send_xyzи get_meфункции асинхронно. Это может ускорить вы ЪоТ значительно , но имеет нежелательные побочные эффекты , если они используются без оглядки. Чтобы включить это поведение, создайте экземпляр AsyncTeleBot вместо TeleBot.

tb = telebot.AsyncTeleBot ( " TOKEN " )

Теперь каждая функция, которая вызывает API Telegram, выполняется в отдельном потоке. Функции модифицированы, чтобы возвращать экземпляр AsyncTask (определенный в util.py). Использование AsyncTeleBot позволяет вам сделать следующее:

импортный телебот

tb = telebot.AsyncTeleBot ( " TOKEN " )
task = tb.get_me () # Выполнить вызов API 
# Выполнить некоторые другие операции ... 
a =  0 
для a в  диапазоне ( 100 ):
 а + =  10

result = task.wait () # Получить результат выполнения

Примечание: если вы выполняете функции send_xyz после друг друга без вызова wait (), порядок доставки сообщений может быть неправильным.

Отправка больших текстовых сообщений

Иногда вы должны отправлять сообщения, которые превышают 5000 символов. Telegram API не может обрабатывать столько символов в одном запросе, поэтому нам нужно разделить сообщение на несколько. Вот как это сделать с помощью API:

от telebot импорта Util
large_text =  open ( " large_text.txt " , " rb " ) .read ()

# Разделить текст каждые 3000 символов. 
# split_string возвращает список с разделенным текстом. 
splitted_text = util.split_string (large_text, 3000 )
 для текста в splitted_text:
 tb.send_message (chat_id, текст)

Контроль количества потоков, используемых TeleBot

Конструктор TeleBot принимает следующие необязательные аргументы:

• с резьбой: True / False (по умолчанию True). Флаг, указывающий, должен ли TeleBot выполнять обработчики сообщений в потоке опроса.

Механизм слушателя

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

def  handle_messages ( messages ):
  для сообщения в сообщениях:
   # Что-то сделать с сообщением 
  bot.reply_to (message, ' Hi ' )

bot.set_update_listener (handle_messages)
bot.polling ()

Использование веб-хуков

При использовании webhooks телеграмма отправляет одно обновление на вызов, для его обработки вы должны вызывать process_new_messages ([update.message]) при получении.

В каталоге examples / webhook_examples есть несколько примеров использования webhooks .

логирование

Вы можете использовать регистратор модулей Telebot для регистрации отладочной информации о Telebot. Используйте, telebot.loggerчтобы получить регистратор модуля TeleBot. Можно добавить пользовательские обработчики журналов в регистратор. Обратитесь к странице модуля регистрации Python для получения дополнительной информации.

ведение журнала импорта

logger = telebot.logger
telebot.logger.setLevel (logging. DEBUG ) # Выводит сообщения отладки на консоль.

полномочие

Вы можете использовать прокси для запроса. apihelper.proxyОбъект будет использовать requestsаргумент прокси вызова .

от телебота импорт apihelper

apihelper.proxy = { ' http ' : ' http://10.10.1.10:3128 ' }

Если вы хотите использовать прокси - сервер Socket5 вам необходимо установить зависимость pip install requests[socks]и убедитесь, что у вас есть последняя версия gunicorn, PySocks, pyTelegramBotAPI, requestsи urllib3.

apihelper.proxy = { ' https ' : ' socks5: // userproxy: пароль @ proxy_address: порт ' }

Часто задаваемые вопросы

Бот 2.0

Апрель 9,2016 Telegram выпустил новый API-интерфейс бота 2.0, который имеет радикальные изменения, особенно для изменения интерфейса метода. Если вы хотите обновить приложение до последней версии, убедитесь, что вы переключили код бота на интерфейс метода бота 2.0.

Больше информации о поддержке pyTelegramBotAPI bot2.0

Как я могу различить пользователя и групповой чат в message.chat?

Telegram Bot API поддерживает новый тип чата для message.chat.

• Проверьте typeатрибут в Chatобъекте:

if message.chat.type == «private»:
  # личное сообщение в чате

if message.chat.type == “group”:
  # сообщение группового чата

if message.chat.type == «супергруппа»:
  # сообщение в супергруппе чата

if message.chat.type == “channel”:
  # сообщение канала

Telegram Chat Group

Получить помощь. Обсудить. Чат.

• Присоединяйтесь к чат-группе pyTelegramBotAPI Telegram
• Теперь у нас есть канал Telegram! Будьте в курсе изменений API и присоединяйтесь к нему .

Больше примеров

• Эхо Бот
• Глубокая связь
• Пример next_step_handler

Боты, использующие этот API

• Бот SiteAlert ( источник ) от ilteoood - контролирует сайты и отправляет уведомления об изменениях
• TelegramLoggingBot от aRandomStranger
• Отправить на Kindle Bot от GabrielRF - Отправить на Kindle файлы или ссылки на файлы.
• Telegram LMGTFY_bot ( источник ) от GabrielRF - Дайте мне Google, что для вас.
• Telegram UrlProBot ( источник ) от GabrielRF - сокращение URL и расширение URL.
• Telegram Proxy Bot от Groosha - простой BITM (бот в середине) для Telegram, действующий как своего рода «прокси».
• Telegram Proxy Bot от mrgigabyte - Credits for the original version of this bot goes to Груша , simply added certain features which I thought were needed .
• RadRetroRobot от Tronikart - многофункциональный бот Telegram RadRetroRobot.
• Бот League of Legends ( источник ) от i32ropie
• NeoBot от neoranger
• TagAlertBot от pitasi
• ComedoresUGRbot ( источник ) от alejandrocq - бот Telegram для проверки меню столовой Universidad de Granada.
• picpingbot - забавный анонимный обмен фотографиями от Boogie Muffin.
• TheZigZagProject - бот «Все в одном» для Telegram! от WebShark025
• proxybot - простой прокси-бот для Telegram. p-hash
• DonantesMalagaBot - DonantesMalagaBot предоставляет донорам крови Малаги информацию о местах, где они могут сдать кровь сегодня или в ближайшие дни. Он также записывает дату последнего пожертвования, чтобы помочь донорам узнать, когда они могут пожертвовать снова. - от vfranch
• DuttyBot от Дмитрия Стрилецкого - Расписание для одного университета в Киеве.
• dailypepebot от Jaime - получает случайные изображения Пепе и дает их идентификатор, затем вы можете назвать это изображение с помощью номера.
• DailyQwertee от Jaime - бот, управляющий каналом, который ежедневно отправляет футболки qwertee в 00:00.
• wat-bridge by rmed - Отправка и получение сообщений в / из WhatsApp через Telegram
• flibusta_bot от Kurbezz
• EmaProject от halkliff - Ema - Eastern Media Assistant заставил задуматься о простой в использовании функции. Кодирование здесь простое, а также быстрое и мощное.
• filmratingbot ( источник ) от jcolladosp - бот Telegram, использующий API Python, который получает рейтинг фильмов по IMDb и метакритику
• you2mp3bot ( ссылка ) - Этот бот может конвертировать видео с YouTube в MP3. Все, что вам нужно, это отправить URL видео.
• areajugonesbot ( ссылка ) - Areajugonesbot отправляет новости, опубликованные в блоге видеоигр Areajugones, в Telegram.
• Send2Kindlebot ( источник ) от GabrielRF - Отправка в службу Kindle.
• RastreioBot ( источник ) от GabrielRF - бот, используемый для отслеживания пакетов в бразильской почтовой службе.
• filex_bot ( ссылка )
• Spbu4UBot ( ссылка ) от EeOneDown - бот с расписанием для студентов СПбГУ.
• SmartySBot ( ссылка ) от 0xVK - бот расписания Telegram, для студентов Житомирского государственного университета имени Ивана Франко.
• yandex_music_bot - скачивает треки / альбомы / публичные плейлисты с сервиса потоковой передачи Яндекс.Музыка бесплатно.
• LearnIt ( ссылка ) - бот Telegram, созданный, чтобы помочь людям запомнить словарь других языков.
• MusicQuiz_bot от Etoneja - Слушайте аудиозамены и попробуйте назвать исполнителя песни.
• Bot-телеграмма-Shodan по rubenleon
• MandangoBot от @Alvaricias - бот для управления альянсами Marvel Strike Force (только на испанском, атм).

Хотите, чтобы ваш бот был указан здесь? Отправьте сообщение Telegram на адрес @eternnoir или @pevdh.