Skip to main content

A Python wrapper around the Telegram Bot API

Project description

python-telegram-bot Logo

A Python wrapper around the Telegram Bot API.

Stay tuned for library updates and new releases on our Telegram Channel.

PyPi Package Version PyPi Package Monthly Download Documentation Status LGPLv3 License Travis CI Status Code Climate Coveralls

Introduction

This library provides a pure Python interface for the Telegram Bot API. It works with Python versions from 2.6+. It also works with Google App Engine.

Status

Telegram API support

Telegram Bot API Method Supported?
getMe Yes
sendMessage Yes
forwardMessage Yes
sendPhoto Yes
sendAudio Yes
sendDocument Yes
sendSticker Yes
sendVideo Yes
sendVoice Yes
sendLocation Yes
sendChatAction Yes
getUpdates Yes
getUserProfilePhotos Yes
getFile Yes
setWebhook Yes

Python Version support

Python Version Supported?
2.6 Yes
2.7 Yes
3.3 Yes
3.4 Yes
PyPy Yes
PyPy3 Yes

Installing

You can install python-telegram-bot using:

$ pip install python-telegram-bot

Or upgrade to the latest version:

$ pip install python-telegram-bot --upgrade

Getting the code

The code is hosted at https://github.com/python-telegram-bot/python-telegram-bot

Check out the latest development version anonymously with:

$ git clone https://github.com/python-telegram-bot/python-telegram-bot
$ cd python-telegram-bot

Run tests:

$ make test

To see other options available, run:

$ make help

Getting started

View the last release API documentation at: https://core.telegram.org/bots/api

The Updater class

The Updater class is the new way to create bots with python-telegram-bot. It provides an easy-to-use interface to the telegram.Bot by caring about getting new updates from telegram and forwarding them to the Dispatcher class. We can register handler functions in the Dispatcher to make our bot react to Telegram commands, messages and even arbitrary updates.

As with the old method, we’ll need an Access Token. To generate an Access Token, we have to talk to BotFather and follow a few simple steps (described here).

First, we create an Updater object:

>>> from telegram import Updater
>>> updater = Updater(token='token')

For quicker access to the Dispatcher used by our Updater, we can introduce it locally:

>>> dispatcher = updater.dispatcher

Now, we need to define a function that should process a specific type of update:

>>> def start(bot, update):
...   bot.sendMessage(chat_id=update.message.chat_id, text="I'm a bot, please talk to me!")

We want this function to be called on a Telegram message that contains the /start command, so we need to register it in the dispatcher:

>>> dispatcher.addTelegramCommandHandler('start', start)

The last step is to tell the Updater to start working:

>>> updater.start_polling()

Our bot is now up and running (go ahead and try it)! It’s not doing anything yet, besides answering to the /start command. Let’s add another handler function and register it:

>>> def echo(bot, update):
...   bot.sendMessage(chat_id=update.message.chat_id, text=update.message.text)
...
>>> dispatcher.addTelegramMessageHandler(echo)

Our bot should now reply to all messages that are not a command with a message that has the same content.

People might try to send commands to the bot that it doesn’t understand, so we should get that covered as well:

>>> def unknown(bot, update):
...   bot.sendMessage(chat_id=update.message.chat_id, text="Sorry, I didn't understand that command.")
...
>>> dispatcher.addUnknownTelegramCommandHandler(unknown)

Let’s add some functionality to our bot. We want to add the /caps command, that will take some text as parameter and return it in all caps. We can get the arguments that were passed to the command in the handler function simply by adding it to the parameter list:

>>> def caps(bot, update, args):
...   text_caps = ' '.join(args).upper()
...   bot.sendMessage(chat_id=update.message.chat_id, text=text_caps)
...
>>> dispatcher.addTelegramCommandHandler('caps', caps)

Now it’s time to stop the bot:

>>> updater.stop()

Check out more examples in the examples folder!

API

Note: Using the Bot class directly is the ‘old’ method, but some of this is still important information, even if you’re using the Updater class!

