blog/markdown/Build-a-bot-to-communicate-with-your-smart-home-over-Telegram.md

You’ve got your smart home fully set up. You regularly like to show off with your friends how cool it is to turn on light bulbs, play videos and movies with a hint to your voice assistant, make coffee, and adjust the thermostat with a tap on an app. Congratulations!

But if you’re an automation enthusiast who rarely settles, you’ve probably grown frustrated with the number of apps you’ll have to download and the number of interfaces you’ll have to master to control your gadgets.

You’ll probably have an app for the lights, one for your media center, one for your smart shades, one for your thermostat, and a Google Home app that zealously (and hopelessly) tries to put all of them in the same place.

Probably, most of these apps won’t communicate with the others, and probably many of them won’t work if you aren’t on the same network as your gadget.

Wouldn’t it be cool if we could control everything from the same interface, without cluttering our phones or computers with tons of apps, through an interface that is accessible both from mobile and desktop devices as well as through external scripts/integrations, whether you are on your home network or outdoor? An interface that was both lightweight and straightforward to use?

But wait, hasn’t such an interface been around for a while, under the name of messaging or chat? After all, wouldn’t it be cool to control our house, gadgets, and cloud services through the same interface that we use to send cat pictures to our friends, and through a bot completely tailored to our needs, without all the boilerplate/frustration that usually comes with third-party bots?

Chat-powered smart homes

Enter the world of chatbot-powered smart homes.

In this story, I’ll show you how to easily set up commands and routines on top of existing smart home installations.

Many messaging apps and platforms exist out there, but so far the efforts of many of them (Facebook Messenger, Whatsapp, Hangouts, etc.) in providing a usable developer’s API have been disappointing, to say the least.

Gone are the golden days when everyone used XMPP or IRC as their messaging backbone and it was easy to integrate with services that all spoke the same language: today’s messaging apps’ world is extremely fragmented.

Moreover, as it’s in the interest of many of the big players to create walled gardens that don’t communicate with the rest of the world, the most-used solutions out there don’t come with officially supported APIs/developer interfaces.

Not only: some of the big players out there actively discourage users from using anything either than the official app to interact with the platform (Whatsapp, I’m looking at you).

In this extremely fragmented world made of several unconnected islands, Telegram represents a welcome exception. Their official bot API is well-documented and supported, and it’s very easy for anyone who knows a bit of programming to build integrations.

Create the bot

It’s quite easy to create a new bot on Telegram:

• Open a conversation with the BotFather.

• Type /start followed by /newbot to create a new bot. Give your bot a display name and a username.

• You’ll be provided with a link to start a conversation with your bot and a unique API key. Store it somewhere as we’ll use it soon to configure the Platypush plugin.

Configuring your bot in Platypush

• Install Platypush with the HTTP and Telegram extensions:

pip install 'platypush[http,telegram]'
[sudo] apt-get install redis-server
[sudo] systemctl start redis
[sudo] systemctl enable redis

• Play a bit with it if you haven’t done so yet. Find a few things that you’d like to manage/automate — lights, music, media, sensors, database, robots, smart plugs… — and install/configure the associated extensions.

In this article, we’ll see how to configure our newly-created bot to control Philips Hue lights, music playback, and PiCamera streaming.

• Add the Telegram configuration to your ~/.config/platypush/config.yaml file:

chat.telegram:
    api_token: <your bot token>

backend.chat.telegram:
    enabled: true

The backend enables you to receive events (like new messages, attachments, requests, etc.) and create custom hooks on them.

The plugin enables you to write to chats, programmatically send messages and attachments, administer channels, etc.

Let’s say that we want the bot to implement the following commands:

• /start: Welcome the new user.
• /help: Show the available commands.
• /lights_on: Turn on the lights.
• /lights_off: Turn off the lights.
• /music_play: Play a music resource/URL.
• /music_pause: Toggle the playback pause state.
• /music_next: Play the next song.
• /music_prev: Play the previous song.
• /start_streaming: Start remote streaming on the PiCamera.
• /stop_streaming: Stop remote streaming on the PiCamera.

All we have to do is to create event hooks in the Platypush config.yaml. In this context, you’ll need to:

pip install 'platypush[hue,mpd,picamera]'

# Hue lights configuration
light.hue:
    # Hue bridge IP address
    bridge: 192.168.1.10

    # Default groups to control
    groups:
        - Living Room

# MPD/Mopidy configuration
music.mpd:
    host: localhost
    port: 6600

# PiCamera configuration
camera.pi:
    vflip: False
    hflip: False

• Create a script (e.g. ~/.config/platypush/scripts/bot.py) to handle the logic of your hooks:

from platypush.event.hook import hook
from platypush.utils import run

from platypush.message.event.chat.telegram import CommandMessageEvent

available_cmds = [
  '/lights_on',
  '/lights_off',
  '/music_play [resource]',
  '/music_pause',
  '/music_prev',
  '/music_next',
  '/start_streaming',
  '/stop_streaming',
]

