Not just a Python wrapper around the Telegram Bot API

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

Table of contents

• Introduction
• Telegram API support
• Installing
• Getting the code
• Getting started
  1. Learning by example
  2. API
  3. Extensions
  4. JobQueue
  5. Logging
  6. Documentation
• Getting help
• Contributing
• License

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.

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
answerInlineQuery	Yes
kickChatMember	Yes
unbanChatMember	Yes
answerCallbackQuery	Yes
editMessageText	Yes
editMessageCaption	Yes
editMessageReplyMarkup	Yes

Installing

You can install or upgrade python-telegram-bot with:

$ 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

Install dependencies:

$ pip install -r requirements.txt -r requirements-dev.txt

Run tests:

$ make test

To see other available options, run:

$ make help

Getting started

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

This library uses the logging module. To set up logging to standard output, put:

import logging
logging.basicConfig(level=logging.DEBUG,
                    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s')

at the beginning of your script.

Note: The telegram.ext module will catch errors that would cause the bot to crash. All these are logged to the logging module, so it's recommended to use this if you are looking for error causes.

Learning by example

We believe that the best way to learn and understand this simple package is by example. So here are some examples for you to review. Even if it's not your approach for learning, please take a look at echobot2 (below), it is de facto the base for most of the bots out there. Best of all, the code for these examples are released to the public domain, so you can start by grabbing the code and building on top of it.

• clibot has a command line interface.
• echobot2 replies back messages.
• inlinebot basic example of an inline bot
• state machine bot keeps the state for individual users, useful for multipart conversations
• timerbot uses the JobQueue to send timed messages.

Examples using only the API:

• echobot replies back messages.
• roboed talks to Robô Ed.

Look at the examples on the wiki to see other bots the community has built.

API

Note: Using the Bot class directly is the 'old' method, we have an easier way to make bots described in the next section. All of this is however still important information, even if you're using the telegram.ext submodule!

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 a text message with Html style:

>>> bot.sendMessage(chat_id=chat_id, text='<b>bold</b> <i>italic</i> <a href="http://google.com">link</a>.', parse_mode=telegram.ParseMode.HTML)

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:

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

To post an image file from disk:

>>> bot.sendPhoto(chat_id=chat_id, photo=open('tests/test.png', 'rb'))

To post a voice file from disk:

>>> 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.KeyboardButton(telegram.Emoji.THUMBS_UP_SIGN),
...     telegram.KeyboardButton(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

Extensions

The telegram.ext submodule is built on top of the bare-metal API. It provides an easy-to-use interface to the telegram.Bot by caring about getting new updates with the Updater class 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.

We'll need an Access Token. Note: If you have done this in the previous step, you can use that one. 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.ext 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. To do that, we have to use a CommandHandler object and register it in the dispatcher:

>>> from telegram.ext import CommandHandler
>>> start_handler = CommandHandler('start', start)
>>> dispatcher.addHandler(start_handler)

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 that listens for regular messages. We're using the MessageHandler here to echo to all text messages:

>>> def echo(bot, update):
...   bot.sendMessage(chat_id=update.message.chat_id, text=update.message.text)
...
>>> from telegram.ext import MessageHandler, Filters
>>> echo_handler = MessageHandler([Filters.text], echo)
>>> dispatcher.addHandler(echo_handler)

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

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 a command in the handler function:

>>> def caps(bot, update, args):
...   text_caps = ' '.join(args).upper()
...   bot.sendMessage(chat_id=update.message.chat_id, text=text_caps)
...
>>> caps_handler = CommandHandler('caps', caps, pass_args=True)
>>> dispatcher.addHandler(caps_handler)

To enable our bot to respond to inline queries, we can add the following (you will also have to talk to BotFather):

>>> from telegram import InlineQueryResultArticle
>>> def inline_caps(bot, update):
...   query = bot.update.inline_query.query
...   results = list()
...   results.append(InlineQueryResultArticle(query.upper(), 'Caps', query.upper()))
...   bot.answerInlineQuery(update.inline_query.id, results)
...
>>> from telegram.ext import InlineQueryHandler
>>> inline_caps_handler = InlineQueryHandler(inline_caps)
>>> dispatcher.addHandler(inline_caps_handler)

People might try to send commands to the bot that it doesn't understand, so we can use a RegexHandler to recognize all commands that were not recognized by the previous handlers. Note: This handler has to be added last, else it will be triggered before the CommandHandlers had a chance to look at the update:

>>> def unknown(bot, update):
...   bot.sendMessage(chat_id=update.message.chat_id, text="Sorry, I didn't understand that command.")
...
>>> from telegram.ext import RegexHandler
>>> unknown_handler = RegexHandler(r'/.*', unknown)
>>> dispatcher.addHandler(unknown_handler)

If you're done playing around, stop the bot with this:

>>> updater.stop()

Check out more examples in the examples folder!

JobQueue

The JobQueue allows you to perform tasks with a delay or even periodically. The Updater will create one for you:

>>> from telegram.ext import Updater
>>> u = Updater('TOKEN')
>>> j = u.job_queue

The job queue uses functions for tasks, so we define one and add it to the queue. Usually, when the first job is added to the queue, it wil start automatically. We can prevent this by setting prevent_autostart=True:

>>> def job1(bot):
...     bot.sendMessage(chat_id='@examplechannel', text='One message every minute')
>>> j.put(job1, 60, next_t=0, prevent_autostart=True)

You can also have a job that will not be executed repeatedly:

>>> def job2(bot):
...     bot.sendMessage(chat_id='@examplechannel', text='A single message with 30s delay')
>>> j.put(job2, 30, repeat=False)

Now, because we didn't prevent the auto start this time, the queue will start ticking. It runs in a seperate thread, so it is non-blocking. When we stop the Updater, the related queue will be stopped as well:

>>> u.stop()

We can also stop the job queue by itself:

>>> j.stop()

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)

Documentation

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

Getting help

You can get help in several ways:

1. We have a vibrant community of developers helping each other in our Telegram group. Join us!
2. You can ask for help on Stack Overflow using the python-telegram-bot tag.
3. As last resort, the developers are ready to help you with serious issues.

Contributing

Contributions of all sizes are welcome. Please review our contribution guidelines to get started. You can also help by reporting bugs.

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.