mirror of
https://github.com/eternnoir/pyTelegramBotAPI.git
synced 2023-08-10 21:12:57 +03:00
316 lines
8.1 KiB
ReStructuredText
316 lines
8.1 KiB
ReStructuredText
pyTelegramBotAPI
|
|
================
|
|
|
|
A Python implementation for the Telegram Bot API.
|
|
|
|
See https://core.telegram.org/bots/api
|
|
|
|
|Build Status|
|
|
|
|
How to install
|
|
--------------
|
|
|
|
Python 2 or Python 3 is required.
|
|
|
|
- Install from source
|
|
|
|
::
|
|
|
|
$ git clone https://github.com/eternnoir/pyTelegramBotAPI.git
|
|
$ cd pyTelegramBotAPI
|
|
$ python setup.py install
|
|
|
|
- or install with pip
|
|
|
|
::
|
|
|
|
$ pip install pyTelegramBotAPI
|
|
|
|
Example
|
|
-------
|
|
|
|
- Sending a message.
|
|
|
|
.. code:: python
|
|
|
|
import telebot
|
|
|
|
TOKEN = '<token string>'
|
|
|
|
tb = telebot.TeleBot(TOKEN)
|
|
# tb.send_message(chatid, message)
|
|
tb.send_message(281281, 'gogo power ranger')
|
|
|
|
- Echo Bot
|
|
|
|
.. code:: python
|
|
|
|
import telebot
|
|
import time
|
|
|
|
TOKEN = '<token_string>'
|
|
|
|
|
|
def listener(messages):
|
|
"""
|
|
When new messages arrive TeleBot will call this function.
|
|
"""
|
|
for m in messages:
|
|
chatid = m.chat.id
|
|
if m.content_type == 'text':
|
|
text = m.text
|
|
tb.send_message(chatid, text)
|
|
|
|
|
|
tb = telebot.TeleBot(TOKEN)
|
|
tb.set_update_listener(listener) #register listener
|
|
tb.polling()
|
|
#Use none_stop flag let polling will not stop when get new message occur error.
|
|
tb.polling(none_stop=True)
|
|
# Interval setup. Sleep 3 secs between request new message.
|
|
tb.polling(interval=3)
|
|
|
|
while True: # Don't let the main Thread end.
|
|
pass
|
|
|
|
TeleBot API usage
|
|
-----------------
|
|
|
|
.. code:: python
|
|
|
|
import telebot
|
|
import time
|
|
|
|
TOKEN = '<token_string>'
|
|
tb = telebot.TeleBot(TOKEN) #create a new Telegram Bot object
|
|
|
|
# TeleBot will not create thread for message listener. Default is True.
|
|
tb = telebot.TeleBot(TOKEN, False)
|
|
|
|
# 4 Thread worker for message listener.
|
|
tb = telebot.TeleBot(TOKEN, True, 4)
|
|
|
|
# Setup telebot handler to telebot logger. If you want to get some information from telebot.
|
|
# More information at Logging section
|
|
handler = logging.StreamHandler(sys.stdout)
|
|
telebot.logger.addHandler(handler)
|
|
telebot.logger.setLevel(logging.INFO)
|
|
|
|
# getMe
|
|
user = tb.get_me()
|
|
|
|
# sendMessage
|
|
tb.send_message(chatid, text)
|
|
|
|
# forwardMessage
|
|
# tb.forward_message(10894,926,3)
|
|
tb.forward_message(to_chat_id, from_chat_id, message_id)
|
|
|
|
# sendPhoto
|
|
photo = open('/tmp/photo.png', 'rb')
|
|
tb.send_photo(chat_id, photo)
|
|
file_id = 'AAAaaaZZZzzz'
|
|
tb.send_photo(chat_id, file_id)
|
|
|
|
# sendAudio
|
|
audio = open('/tmp/audio.mp3', 'rb')
|
|
tb.send_audio(chat_id, audio)
|
|
## sendAudio with duration, performer and title.
|
|
tb.send_audio(CHAT_ID, file_data, 1, 'eternnoir', 'pyTelegram')
|
|
file_id = 'AAAaaaZZZzzz'
|
|
tb.send_audio(chat_id, file_id)
|
|
|
|
# sendVoice
|
|
voice = open('/tmp/voice.ogg', 'rb')
|
|
tb.send_voice(chat_id, voice)
|
|
file_id = 'AAAaaaZZZzzz'
|
|
tb.send_voice(chat_id, file_id)
|
|
|
|
# sendDocument
|
|
doc = open('/tmp/file.txt', 'rb')
|
|
tb.send_document(chat_id, doc)
|
|
file_id = 'AAAaaaZZZzzz'
|
|
tb.send_document(chat_id, file_id)
|
|
|
|
# sendSticker
|
|
sti = open('/tmp/sti.webp', 'rb')
|
|
tb.send_sticker(chat_id, sti)
|
|
file_id = 'AAAaaaZZZzzz'
|
|
tb.send_sticker(chat_id, file_id)
|
|
|
|
# sendVideo
|
|
video = open('/tmp/video.mp4', 'rb')
|
|
tb.send_video(chat_id, video)
|
|
file_id = 'AAAaaaZZZzzz'
|
|
tb.send_video(chat_id, file_id)
|
|
|
|
# sendLocation
|
|
tb.send_location(chat_id, lat, lon)
|
|
|
|
# sendChatAction
|
|
# action_string can be one of the following strings: 'typing', 'upload_photo', 'record_video', 'upload_video',
|
|
# 'record_audio', 'upload_audio', 'upload_document' or 'find_location'.
|
|
tb.send_chat_action(chat_id, action_string)
|
|
|
|
# Use the ReplyKeyboardMarkup class.
|
|
# Thanks pevdh.
|
|
from telebot import types
|
|
|
|
markup = types.ReplyKeyboardMarkup()
|
|
markup.add('a', 'v', 'd')
|
|
tb.send_message(chat_id, message, reply_markup=markup)
|
|
|
|
# or add strings one row at a time:
|
|
markup = types.ReplyKeyboardMarkup()
|
|
markup.row('a', 'v')
|
|
markup.row('c', 'd', 'e')
|
|
tb.send_message(chat_id, message, reply_markup=markup)
|
|
|
|
Creating a Telegram bot with the pyTelegramBotAPI
|
|
-------------------------------------------------
|
|
|
|
There are two ways to define a Telegram Bot with the pyTelegramBotAPI.
|
|
### The listener mechanism
|
|
|
|
- First, create a TeleBot instance.
|
|
|
|
.. code:: python
|
|
|
|
import telebot
|
|
|
|
TOKEN = '<token string>'
|
|
|
|
bot = telebot.TeleBot(TOKEN)
|
|
|
|
- Then, define a listener function.
|
|
|
|
.. code:: python
|
|
|
|
def echo_messages(*messages):
|
|
"""
|
|
Echoes all incoming messages of content_type 'text'.
|
|
"""
|
|
for m in messages:
|
|
chatid = m.chat.id
|
|
if m.content_type == 'text':
|
|
text = m.text
|
|
bot.send_message(chatid, text)
|
|
|
|
- Now, register your listener with the TeleBot instance and call
|
|
TeleBot#polling()
|
|
|
|
.. code:: python
|
|
|
|
bot.set_update_listener(echo_messages)
|
|
bot.polling()
|
|
|
|
while True: # Don't let the main Thread end.
|
|
pass
|
|
|
|
- use Message's content\_type attribute to check the type of Message.
|
|
Now Message supports content types:
|
|
- text
|
|
- audio
|
|
- document
|
|
- photo
|
|
- sticker
|
|
- video
|
|
- location
|
|
- contact
|
|
- new\_chat\_participant
|
|
- left\_chat\_participant
|
|
- new\_chat\_title
|
|
- new\_chat\_photo
|
|
- delete\_chat\_photo
|
|
- group\_chat\_created
|
|
- That's it!
|
|
|
|
The decorator mechanism
|
|
~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
- First, create a TeleBot instance.
|
|
|
|
.. code:: python
|
|
|
|
import telebot
|
|
|
|
TOKEN = '<token string>'
|
|
|
|
bot = telebot.TeleBot(TOKEN)
|
|
|
|
- Next, define all of your so-called message handlers and decorate them
|
|
with @bot.message\_handler
|
|
|
|
.. code:: python
|
|
|
|
# Handle /start and /help
|
|
@bot.message_handler(commands=['start', 'help'])
|
|
def command_help(message):
|
|
bot.reply_to(message, "Hello, did someone call for help?")
|
|
|
|
# Handles all messages which text matches the regex regexp.
|
|
# See https://en.wikipedia.org/wiki/Regular_expression
|
|
# This regex matches all sent url's.
|
|
@bot.message_handler(regexp='((https?):((//)|(\\\\))+([\w\d:#@%/;$()~_?\+-=\\\.&](#!)?)*)')
|
|
def command_url(message):
|
|
bot.reply_to(message, "I shouldn't open that url, should I?")
|
|
|
|
# Handle all sent documents of type 'text/plain'.
|
|
@bot.message_handler(func=lambda message: message.document.mime_type == 'text/plain', content_types=['document'])
|
|
def command_handle_document(message):
|
|
bot.reply_to(message, "Document received, sir!")
|
|
|
|
# Default command handler. A lambda expression which always returns True is used for this purpose.
|
|
@bot.message_handler(func=lambda message: True, content_types=['audio', 'video', 'document', 'text', 'location', 'contact', 'sticker'])
|
|
def default_command(message):
|
|
bot.reply_to(message, "This is the default command handler.")
|
|
|
|
- And finally, call bot.polling()
|
|
|
|
.. code:: python
|
|
|
|
bot.polling()
|
|
|
|
while True: # Don't end the main thread.
|
|
pass
|
|
|
|
Use whichever mechanism fits your purpose! It is even possible to mix
|
|
and match.
|
|
|
|
Logging
|
|
-------
|
|
|
|
Now you can use Telebot module logger to log some information in
|
|
Telebot. Use ``telebot.logger`` to get Telebot module logger.
|
|
|
|
.. code:: python
|
|
|
|
logger = telebot.logger
|
|
formatter = logging.Formatter('[%(asctime)s] %(thread)d {%(pathname)s:%(lineno)d} %(levelname)s - %(message)s',
|
|
'%m-%d %H:%M:%S')
|
|
ch = logging.StreamHandler(sys.stdout)
|
|
logger.addHandler(ch)
|
|
logger.setLevel(logging.DEBUG) # or use logging.INFO
|
|
ch.setFormatter(formatter)
|
|
|
|
Telegram Chat Group
|
|
-------------------
|
|
|
|
Get help. Discuss. Chat.
|
|
|
|
Join `pyTelegramBotAPI Chat
|
|
Group <https://telegram.me/joinchat/067e22c60035523fda8f6025ee87e30b>`__.
|
|
|
|
Examples
|
|
--------
|
|
|
|
- `Echo
|
|
Bot <https://github.com/eternnoir/pyTelegramBotAPI/blob/master/examples/echo_bot.py>`__
|
|
- `Deep
|
|
Linking <https://github.com/eternnoir/pyTelegramBotAPI/blob/master/examples/deep_linking.py>`__
|
|
- `next\_step\_handler
|
|
Example <https://github.com/eternnoir/pyTelegramBotAPI/blob/master/examples/step_example.py>`__
|
|
|
|
.. |Build Status| image:: https://travis-ci.org/eternnoir/pyTelegramBotAPI.svg?branch=master
|
|
:target: https://travis-ci.org/eternnoir/pyTelegramBotAPI
|