Telegram Communication

Telegram-Bot setup

Create a new Telegram-Bot

  • Telegram must be installed on Smartphone/PC,…
  • Open the following website:
  • Click on ‘SEND MESSAGE’ (Telegram should open and create a new contact ‘BotFather’)
  • Create a new bot with the command ‘/newbot
  • Enter a name for the bot
  • Enter a username for the bot
  • You will receive a token which has to be entered in RTOC (looks like this: 123456789:AABBAABB66AA11_uGG22GH44AA55_3)

Configure RTOC for Telegram

You can eather configure it in the settings of the RTOC GUI or edit the config.json file by yourself. Enter your Bot-Token there and activate it (active=True).

User permissions

By default any new client connected to this bot will have no permissions. You can change the default behavior in config.json.

The first client connected to the bot will automatically be admin. The admin has the permission to change the permissions of all users.

  • blocked: No permissions at all
  • custom: Can only call user-specifig shortcuts, cannot receive event-notifications
  • read: Can receive event-notifications and plot signals
  • write: Can create global Events/Actions, send Events/Signals, access devices
  • admin: Full permissions. Can delete signals, access settings menu

Custom permission

The custom permission has a special role. A user with ‘custom’ permission will not receive notifications for events and will only see shortcuts, created for this user. Thereby you can provide a very simple bot to users, which will only be able to call selected functions or modify parameters. For example a bot with only two buttons to control the heating in the livingroom: ‘Set Temperature’ and ‘Enable/Disable’

Telegram Custom-menu

The file telegramActions.json contains dicts with actions, that will be shown in the main menu and can be executed by any user. If the action-name (key) starts with ‘_’ only admins will be able to see this button.

Here is an example to send a screenshot

       "Screenshot": """

    import pyscreenshot as ImageGrab
    dir = self.config['global']['documentfolder']
    im = ImageGrab.grab()\'/telegram_overview.png')
    return 'picture', dir+'/telegram_overview.png'


A telegram action must return either a text, a picture or any other file.

return 'text', 'My example text' to return a text message.

return 'picture', <dir/to/picture.jpg> to return a picture.

return 'document', <dir/to/file> to return any other file.

User Shortcuts

Any Telegram client can define his own shortcuts to plugin-functions and parameters. These shortcuts will be displayed in the main menu.

To define a new shortcut, you can either modify the shortcuts manually in the telegram_clients.json file.

Clients with ‘write’ or ‘admin’ permission can create shortcuts right in the Telegram bot. You can press the ‘Create shortcut’ button in every plugin-parameter or function submenu.

**Important: ** Every telegram function (telegram_send_message,…) inside a plugin-function will send the message, file or image only to the client, who called the shortcut.