python-telegram-bot codeclimate travis-ci python

A Python wrapper around the Telegram Bot API.

Python Telegram Bot

A Python wrapper around the Telegram Bot API.

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

By Leandro Toledo <[email protected]>_

.. image:: :target: :alt: PyPi Package Version

.. image:: :target: :alt: PyPi Package Monthly Download

.. image:: :target: :alt: Documentation Status

.. image:: :target: :alt: LGPLv3 License

.. image:: :target: :alt: Travis CI Status

.. image:: :target: :alt: Code Climate

.. image:: :target: :alt: Coveralls


Table of contents

  • Introduction_

  • Status_

    1. Telegram API support_

    2. Python Version support_

  • Installing_

  • Getting the code_

  • Getting started_

    1. API_

    2. Logging_

    3. Examples_

    4. Documentation_

  • License_

  • Contact_

  • TODO_



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 <>.



_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 ============== ============



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

Check out the latest development version anonymously with::

$ git clone
$ 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:


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<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 [ for u in updates if]

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](", 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='')

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)

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

$ pydoc telegram.Bot


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)


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

  • echobot <>_ replies back messages.

  • roboed <>_ talks to Robô Ed <>_.

  • Simple-Echo-Telegram-Bot <>_ simple Python Telegram bot that echoes your input with Flask microframework, setWebhook method, and Google App Engine (optional) - by @sooyhwang.

  • DevOps Reaction Bot <>_ sends latest or random posts from DevOps Reaction <>. Running on Google App Engine <> (billing has to be enabled for fully Socket API support).



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



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.



Feel free to join to our Telegram group <>_.

If you face trouble joining in the group please ping me via Telegram <>_, I’ll be glad to add you.



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

  • Add commands handler.

Related Repositories



We have made you a wrapper you can't refuse ...



Python framework for Telegram Bot API ...



Python Telegram bot api. ...



Is a pretty simple and fully asynchronous library for Telegram Bot API written in Python 3.6 with asyncio and aiohttp. ...



A Text-to-Speech Python Telegram bot ...

Top Contributors

leandrotoledo ergoz NoneGG rahiel jh0ker wjt JRoot3D Avanatiker bimmlerd franciscod mASOUDd zubchick zeehio peczony


-   v2.8.7 zip tar
-   v2.8.6 zip tar
-   v2.8.5 zip tar
-   v2.8.4 zip tar
-   v2.8.3 zip tar
-   v2.8.2 zip tar
-   v2.8.1 zip tar
-   v2.8 zip tar
-   v2.7.1 zip tar
-   v2.7 zip tar
-   v2.6.1 zip tar
-   v2.6.0 zip tar
-   v2.5.3 zip tar
-   v2.5.2 zip tar
-   v2.5.1 zip tar
-   v2.5 zip tar