diff --git a/source/_components/telegram_bot.markdown b/source/_components/telegram_bot.markdown
new file mode 100644
index 00000000000..8d51d6d9112
--- /dev/null
+++ b/source/_components/telegram_bot.markdown
@@ -0,0 +1,81 @@
+---
+layout: page
+title: "Telegram chatbot"
+description: "Telegram chatbot support"
+date: 2017-04-05 18:50
+sidebar: true
+comments: false
+sharing: true
+footer: true
+logo: telegram.png
+ha_release: 0.42
+---
+
+Use Telegram on your mobile device to send messages or commands to your Home Assistant.
+
+
+A command looks like `/thecommand`
+
+When received by hass it will fire a `telegram.command` event on the event bus with the following `event_data`:
+
+```yaml
+command: "/thecommand"
+args: "<any other text following the command>"
+from_first: "<first name of the sender>"
+from_last: "<last name of the sender>"
+user_id: "<id of the sender>"
+```
+
+### {% linkable_title Configuration samples %}
+
+
+Simple ping pong example.
+
+```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.notify
+    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
+```
diff --git a/source/_components/telegram_bot.polling.markdown b/source/_components/telegram_bot.polling.markdown
new file mode 100644
index 00000000000..6536e349ada
--- /dev/null
+++ b/source/_components/telegram_bot.polling.markdown
@@ -0,0 +1,38 @@
+---
+layout: page
+title: "Telegram polling"
+description: "Telegram polling support"
+date: 2017-04-05 18:50
+sidebar: true
+comments: false
+sharing: true
+footer: true
+logo: telegram.png
+ha_category: Telegram chatbot
+ha_release: 0.42
+---
+
+Telegram chatbot polling implementation.
+
+One of two bot implementations supported by Telegram. Your hass does not have to be exposed to the internet.
+
+To integrate this into Home Assistant, add the following section to your `configuration.yaml` file:
+
+```yaml
+# Example configuration.yaml entry
+
+telegram_bot:
+  platform: polling
+  api_key: <telegram api key>
+  allowed_chat_ids:
+    - 12345
+    - 67890
+```
+
+Configuration variables:
+
+- **allowed_chat_ids** (*Required*): A list of user in the `user_id` Telegram format enabled to interact to webhook
+- **api_key** (*Required*): The API token of your bot.
+
+To get your `chat_id` and `api_key` follow the instructions [here](/components.notify.telegram) .
+
diff --git a/source/_components/telegram_bot.webhooks.markdown b/source/_components/telegram_bot.webhooks.markdown
new file mode 100644
index 00000000000..7b2dfe387dc
--- /dev/null
+++ b/source/_components/telegram_bot.webhooks.markdown
@@ -0,0 +1,61 @@
+---
+layout: page
+title: "Telegram webhooks"
+description: "Telegram webhooks support"
+date: 2017-04-05 18:50
+sidebar: true
+comments: false
+sharing: true
+footer: true
+logo: telegram.png
+ha_category: Telegram chatbot
+ha_release: 0.42
+---
+
+Telegram chatbot webhooks implementation as described in [docs](https://core.telegram.org/bots/webhooks).
+
+One of two bot implementations supported by Telegram. Described by Telegram as the preferred implementation but requires your hass instance to be exposed to the internet.
+
+To integrate this into Home Assistant, add the following section to your `configuration.yaml` file:
+
+```yaml
+# Example configuration.yaml entry
+http:
+  base_url: <public_url> # the hass https url which is exposed to the internet.
+
+telegram_bot:
+  platform: webhooks
+  api_key: telegram api key
+  allowed_chat_ids:
+    - 12345
+    - 67890
+```
+
+Configuration variables:
+
+- **allowed_chat_ids** (*Required*): A list of user in the `user_id` Telegram format enabled to interact to webhook
+- **api_key** (*Required*): The API token of your bot.
+- **trusted_networks** (*Optional*): Telegram server access ACL as list. Defaults to `149.154.167.197-233`.
+
+To get your `chat_id` and `api_key` follow the instructions [here](/components.notify.telegram) .
+
+Full configuration sample:
+
+```yaml
+# Example configuration.yaml entry
+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
+  allowed_chat_ids:
+    - 12345
+    - 67890
+```
\ No newline at end of file