Skip to main content

A simple app to develop Telegram bot with Django

Project description

A simple app to develop Telegram bots with Django


The full documentation is at


  • IMPORTANT ver 1.0.0 : If you upgrade from a previous version, you MUST change how to include django_telegrambot.urls and modify your


Install django-telegrambot:

pip install django-telegrambot

Configure your installation

Add django_telegrambot in INSTALLED_APPS

And set your bots:
#Django Telegram Bot settings


    'MODE' : 'WEBHOOK', #(Optional [str]) # The default value is WEBHOOK,
                        # otherwise you may use 'POLLING'
                        # NB: if use polling you must provide to run
                        # a management command that starts a worker

    'WEBHOOK_SITE' : '',
    'WEBHOOK_PREFIX' : '/prefix', # (Optional[str]) # If this value is specified,
                                  # a prefix is added to webhook url

    #'WEBHOOK_CERTIFICATE' : 'cert.pem', # If your site use self-signed
                         #certificate, must be set with location of your public key
                         #certificate.(More info at )

    'BOTS' : [
           'TOKEN': '123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11', #Your bot token.

           #'ALLOWED_UPDATES':(Optional[list[str]]), # List the types of
                                                   #updates you want your bot to receive. For example, specify
                                                   #``["message", "edited_channel_post", "callback_query"]`` to
                                                   #only receive updates of these types. See ``telegram.Update``
                                                   #for a complete list of available update types.
                                                   #Specify an empty list to receive all updates regardless of type
                                                   #(default). If not specified, the previous setting will be used.
                                                   #Please note that this parameter doesn't affect updates created
                                                   #before the call to the setWebhook, so unwanted updates may be
                                                   #received for a short period of time.

           #'TIMEOUT':(Optional[int|float]), # If this value is specified,
                                   #use it as the read timeout from the server

           #'WEBHOOK_MAX_CONNECTIONS':(Optional[int]), # Maximum allowed number of
                                   #simultaneous HTTPS connections to the webhook for update
                                   #delivery, 1-100. Defaults to 40. Use lower values to limit the
                                   #load on your bot's server, and higher values to increase your
                                   #bot's throughput.

           #'POLL_INTERVAL' : (Optional[float]), # Time to wait between polling updates from Telegram in
                           #seconds. Default is 0.0

           #'POLL_CLEAN':(Optional[bool]), # Whether to clean any pending updates on Telegram servers before
                                   #actually starting to poll. Default is False.

           #'POLL_BOOTSTRAP_RETRIES':(Optional[int]), # Whether the bootstrapping phase of the `Updater`
                                   #will retry on failures on the Telegram server.
                                   #|   < 0 - retry indefinitely
                                   #|     0 - no retries (default)
                                   #|   > 0 - retry up to X times

           #'POLL_READ_LATENCY':(Optional[float|int]), # Grace time in seconds for receiving the reply from
                                   #server. Will be added to the `timeout` value and used as the read timeout from
                           #server (Default: 2).
        #Other bots here with same structure.


Include in your the django_telegrambot.urls (NB: If you upgrade from a previous version, you MUST change how to include django_telegrambot.urls. Never set prefix here!):
urlpatterns = [
    url(r'^', include('django_telegrambot.urls')),

Then use it in a project creating a module in your app

# Example code for module
from telegram.ext import CommandHandler, MessageHandler, Filters
from django_telegrambot.apps import DjangoTelegramBot

import logging
logger = logging.getLogger(__name__)

# Define a few command handlers. These usually take the two arguments bot and
# update. Error handlers also receive the raised TelegramError object in error.
def start(bot, update):
    bot.sendMessage(update.message.chat_id, text='Hi!')

def help(bot, update):
    bot.sendMessage(update.message.chat_id, text='Help!')

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

def error(bot, update, error):
    logger.warn('Update "%s" caused error "%s"' % (update, error))

def main():"Loading handlers for telegram bot")

    # Default dispatcher (this is related to the first bot in settings.DJANGO_TELEGRAMBOT['BOTS'])
    dp = DjangoTelegramBot.dispatcher
    # To get Dispatcher related to a specific bot
    # dp = DjangoTelegramBot.getDispatcher('BOT_n_token')     #get by bot token
    # dp = DjangoTelegramBot.getDispatcher('BOT_n_username')  #get by bot username

    # on different commands - answer in Telegram
    dp.add_handler(CommandHandler("start", start))
    dp.add_handler(CommandHandler("help", help))

    # on noncommand i.e message - echo the message on Telegram
    dp.add_handler(MessageHandler([Filters.text], echo))

    # log all errors


  • Multiple bots

  • Admin dashboard available at /admin/django-telegrambot

  • Polling mode by management command (an easy to way to run bot in local machine, not recommended in production!)

    (myenv) $ python botpolling --username=<username_bot>


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

Running Tests

Does the code actually work?

source <YOURVIRTUALENV>/bin/activate
(myenv) $ pip install -r requirements-test.txt
(myenv) $ python

Sample Application

There a sample application in sampleproject directory. Here is installation instructions:

  1. Install requirements with command

    pip install -r requirements.txt

  2. Copy file as and edit your bot token

    cp sampleproject/ sampleproject/

    nano sampleproject/

  3. Run Django migrations

    python migrate

  4. Run server

    python runserver

  5. If WEBHOOK Mode setted go to 8

  6. If POLLING Mode setted, open in your browser http://localhost/

  7. Open Django-Telegram Dashboard http://localhost/admin/django-telegrambot and follow instruction to run worker by management command botpolling. Then go to 10

  8. To test webhook locally install ngrok application and run command

    ./ngrok http 8000

  9. Change WEBHOOK_SITE and ALLOWED_HOSTS in file

  10. Start a chat with your bot using link avaible in Django-Telegram Dashboard at http://localhost/admin/django-telegrambot


Required package:

Tools used in rendering this package:


1.0.0 (2017-05-25)

  • IMPORTANT: If you upgrade from a previous version, you MUST change how to include django_telegrambot.urls and

  • Added admin dashboard, available at /admin/django-telegrambot

  • Added polling mode from management command (an easy to way to run bot in local machine, not recommended in production)

  • More setting available

  • Improved AppConfig

  • Improved sample project

0.2.6 (2017-04-08)

  • Improved module loading

  • Added sample project

0.2.5 (2017-03-06)

  • Fix compatibility with python-telegram-bot 5.1

0.2.4 (2016-10-04)

  • Fix compatibility with Django 1.10

0.2.3 (2016-07-30)

  • Fix default dispatcher and bot

0.2.2 (2016-07-27)

  • Fix multi workers

0.2.1 (2016-07-24)

  • Update for python-telegram-bot release v5.0

0.2.0 (2016-04-27)

  • Update for python-telegram-bot release v4.0.1

0.1.8 (2016-03-22)

  • Update for deprecation in python-telegram-bot release v3.4

0.1.5 (2016-01-28)

  • Fix compatibility.

0.1.4 (2016-01-28)

  • Fix compatibility.

0.1.3 (2016-01-28)

  • Fix setting certificate.

  • Add method DjangoTelegramBot.getBot(); get bot instance by token or username.

0.1.2 (2016-01-26)

  • First release on PyPI.

Project details

Download files

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

Source Distributions

No source distribution files available for this release. See tutorial on generating distribution archives.

Built Distribution

django_telegrambot-1.0.1-py2.py3-none-any.whl (18.1 kB view hashes)

Uploaded py2 py3

Supported by

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