Skip to main content

A Python wrapper around the Telegram Bot API

Project description

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

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

Table of contents

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

Getting started

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

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

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.

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

TODO

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

  • Add commands handler.

Project details


Release history Release notifications | RSS feed

Download files

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

Source Distribution

python-telegram-bot-2.9.1.tar.gz (41.1 kB view details)

Uploaded Source

Built Distribution

python_telegram_bot-2.9.1-py2.py3-none-any.whl (51.5 kB view details)

Uploaded Python 2 Python 3

File details

Details for the file python-telegram-bot-2.9.1.tar.gz.

File metadata

File hashes

Hashes for python-telegram-bot-2.9.1.tar.gz
Algorithm Hash digest
SHA256 d64396d2c6bae76372cf033baf995f020be74556038585aecff2fa08c6e00796
MD5 9394589f96853d5b9c919ff34a9f795a
BLAKE2b-256 4b59a17d48509bc28b635af5d5d8a7b37c3ed43d9376259f141748262c9be633

See more details on using hashes here.

File details

Details for the file python_telegram_bot-2.9.1-py2.py3-none-any.whl.

File metadata

File hashes

Hashes for python_telegram_bot-2.9.1-py2.py3-none-any.whl
Algorithm Hash digest
SHA256 02e6f7538497142b19b8b2ee5af208eaf9eda1e958e761739bd265b13cccd6db
MD5 355c4e35dc5b1e705b61feee168d8ad6
BLAKE2b-256 44478d1ee27b7ae3419365608143613c93b2ed69a2bccb729b8c000608833f7c

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page