# /start command handler
@hook(CommandMessageEvent, command='start')
def on_start_cmd(event, **context):
    run('chat.telegram.send_message', chat_id=event.chat_id,
        text='Welcome! Type /help to see the available commands')

# /help command handler
@hook(CommandMessageEvent, command='help')
def on_help_cmd(event, **context):
  run('chat.telegram.send_message', chat_id=event.chat_id,
      text='Available commands:\n\n' + '\n'.join(available_cmds))

# /lights_on command handler
@hook(CommandMessageEvent, command='lights_on')
def on_lights_on_cmd(event, **context):
  run('light.hue.on')
  run('chat.telegram.send_message', chat_id=event.chat_id,
      text='Lights turned on')

# /lights_off command handler
@hook(CommandMessageEvent, command='lights_off')
def on_lights_off_cmd(event, **context):
  run('light.hue.off')
  run('chat.telegram.send_message', chat_id=event.chat_id,
      text='Lights turned off')

# /music_play command handler
@hook(CommandMessageEvent, command='music_play')
def on_music_play_cmd(event, **context):
  if event.cmdargs:
    run('music.mpd.play', resource=event.cmdargs[0])
  else:
    run('music.mpd.play')

  run('chat.telegram.send_message', chat_id=event.chat_id,
      text='Playing music')

# /music_pause command handler
@hook(CommandMessageEvent, command='music_pause')
def on_music_pause_cmd(event, **context):
  run('music.mpd.pause')
  run('chat.telegram.send_message', chat_id=event.chat_id,
      text='Music paused')

# /music_prev command handler
@hook(CommandMessageEvent, command='music_prev')
def on_music_prev_cmd(event, **context):
  run('music.mpd.previous')
  run('chat.telegram.send_message', chat_id=event.chat_id,
      text='Playing previous track')

# /music_next command handler
@hook(CommandMessageEvent, command='music_next')
def on_music_next_cmd(event, **context):
  run('music.mpd.next')
  run('chat.telegram.send_message', chat_id=event.chat_id,
      text='Playing next track')

# /start_streaming command handler
@hook(CommandMessageEvent, command='start_streaming')
def on_start_streaming_cmd(event, **context):
  run('camera.pi.start_streaming', listen_port=2222)
  run('chat.telegram.send_message', chat_id=event.chat_id,
      text='Camera stream started - check it with vlc tcp/h264://hostname:2222')

# /stop_streaming command handler
@hook(CommandMessageEvent, command='stop_streaming')
def on_stop_streaming_cmd(event, **context):
  run('camera.pi.stop_streaming')
  run('chat.telegram.send_message', chat_id=event.chat_id,
      text='Camera stream stopped')

• Start Platypush:

# Manual start
platypush

# Service start
systemctl --user start platypush.service

• Open a conversation with your bot on Telegram through the link provided by the BotFather and start playing with it:

You can also invite the bot to a chat group if you want to share it with multiple users - now your friends can finally easily mess the lights in your house!

Securing access

Right now the bot is accessible by anyone — you probably don’t want that. You can configure the Telegram back end so it only accepts messages from a specific list of chat IDs. (In Telegram, the chat_id is used both for private users and groups).

Send a message to the bot and open the Platypush logs or check its standard output: you should see some messages like this:

2020-01-03 19:09:32,701| INFO|platypush|Received event: {"type": "event", "target": "turing", "origin": "turing", "id": "***", "args": {"type": "platypush.message.event.chat.telegram.CommandMessageEvent", "chat_id": your_chat_id, "message": {"text": "/help", ...}, "user": {"user_id": your_user_id, "username": "****", "is_bot": false, "link": "https://t.me/you", "language_code": "en", "first_name": "***", "last_name": "***"}, "command": "help", "cmdargs": []}}

Copy the chat_id associated with your user in the backend configuration:

backend.chat.telegram:
    authorized_chat_ids:
        - your_user_id

The bot will now reply with an error if you try to send a message from an unauthorized user.

Conclusions

We have only explored one specific feature of the Telegram integration in this article: the ability of the bot to react to CommandMessageEvent events, run actions, and reply with text messages.

As you can see from the list of supported Telegram events you can do more, such as:

• Create hooks when someone shares contact info. Ever thought of letting a bot automatically store the new contacts sent to you by your friends via chat?

• Create hooks when you share a photo, video, or image file. For example, automatically download all media files sent to a chat to your hard drive or a remote Dropbox folder.

• Run actions on text messages instead of commands. You can use the TextMessageEvent, for example, if you prefer to type “turn on the lights” instead of /lights_on.

• Take a picture from the camera and send it to yourself through the send_photo action.

• Automatically moderate chat groups through the chat.telegram actions.

• You can also deploy multiple bots, e.g. per device, so you can run actions on a specific device from the associated chat, or instead, use a single bot as entry point and deliver messages to other devices over MQTT, Kafka, or HTTP API.

As long as there’s a plugin for it, you can now do it through your chat bot.