public/openhab-addons
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

[telegram] Add support for sendVideo (MP4) and sendAnimation (GIF) (#8969)

Browse Source 
* Add sendVideo and sendAnimation features.
* Re-order functions to keep inline with other functions.
* Readme change to trigger new build.
* Add ability to use raw file paths to send video and animations.
* Change Paths.get to Path.of as JavaDocs recommend.
* Allow absolute paths in SendPhoto methods and update readme.md
* Support for no caption with photo.
* Add absolute path support for png and webp.
* Add all file types requested.
* Remove multiple OR and only do lowercase once.

Signed-off-by: Matthew Skinner <matt@pcmus.com>
This commit is contained in:
Matthew Skinner
2020-11-11 14:50:58 +11:00
committed by GitHub
parent 5a1428dddc
commit 7e5be7ef47
5 changed files with 236 additions and 40 deletions
Download Patch File Download Diff File Expand all files Collapse all files

49
bundles/org.openhab.binding.telegram/README.md
View File

@@ -4,9 +4,9 @@ The Telegram binding allows sending and receiving messages to and from Telegram
# Prerequisites
As described in the Telegram Bot API, this is the manual procedure needed in order to get the necessary information.
As described in the Telegram Bot API (https://core.telegram.org/bots#6-botfather), this is the manual procedure needed in order to get the necessary information.
1. Create the Bot and get the Token
1. Create a new Bot and get the Token
- On a Telegram client open a chat with BotFather.
- Send `/newbot` to BotFather and fill in all the needed information. The authentication token that is given will be needed in the next steps.
@@ -32,13 +32,15 @@ Note bots may work or not at any time so eventually you need to try another one.
- `https://api.telegram.org/bot<token>/sendMessage?chat_id=<chatId>&text=testing`
- Your Telegram-bot should send you a message with the text: `testing`
**Notice:** By default your bot will only receive messages that either start with the '/' symbol or mention the bot by username (or if you talk to it directly). However, if you add your bot to a group you must either talk to BotFather and send the command "/setprivacy" and then disable it or you give admin rights to your bot in that group. Otherwise you will not be able to receive those messages.
**Notice:** By default your bot will only receive messages that either start with the '/' symbol or mention the bot by username (or if you talk to it directly).
However, if you add your bot to a group you must either talk to BotFather and send the command "/setprivacy" and then disable it or you give admin rights to your bot in that group.
Otherwise you will not be able to receive those messages.
## Supported Things
**telegramBot** - A Telegram Bot that can send and receive messages.
The Telegram binding supports the following things which origin from the latest message sent to the Telegram bot:
The Telegram binding supports the following things which originate from the last message sent to the Telegram bot:
* message text or URL
* message date
@@ -47,22 +49,22 @@ The Telegram binding supports the following things which origin from the latest
* chat id (used to identify the chat of the last message)
* reply id (used to identify an answer from a user of a previously sent message by the binding)
Please note that the things cannot be used to send messages.
Please note that the binding channels cannot be used to send messages.
In order to send a message, an action must be used instead.
## Thing Configuration
**telegramBot** parameters:
| Property | Default | Required | Description |
|-------------------------|---------|:--------:|----------------------------------------------------------------------------------------------|
| `chatIds` | | Yes | Comma-separated list of chat ids |
| `botToken` | | Yes | authentication token |
| `parseMode` | None | No | Support for formatted messages, values: Markdown or HTML. |
| `proxyHost` | None | No | Proxy host for telegram binding. |
| `proxyPort` | None | No | Proxy port for telegram binding. |
| `proxyType` | SOCKS5 | No | Type of proxy server for telegram binding (SOCKS5 or HTTP). Default: SOCKS5 |
| `longPollingTime` | 25 | No | Timespan for long polling the telegram API |
| Property | Default | Required | Description |
|-|-|-|-|
| `chatIds` | | Yes | A list of chatIds that are entered one per line in the UI, or are comma separated values when using textual config. |
| `botToken` | | Yes | Authentication token that looks like 1122334455:AABBCCDDEEFFGG1122334455667788 |
| `parseMode` | None | No | Support for formatted messages, values: Markdown or HTML. |
| `proxyHost` | None | No | Proxy host for telegram binding. |
| `proxyPort` | None | No | Proxy port for telegram binding. |
| `proxyType` | SOCKS5 | No | Type of proxy server for telegram binding (SOCKS5 or HTTP). |
| `longPollingTime` | 25 | No | Timespan in seconds for long polling the telegram API. |
By default chat ids are bi-directionally, i.e. they can send and receive messages.
They can be prefixed with an access modifier:
@@ -84,7 +86,6 @@ telegram.thing (multiple chat ids, one bi-directional chat (ID1), one outbound-o
Thing telegram:telegramBot:Telegram_Bot [ chatIds="ID1",">ID2", botToken="TOKEN" ]
```
telegram.thing (markdown format):
```
@@ -103,7 +104,6 @@ or HTTP proxy server
Thing telegram:telegramBot:Telegram_Bot [ chatIds="ID", botToken="TOKEN", proxyHost="localhost", proxyPort="8123", proxyType="HTTP" ]
```
## Channels
| Channel Type ID | Item Type | Description |
@@ -123,7 +123,7 @@ If the message did contain an audio, photo, video or voice, the URL to retrieve
## Rule Actions
This binding includes a rule action, which allows to send Telegram messages from within rules.
This binding includes a number of rule actions, which allow the sending of Telegram messages from within rules.
```
val telegramAction = getActions("telegram","telegram:telegramBot:<uid>")
@@ -150,8 +150,18 @@ These actions will send a message to all chat ids configured for this bot.
| sendTelegram(String format, Object... args) | Sends a formatted message (See https://docs.oracle.com/javase/8/docs/api/java/util/Formatter.html for more information).
| sendTelegramQuery(String message, String replyId, String... buttons) | Sends a question to the user that can be answered via the defined buttons. The replyId can be freely choosen and is sent back with the answer. Then, the id is required to identify what question has been answered (e.g. in case of multiple open questions). The final result looks like this: ![Telegram Inline Keyboard](doc/queryExample.png). |
| sendTelegramAnswer(String replyId, String message) | Sends a message after the user has answered a question. You should *always* call this method after you received an answer. It will remove buttons from the specific question and will also stop the progress bar displayed at the client side. If no message is necessary, just pass `null` here. |
| sendTelegramPhoto(String photoURL, String caption) | Sends a picture. The URL can be specified using the http, https, and file protocols or a base64 encoded image (simple base64 data or data URI scheme). |
| sendTelegramPhoto(String photoURL, String caption) | Sends a picture. Can be one of the URL formats, see the Note below, or a base64 encoded image (simple base64 data or data URI scheme). |
| sendTelegramPhoto(String photoURL, String caption, String username, String password) | Sends a picture which is downloaded from a username/password protected http/https address. |
| sendTelegramAnimation(String animationURL, String caption) | Send animation files either GIF or H.264/MPEG-4 AVC video without sound. |
| sendTelegramVideo(String videoURL, String caption) | Send MP4 video files up to 50MB. |
**Note:** In actions that require a file URL, the following formats are acceptable:
+ http://foo.com/bar.jpg
+ https://foo.com/bar.jpg
+ file://c:\\foo\\bar.jpg
+ c:\\foo\\bar.jpg
+ /etc/openhab/html/bar.jpg
### Actions to send messages to a particular chat
@@ -336,5 +346,4 @@ then
telegramAction.sendTelegramAnswer(telegramReplyId.state.toString, "Ok, I'll leave them *on*.")
}
end
```
```