diff --git a/README.rst b/README.rst new file mode 100644 index 0000000..bc789a3 --- /dev/null +++ b/README.rst @@ -0,0 +1,315 @@ +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 = '' + + 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 = '' + + + 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 = '' + 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 = '' + + 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 = '' + + 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 `__. + +Examples +-------- + +- `Echo + Bot `__ +- `Deep + Linking `__ +- `next\_step\_handler + Example `__ + +.. |Build Status| image:: https://travis-ci.org/eternnoir/pyTelegramBotAPI.svg?branch=master + :target: https://travis-ci.org/eternnoir/pyTelegramBotAPI