Creating Telegram Bot and Deploying it to Heroku

In this tutorial, we’ll create a simple Telegram Bot using python-telegram-bot and deploy it to Heroku using Heroku Container Registry and Docker.

Photo by Marc-Olivier Jodoin on Unsplash
All source code is available in Github repository.


Our bot has 2 commands: /start and /random.

  • Command /start says hello to our new users
  • Command /random sends the random number to the user


Our script has 2 ways of work: development (local) and production (Heroku). It’s determined by using the env variable MODEwith 2 possible values: dev, prod. If you do not specify MODE, you will get a logger error message and script will exit.

Not less important is env variableTOKEN. You can get it from system Telegram Bot called BotFather.

Here is a image-example of your possible dialog with BotFather.

Example of creating a new bot and getting its token. Token for this bot is 798031528:AAFsvUypwHyAyhhWZ5X8WYYgSwiBTJB8I0Q. This token is not working anymore, I revoked it.
IMPORTANT: don’t tell anyone your bot TOKEN, don’t put it on your public Github repo etc!

If you are wonder about env variable PORT, you can simply don’t set it, 8443 is OK port number for Heroku.

HEROKU_APP_NAME is the name of your application that you have created in Heroku.

Now, it’s time to talk about the code itself.

First of all, we need to initialize our Updater with TOKEN.

Then, we need to add command handlers, we are going to use CommandHandler class from telegram.ext package. It accepts two mandatory arguments:

  • command — string or list of strings this handler should listen for
  • callback — callback function for this handler

In our example, if the user sends /start message, it will be caught by start_hanlder, /random message will be caught by random_handler; all other messages will be ignored.


To run this bot locally, you need to execute the command in your terminal:

MODE=dev; TOKEN=<your TOKEN from BotFather>; python

If you are using PyCharm for Python development, you can use Run/Debug Configurations window.

Run/Debug Configurations PyCharm window
Environmental Variables PyCharm window

After running using your preferred option, you will get

2018–12–14 15:12:21,500 — root — INFO — Starting bot

If you go to your bot in Telegram and press Start button, you will get

2018–12–14 15:12:36,617 — root — INFO — User <user_id> started bot

And if you type /random command, you will get

2018–12–14 15:12:38,238 — root — INFO — User <user_id> randomed number 2


You should have a Heroku account.

To launch your bot in Heroku you should go through the next steps:

  • create an account or use an existing one
  • create an application (remember about HEROKU_APP_NAME)
Creating an application in your account
  • specify environmental variables in Settings tab of your application
Setting env variables. TOKEN provided in the image is not valid.

To deploy to Heroku I prefer Heroku Container Registry. Thus you need Docker to be installed and running.

Docker tutorial could be found here.

Installation links for:

You can read full instructions about deploying images to Heroku here. But I’ll focus on the steps that you actually need to start your bot.

This is a sample of Dockerfile to build an image and push it to Heroku Container Registry.

Go to the directory where you place, Dockerfileand execute next steps:

  • Download Heroku CLI here
  • Login

heroku container:login

  • Build and push an image

heroku container:push --app <HEROKU_APP_NAME> web

  • Create a new release

heroku container:release --app <HEROKU_APP_NAME> web

  • Watch logs

heroku logs --tail --app <HEROKU_APP_NAME>

After some time, you should be able to see logs of your bot.

And yes, it could be absolutely FREE.


So, in this tutorial, we have created a simple Telegram Bot using Python and deployed it on Heroku using Heroku Container Registry and Docker.

P.S. Bot is live, you can check it out here.

I personally have only one issue with the free plan on Heroku. Your application sleeps after 30 minutes of inactivity. This leads to the fact that the state in which your bot was, will not be saved, and an attempt to respond to an old message will not lead to something.

There are 2 possible solutions for this issue:

  • Use next level plan on Heroku (require $)
  • Use persistence in python-telegram-bot. It is under development now, but I believe it will be released soon.

Thanks for the attention to the topic, feel free to leave your questions in the comments for discussion.