Telegram webhooks


Telegram chatbot webhooks implementation as described in the Telegram documentation.

Using Telegrams setWebhook method your bot’s webhook URL should be set to https://<public_url>:<port>/api/telegram_webhooks.

This is one of two bot implementations supported by Telegram. Described by Telegram as the preferred implementation but requires your Home Assistant instance to be exposed to the internet.

Configuration

To integrate this into Home Assistant, add the following section to your configuration.yaml file:

# Example configuration.yaml entry
telegram_bot:
  - platform: webhooks
    api_key: YOUR_API_KEY
    parse_mode: html
    allowed_chat_ids:
      - 12345
      - 67890

Configuration Variables

allowed_chat_ids listRequired

A list of ids representing the users and group chats that are authorized to interact with the webhook.

api_key stringRequired

The API token of your bot.

parse_mode string(Optional, default: markdown)

Default parser for messages if not explicit in message data, either html or markdown.

proxy_url string(Optional)

Proxy URL if working behind one (socks5://proxy_ip:proxy_port).

proxy_params string(Optional)

Proxy configuration parameters, as dict, if working behind a proxy (username, password, etc.).

url string(Optional)

Allow to overwrite the external URL from the Home Assistant configuration for different setups (https://<public_url>:<port>).

trusted_networks string(Optional)

Telegram server access ACL as list.

Default:

149.154.160.0/20, 91.108.4.0/22

To get your chat_id and api_key follow the instructions here. As well as authorizing the chat, if you have added your bot to a group you will also need to authorize any user that will be interacting with the webhook. When an unauthorized user tries to interact with the webhook Home Assistant will raise an error (“Incoming message is not allowed”), you can easily obtain the users id by looking in the “from” section of this error message.

Full configuration example

The configuration sample below shows how an entry can look like:

# Example configuration.yaml entry
telegram_bot:
  - platform: webhooks
    api_key: YOUR_API_KEY
    trusted_networks:
      - 149.154.160.0/20
      - 91.108.4.0/22
    allowed_chat_ids:
      - 12345
      - 67890