Telegram webhooks (#2043)

* first version

* configuration variables
This commit is contained in:
Stefano Scipioni 2017-02-14 19:07:41 +01:00 committed by Fabian Affolter
parent fa33fe6231
commit 7eb63a23b9

View File

@ -0,0 +1,102 @@
---
layout: page
title: "Telegram webhooks"
description: "Telegram webhooks support"
date: 2017-02-13 18:50
sidebar: true
comments: false
sharing: true
footer: true
logo: telegram.png
ha_category: Notifications
ha_release: 0.39
---
Telegram webhooks support as described in [docs](https://core.telegram.org/bots/webhooks).
With new component `telegram_webhooks` it is possible to send commands to home assistant via telegram bot. It works well with telegram notification: webhooks receive commands from user and notify send messages to user.
Webhook responds only to:
- users listed in configuration, in telegram user_id format.
- telegram servers (listed in webhooks [docs](https://core.telegram.org/bots/webhooks)) specified in trusted_networks
To integrate this into Home Assistant, add the following section to your `configuration.yaml` file:
```yaml
http:
base_url: <public_url>
telegram_webhooks:
api_key: ABCDEFGHJKLMNOPQRSTUVXYZ
trusted_networks:
- 149.154.167.197/32
- 149.154.167.198/31
- 149.154.167.200/29
- 149.154.167.208/28
- 149.154.167.224/29
- 149.154.167.232/31
user_id:
user1: USER_ID
user2: USER_ID
```
Configuration variables:
- **api_key** (*Optional*): the API token of your bot. If present webhook of bot is automatically registered to `public_url/api/telegram_webhooks`. If not present manual registration is required.
- **trusted_networks** (*Optional*): telegram server access ACL (default to 149.154.167.197-233)
- **user_id** (*Required*): list of user in user_id telegram format enabled to interact to webhook
Telegram webhooks raise an event `telegram.command` with a payload
```json{
'command': '/thecommand'
'args': 'strings after command'
'user_id': 12345
}
Automation example that realize simple test to command/notify interaction
```yaml
alias: 'telegram bot that reply pong to ping'
hide_entity: true
trigger:
platform: event
event_type: telegram.command
event_data:
command: '/ping'
action:
- service: notify.telegram
data:
message: 'pong'
```
Example that show keyboard interaction with notify.telegram
```yaml
trigger:
platform: event
event_type: telegram.command
event_data:
command: '/start'
action:
- service: notify.telegram
data:
message: 'commands'
data:
keyboard:
- '/ping, /alarm'
- '/siren'
```
... and an automation to trigger a related command "/siren"
```yaml
trigger:
platform: event
event_type: telegram.command
event_data:
command: '/siren'
action:
- service: homeassistant.turn_on
entity_id: switch.vision_zm1601eu5_battery_operated_siren_switch_9_0
- delay:
seconds: 10
- service: homeassistant.turn_off
entity_id: switch.vision_zm1601eu5_battery_operated_siren_switch_9_0
```