This tutorial shows you how to create a Telegram bot that runs on your device. With this setup it is easy to control your device from anywhere in the world, or to send notifications from your device to your phone (or any other device that has Telegram installed).


We assume that you have set up your development environment as described in the IDE tutorial.

We also assume that you have flashed your device with Jaguar and that you are familiar with running Toit programs on it. If not, have a look at the Hello world tutorial.

Note that you can do this tutorial without a device. In that case, you need to use the -d host option whenever you invoke jag run. The program will then run on your computer instead of on a device.

You will need a Telegram account to follow this tutorial.

Create a Telegram bot

To create a Telegram bot, you need to talk to the BotFather. This is a bot that helps you create other bots.

Start a conversation with the BotFather by clicking on the link above. Then type /newbot and follow the instructions. You will be asked to give your bot a name and a username. The username must end with bot. For example, you can call your bot ToitBot and give it the username ToitBot_bot. The bot names are globally unique, so you may have to try a few different names before you find one that is available.

When you are done, the BotFather will give you a token that you can use to access your bot. You will need this token later.

See the official BotFather documentation.

Toit program

Now that we have a bot, we can write a Toit program that uses it.


We will use the telegram package to communicate with the Telegram bot. Install it with the following command. See the packages tutorial for details.

jag pkg install

You can probably just write jag pkg install telegram, but the full ID together with the version is more explicit, and will make sure you get the right package.

Feel free to use a newer version of the package if one is available. You might need to update the code samples below if you do.


The following program implements a simple bot that listens for messages that are sent to it (in a private chat). It will reply to these messages with an "Of course!" message.

Don't forget to replace <YOUR TOKEN> with the token that you got from the BotFather.

import telegram show *


  client := Client --token=TELEGRAM-TOKEN
  my-username := client.get-me.username

  client.listen: | update/Update? |
    if update is UpdateMessage:
      print "Got message: $update"
      message := (update as UpdateMessage).message
      if and == Chat.TYPE-PRIVATE:
        client.send-message "Of course!"

For a more useful bot, you would probably want to do something more interesting than just replying to messages. For example, you could use the bot to control a peripheral on your device, or to send notifications to your phone when a sensor value changes.

It is not good practice to hard-code credentials in your program. See the secrets tutorial for details on how to handle secrets in Toit projects.