Python Telegram Bot

A Python wrapper around the Telegram Bot API.

By Leandro Toledo

• Introduction
• Status
  1. Telegram API support
  2. Python Version support
• Installing
• Getting the code
• Documentation
  1. API
  2. Examples
• 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.

You can install python-telegram-bot using:

$ pip install python-telegram-bot

Or upgrade to the latest version:

$ pip install python-telegram-bot --upgrade

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

Check out the latest development version anonymously with:

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

Run tests:

$ make test

To see other options available, run:

$ make help

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

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 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 an audio file:

>>> bot.sendAudio(chat_id=chat_id, audio=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)

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

$ pydoc telegram.Bot

To get a verbose mode to debug:

>>> telegram.Bot('token', debug=True)

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

• echobot replies back messages.
• roboed talks to Robô Ed.
• 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).

Feel free to join to our Telegram group.

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

• Add commands handler.