PTB Django cookiecutter

PTB Django Cookiecutter

A simple cookiecutter to create Python Telegram bots, wrapped with Django.

Latest release Documentation Status Chat on Telegram

All Contributors

Based on this cool projects

What's inside

  • Django app with dev and prod environments.
  • Model to store bot users data.
  • Command to run the bot.
  • Admin web interface to see the bot data.
  • Authentication mechanism.
  • Some example callbacks.
  • Small engine to wrap the bot callbacks.
  • Ready for deployment using Docker via docker-compose.


Install the latest Cookiecutter if you haven't installed it yet:

pip install -U cookiecutter

Create your bot using this cookiecutter:

cookiecutter gh:lugodev/ptb-django-cookiecutter

This will clone the cookiecutter and launch a wizard to help you customize your new bot.


Bot engine folder structure ?

Once you have generated your new bot, you will get this folders structure:

  • src/bot: The bot source code.
    • core:
      • The authentication mechanism.
      • Your callbacks here.
      • Your commands here.
      • Your conversation states, defined as constants.
      • Your conversation callbacks.
      • The bot engine.
      • The message filter callbacks.
      • Your bot models, defined as Django model classes.
      • Methods to render your messages.

Install your bot dependencies ?

You have two primary options to install de bot Python dependencies: pip or Poetry. You can also use pipenv, virtualenvwrapper or another package managers. We recommend Poetry.

  1. Install dependencies using Poetry:

    curl -sSL | python -
    cd src/bot
    poetry install

Tip (optional): Create these aliases on on your .bashrc or .zshrc, like this

alias poetry="python3 -m poetry"
alias django="poetry run ./"
alias djr="django runserver"
alias djm="django makemigrations && django migrate"
alias djmr="djm && djr"
  1. Or install your dependencies using pip.

    pip3 install -r requirements.txt

Initialize your bot environment variables

Place your env vars to the .env file (never push this file to the repo):

SECRET_KEY=your django random secret key
TELEGRAM_TOKEN=your bot token

Migrate database

This cookiecutter uses the Django ORM. First you must to make the model's migrations and then migrate them to database:

python3 src/bot/ makemigrations
python3 src/bot/ migrate

Start the bot

Start the bot (using the previously suggested alias, optional):

django runbot

Or using Poetry:

python3 -m poetry run src/bot/ runbot

Or using Python:

python3 src/bot/ runbot

Deploy your bot ?

Clone your repo to the server, and create this folder structure:

  • codebase: The repo itself, the source code.
  • storage: The place to store the DB and other persistant files.

Create and fill the ./codebase/.env file with the environment vars.

Then, deploy, using docker-compose:

cd codebase
docker-compose up --build -d

Bots created with this cookiecutter

None yet. Want to be the first? Submit your bot if it's open source.

Related videos

Crea tu bot de Telegram usando esta plantilla - PTB  + Django + Cookiecutter


Thanks goes to these wonderful people (emoji key):

Carlos Lugones

Reinier Hernández

This project follows the all-contributors specification. Contributions of any kind welcome!

Download source code from Github

Download ZIP

Submit resources