The API is exposed via the telegram.Bot class.

To generate an Access Token you have to talk to BotFather and follow a few simple steps (described here).

For full details see the Bots: An introduction for developers.

To create an instance of the telegram.Bot:

>>> import telegram
>>> bot = telegram.Bot(token='token')

To see if your credentials are successful:

>>> print bot.getMe()
{"first_name": "Toledo's Palace Bot", "username": "ToledosPalaceBot"}

Bots can’t initiate conversations with users. A user must either add them to a group or send them a message first. People can use telegram.me/<bot_username> links or username search to find your bot.

To fetch text messages sent to your Bot:

>>> updates = bot.getUpdates()
>>> print [u.message.text for u in updates]

To fetch images sent to your Bot:

>>> updates = bot.getUpdates()
>>> print [u.message.photo for u in updates if u.message.photo]

To reply messages you’ll always need the chat_id:

>>> chat_id = bot.getUpdates()[-1].message.chat_id

To post a text message:

>>> bot.sendMessage(chat_id=chat_id, text="I'm sorry Dave I'm afraid I can't do that.")

To post a text message with markdown:

>>> bot.sendMessage(chat_id=chat_id, text="*bold* _italic_ [link](http://google.com).", parse_mode=telegram.ParseMode.MARKDOWN)

To post an Emoji (special thanks to Tim Whitlock):

>>> bot.sendMessage(chat_id=chat_id, text=telegram.Emoji.PILE_OF_POO)

To post an image file via URL (right now only sendPhoto supports this):

>>> bot.sendPhoto(chat_id=chat_id, photo='https://telegram.org/img/t_logo.png')

To post a voice file:

>>> bot.sendVoice(chat_id=chat_id, voice=open('tests/telegram.ogg', 'rb'))

To tell the user that something is happening on bot’s side:

>>> bot.sendChatAction(chat_id=chat_id, action=telegram.ChatAction.TYPING)

To create Custom Keyboards:

>>> custom_keyboard = [[ telegram.Emoji.THUMBS_UP_SIGN, telegram.Emoji.THUMBS_DOWN_SIGN ]]
>>> reply_markup = telegram.ReplyKeyboardMarkup(custom_keyboard)
>>> bot.sendMessage(chat_id=chat_id, text="Stay here, I'll be back.", reply_markup=reply_markup)

To hide Custom Keyboards:

>>> reply_markup = telegram.ReplyKeyboardHide()
>>> bot.sendMessage(chat_id=chat_id, text="I'm back.", reply_markup=reply_markup)

To download a file (you will need its file_id):

>>> file_id = message.voice.file_id
>>> newFile = bot.getFile(file_id)
>>> newFile.download('voice.ogg')

There are many more API methods, to read the full API documentation:

$ pydoc telegram.Bot

Logging

You can get logs in your main application by calling logging and setting the log level you want:

>>> import logging
>>> logger = logging.getLogger()
>>> logger.setLevel(logging.INFO)

If you want DEBUG logs instead:

>>> logger.setLevel(logging.DEBUG)

Examples

Here follows some examples to help you to get your own Bot up to speed:

Legacy examples (pre-3.0):

Other notable examples:

Documentation

python-telegram-bot’s documentation lives at Read the Docs.

License

You may copy, distribute and modify the software provided that modifications are described and licensed for free under LGPL-3. Derivatives works (including modifications or anything statically linked to the library) can only be redistributed under LGPL-3, but applications that use the library don’t have to be.

Contact

Feel free to join to our Telegram group.

TODO

Patches and bug reports are welcome, just please keep the style consistent with the original source.

Project details


Release history Release notifications

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for python-telegram-bot, version 3.1.2
Filename, size & hash File type Python version Upload date
python_telegram_bot-3.1.2-py2.py3-none-any.whl (62.4 kB) View hashes Wheel 2.7
python-telegram-bot-3.1.2.tar.gz (52.3 kB) View hashes Source None

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page