Skip to content

Telegram Bot doc enhancements with callback queries and more notification options #2508

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
balloob merged 1 commit into from
May 10, 2017
Merged

Telegram Bot doc enhancements with callback queries and more notification options #2508

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
55 changes: 48 additions & 7 deletions source/_components/notify.telegram.markdown
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,8 @@ The `telegram` platform uses [Telegram](https://web.telegram.org) to delivery no
The requirements are:

- You need a [Telegram bot](https://core.telegram.org/bots). Please follow those [instructions](https://core.telegram.org/bots#6-botfather) to create one and get the token for your bot. Keep in mind that bots are not allowed to contact users. You need to make the first contact with your user. Meaning that you need to send a message to the bot from your user.
- The `chat_id` of an user.
- You need to configure a [Telegram bot in Home Assistant](/components/telegram_bot) and define there your API key and the allowed chat ids to interact with.
- The `chat_id` of an allowed user.

To retrieve your `chat_id`, contact any of the Telegram bots created for this purpose (@myidbot, @get_id_bot)

Expand All @@ -45,22 +46,51 @@ $ python3
To enable Telegram notifications in your installation, add the following to your `configuration.yaml` file:

```yaml
# Example configuration.yaml entry
# Example configuration.yaml entry for the Telegram Bot
telegram_bot:
platform: webhooks
Copy link
Copy Markdown
Member

@MartinHjelmare MartinHjelmare May 21, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think we should assume that a user has exposed the install to the outside, which is required for webhooks. Better to suggest the polling platform.

api_key: ABCDEFGHJKLMNOPQRSTUVXYZ
allowed_chat_ids:
- CHAT_ID_1
- CHAT_ID_2
- CHAT_ID_3

# Example configuration.yaml entry for the notifier
notify:
- name: NOTIFIER_NAME
platform: telegram
api_key: ABCDEFGHJKLMNOPQRSTUVXYZ
chat_id: YOUR_CHAT_ID
chat_id: CHAT_ID_2
```

Configuration variables:

- **name** (*Optional*): Setting the optional parameter `name` allows multiple notifiers to be created. The default value is `notify`. The notifier will bind to the service `notify.NOTIFIER_NAME`.
- **api_key** (*Required*): The API token of your bot.
- **chat_id** (*Required*): The chat ID of your user.

To use notifications, please see the [getting started with automation page](/getting-started/automation/).

### {% linkable_title Text message %}

```yaml
...
action:
service: notify.NOTIFIER_NAME
data:
title: '*Send a message*'
message: 'That's an example that _sends_ a *formatted* message with a custom keyboard.'
data:
keyboard:
- '/command1, /command2'
- '/command3, /command4'
```

Configuration variables:

- **message** (*Required*): Message text.
- **title** (*Optional*): Will be composed as '%title\n%message'.
- **keyboard** (*Optional*): List of rows of commands, comma-separated, to make a custom keyboard.
- **inline_keyboard** (*Optional*): List of rows of commands, comma-separated, to make a custom inline keyboard with buttons with asociated callback data.

### {% linkable_title Photo support %}

```yaml
Expand All @@ -81,10 +111,15 @@ action:
caption: I.e. for a Title
```

Configuration variables:

- **url** or **file** (*Required*): For local or remote path to an image.
- **caption** (*Optional*): The title of the image.
- **username** (*Optional*): Username for a URL which require HTTP basic authentication.
- **password** (*Optional*): Username for a URL which require HTTP basic authentication.
- **keyboard** (*Optional*): List of rows of commands, comma-separated, to make a custom keyboard.
- **inline_keyboard** (*Optional*): List of rows of commands, comma-separated, to make a custom inline keyboard with buttons with asociated callback data.


### {% linkable_title Document support %}

Expand All @@ -99,13 +134,16 @@ action:
document:
file: /tmp/whatever.odf
caption: Document Title xy

```

Configuration variables:

- **url** or **file** (*Required*): For local or remote path to a document.
- **caption** (*Optional*): The title of the document.
- **username** (*Optional*): Username for a URL which require HTTP basic authentication.
- **password** (*Optional*): Username for a URL which require HTTP basic authentication.
- **keyboard** (*Optional*): List of rows of commands, comma-separated, to make a custom keyboard.
- **inline_keyboard** (*Optional*): List of rows of commands, comma-separated, to make a custom inline keyboard with buttons with asociated callback data.

### {% linkable_title Location support %}

Expand All @@ -123,7 +161,10 @@ action:
longitude: 117.22743
```

Configuration variables:

- **location** (*Required*): For local or remote path to an image.
- **latitude** (*Required*): The latitude to send.
- **longitude** (*Required*): The longitude to send.

- **keyboard** (*Optional*): List of rows of commands, comma-separated, to make a custom keyboard.
- **inline_keyboard** (*Optional*): List of rows of commands, comma-separated, to make a custom inline keyboard with buttons with asociated callback data.
Loading