Skip to content

Commit

Permalink
[telegram] Add event channels and Answer overload (openhab#9251)
Browse files Browse the repository at this point in the history 
* Add event channels and Answer overload

Signed-off-by: Michael Murton <6764025+CrazyIvan359@users.noreply.github.com>
Signed-off-by: Dave J Schoepel <dave@theschoepels.com>
  • Loading branch information
@CrazyIvan359 @dschoepel
CrazyIvan359 authored and dschoepel committed Nov 9, 2021
1 parent 377e4a6 commit 604e7a7
Show file tree
Hide file tree
Showing 5 changed files with 288 additions and 38 deletions.
61 changes: 59 additions & 2 deletions bundles/org.openhab.binding.telegram/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -41,7 +41,7 @@ Otherwise you will not be able to receive those messages.

**telegramBot** - A Telegram Bot that can send and receive messages.

The Telegram binding supports the following things which originate from the last message sent to the Telegram bot:
The Telegram binding supports the following state channels which originate from the last message sent to the Telegram bot:

* message text or URL
* message date
Expand All @@ -50,6 +50,8 @@ The Telegram binding supports the following things which originate from the last
* 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)

There are also event channels that provide received messages or query callback responses as JSON payloads for easier handling in rules.

Please note that the binding channels cannot be used to send messages.
In order to send a message, an action must be used instead.

Expand Down Expand Up @@ -105,7 +107,7 @@ or HTTP proxy server
Thing telegram:telegramBot:Telegram_Bot [ chatIds="ID", botToken="TOKEN", proxyHost="localhost", proxyPort="8123", proxyType="HTTP" ]
```

## Channels
## State Channels

| Channel Type ID | Item Type | Description |
|--------------------------------------|-----------|-----------------------------------------------------------------|
Expand All @@ -122,6 +124,52 @@ Either `lastMessageText` or `lastMessageURL` are populated for a given message.
If the message did contain text, the content is written to `lastMessageText`.
If the message did contain an audio, photo, video or voice, the URL to retrieve that content can be found in `lastMessageURL`.

## Event Channels

### messageEvent

When a message is received this channel will be triggered with a simplified version of the message data as the `event`, payload encoded as a JSON string.
The following table shows the possible fields, any `null` values will be missing from the JSON payload.

| Field | Type | Description |
|------------------|--------|---------------------------------------|
| `message_id` | Long | Unique message ID in this chat |
| `from` | String | First and/or last name of sender |
| `chat_id` | Long | Unique chat ID |
| `text` | String | Message text |
| `animation_url` | String | URL to download animation from |
| `audio_url` | String | URL to download audio from |
| `document_url` | String | URL to download file from |
| `photo_url` | Array | Array of URLs to download photos from |
| `sticker_url` | String | URL to download sticker from |
| `video_url` | String | URL to download video from |
| `video_note_url` | String | URL to download video note from |
| `voice_url` | String | URL to download voice clip from |

### messageRawEvent

When a message is received this channel will be triggered with the raw message data as the `event` payload, encoded as a JSON string.
See the [`Message` class for details](https://github.com/pengrad/java-telegram-bot-api/blob/4.9.0/library/src/main/java/com/pengrad/telegrambot/model/Message.java)

### callbackEvent

When a Callback Query response is received this channel will be triggered with a simplified version of the callback data as the `event`, payload encoded as a JSON string.
The following table shows the possible fields, any `null` values will be missing from the JSON payload.

| Field | Type | Description |
|---------------|--------|------------------------------------------------------------|
| `message_id` | Long | Unique message ID of the original Query message |
| `from` | String | First and/or last name of sender |
| `chat_id` | Long | Unique chat ID |
| `callback_id` | String | Unique callback ID to send receipt confirmation to |
| `reply_id` | String | Plain text name of original Query |
| `text` | String | Selected response text from options give in original Query |

### callbackRawEvent

When a Callback Query response is received this channel will be triggered with the raw callback data as the `event` payload, encoded as a JSON string.
See the [`CallbackQuery` class for details](https://github.com/pengrad/java-telegram-bot-api/blob/4.9.0/library/src/main/java/com/pengrad/telegrambot/model/CallbackQuery.java)

## Rule Actions

This binding includes a number of rule actions, which allow the sending of Telegram messages from within rules.
Expand Down Expand Up @@ -172,6 +220,15 @@ Just put the chat id (must be a long value!) followed by an "L" as the first arg
telegramAction.sendTelegram(1234567L, "Hello world!")
```

### Advanced Callback Query Response

This binding stores the `callbackId` and recalls it using the `replyId`, but this information is lost if openHAB restarts.
If you store the `callbackId`, `chatId`, and optionally `messageId` somewhere that will be persisted when openHAB shuts down, you can use the following overload of `sendTelegramAnswer` to respond to any Callback Query.

```
telegramAction.sendTelegramAnswer(chatId, callbackId, messageId, message)
```

## Full Example

### Send a text message to telegram chat
Expand Down
5 changes: 5 additions & 0 deletions ...elegram/src/main/java/org/openhab/binding/telegram/internal/TelegramBindingConstants.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -41,4 +41,9 @@ public class TelegramBindingConstants {
public static final String LASTMESSAGEUSERNAME = "lastMessageUsername";
public static final String CHATID = "chatId";
public static final String REPLYID = "replyId";
public static final String LONGPOLLINGTIME = "longPollingTime";
public static final String MESSAGEEVENT = "messageEvent";
public static final String MESSAGERAWEVENT = "messageRawEvent";
public static final String CALLBACKEVENT = "callbackEvent";
public static final String CALLBACKRAWEVENT = "callbackRawEvent";
}
126 changes: 107 additions & 19 deletions ...binding.telegram/src/main/java/org/openhab/binding/telegram/internal/TelegramHandler.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -49,9 +49,15 @@
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

import com.google.gson.Gson;
import com.google.gson.JsonArray;
import com.google.gson.JsonElement;
import com.google.gson.JsonObject;
import com.google.gson.JsonParser;
import com.pengrad.telegrambot.TelegramBot;
import com.pengrad.telegrambot.TelegramException;
import com.pengrad.telegrambot.UpdatesListener;
import com.pengrad.telegrambot.model.CallbackQuery;
import com.pengrad.telegrambot.model.Message;
import com.pengrad.telegrambot.model.PhotoSize;
import com.pengrad.telegrambot.model.Update;
Expand All @@ -70,13 +76,12 @@
* @author Jens Runge - Initial contribution
* @author Alexander Krasnogolowy - using Telegram library from pengrad
* @author Jan N. Klug - handle file attachments
* @author Michael Murton - add trigger channel
*/
@NonNullByDefault
public class TelegramHandler extends BaseThingHandler {

@NonNullByDefault
private class ReplyKey {

final Long chatId;
final String replyId;

Expand Down Expand Up @@ -106,9 +111,9 @@ public boolean equals(@Nullable Object obj) {
}
}

private static Gson gson = new Gson();
private final List<Long> authorizedSenderChatId = new ArrayList<>();
private final List<Long> receiverChatId = new ArrayList<>();

private final Logger logger = LoggerFactory.getLogger(TelegramHandler.class);
private @Nullable ScheduledFuture<?> thingOnlineStatusJob;

Expand Down Expand Up @@ -247,6 +252,15 @@ private String getFullDownloadUrl(String fileId) {
return bot.getFullFilePath(bot.execute(new GetFile(fileId)).file());
}

private void addFileUrlsToPayload(JsonObject filePayload) {
filePayload.addProperty("file_url",
getFullDownloadUrl(filePayload.getAsJsonPrimitive("file_id").getAsString()));
if (filePayload.has("thumb")) {
filePayload.getAsJsonObject("thumb").addProperty("file_url", getFullDownloadUrl(
filePayload.getAsJsonObject("thumb").getAsJsonPrimitive("file_id").getAsString()));
}
}

private int handleUpdates(List<Update> updates) {
final TelegramBot localBot = bot;
if (localBot == null) {
Expand All @@ -267,6 +281,7 @@ private int handleUpdates(List<Update> updates) {
String replyId = null;

Message message = update.message();
CallbackQuery callbackQuery = update.callbackQuery();

if (message != null) {
chatId = message.chat().id();
Expand All @@ -278,6 +293,60 @@ private int handleUpdates(List<Update> updates) {
// chat
}

// build and publish messageEvent trigger channel payload
JsonObject messageRaw = JsonParser.parseString(gson.toJson(message)).getAsJsonObject();
JsonObject messagePayload = new JsonObject();
messagePayload.addProperty("message_id", message.messageId());
messagePayload.addProperty("from",
String.join(" ", new String[] { message.from().firstName(), message.from().lastName() }));
messagePayload.addProperty("chat_id", message.chat().id());
if (messageRaw.has("text")) {
messagePayload.addProperty("text", message.text());
}
if (messageRaw.has("animation")) {
addFileUrlsToPayload(messageRaw.getAsJsonObject("animation"));
messagePayload.add("animation_url", messageRaw.getAsJsonObject("animation").get("file_url"));
}
if (messageRaw.has("audio")) {
addFileUrlsToPayload(messageRaw.getAsJsonObject("audio"));
messagePayload.add("audio_url", messageRaw.getAsJsonObject("audio").get("file_url"));
}
if (messageRaw.has("document")) {
addFileUrlsToPayload(messageRaw.getAsJsonObject("document"));
messagePayload.add("document_url", messageRaw.getAsJsonObject("document").get("file_url"));
}
if (messageRaw.has("photo")) {
JsonArray photoURLArray = new JsonArray();
for (JsonElement photoPayload : messageRaw.getAsJsonArray("photo")) {
JsonObject photoPayloadObject = photoPayload.getAsJsonObject();
String photoURL = getFullDownloadUrl(
photoPayloadObject.getAsJsonPrimitive("file_id").getAsString());
photoPayloadObject.addProperty("file_url", photoURL);
photoURLArray.add(photoURL);
}
messagePayload.add("photo_url", photoURLArray);
}
if (messageRaw.has("sticker")) {
addFileUrlsToPayload(messageRaw.getAsJsonObject("sticker"));
messagePayload.add("sticker_url", messageRaw.getAsJsonObject("sticker").get("file_url"));
}
if (messageRaw.has("video")) {
addFileUrlsToPayload(messageRaw.getAsJsonObject("video"));
messagePayload.add("video_url", messageRaw.getAsJsonObject("video").get("file_url"));
}
if (messageRaw.has("video_note")) {
addFileUrlsToPayload(messageRaw.getAsJsonObject("video_note"));
messagePayload.add("video_note_url", messageRaw.getAsJsonObject("video_note").get("file_url"));
}
if (messageRaw.has("voice")) {
JsonObject voicePayload = messageRaw.getAsJsonObject("voice");
String voiceURL = getFullDownloadUrl(voicePayload.getAsJsonPrimitive("file_id").getAsString());
voicePayload.addProperty("file_url", voiceURL);
messagePayload.addProperty("voice_url", voiceURL);
}
triggerEvent(MESSAGEEVENT, messagePayload.toString());
triggerEvent(MESSAGERAWEVENT, messageRaw.toString());

// process content
if (message.audio() != null) {
lastMessageURL = getFullDownloadUrl(message.audio().fileId());
Expand All @@ -300,28 +369,43 @@ private int handleUpdates(List<Update> updates) {
}

// process metadata
lastMessageDate = message.date();
lastMessageFirstName = message.from().firstName();
lastMessageLastName = message.from().lastName();
lastMessageUsername = message.from().username();
} else if (update.callbackQuery() != null && update.callbackQuery().message() != null
&& update.callbackQuery().message().text() != null) {
String[] callbackData = update.callbackQuery().data().split(" ", 2);
if (lastMessageURL != null || lastMessageText != null) {
lastMessageDate = message.date();
lastMessageFirstName = message.from().firstName();
lastMessageLastName = message.from().lastName();
lastMessageUsername = message.from().username();
}
} else if (callbackQuery != null && callbackQuery.message() != null
&& callbackQuery.message().text() != null) {
String[] callbackData = callbackQuery.data().split(" ", 2);

if (callbackData.length == 2) {
replyId = callbackData[0];
lastMessageText = callbackData[1];
lastMessageDate = update.callbackQuery().message().date();
lastMessageFirstName = update.callbackQuery().from().firstName();
lastMessageLastName = update.callbackQuery().from().lastName();
lastMessageUsername = update.callbackQuery().from().username();
chatId = update.callbackQuery().message().chat().id();
replyIdToCallbackId.put(new ReplyKey(chatId, replyId), update.callbackQuery().id());
logger.debug("Received callbackId {} for chatId {} and replyId {}", update.callbackQuery().id(),
chatId, replyId);
lastMessageDate = callbackQuery.message().date();
lastMessageFirstName = callbackQuery.from().firstName();
lastMessageLastName = callbackQuery.from().lastName();
lastMessageUsername = callbackQuery.from().username();
chatId = callbackQuery.message().chat().id();
replyIdToCallbackId.put(new ReplyKey(chatId, replyId), callbackQuery.id());

// build and publish callbackEvent trigger channel payload
JsonObject callbackRaw = JsonParser.parseString(gson.toJson(callbackQuery)).getAsJsonObject();
JsonObject callbackPayload = new JsonObject();
callbackPayload.addProperty("message_id", callbackQuery.message().messageId());
callbackPayload.addProperty("from", lastMessageFirstName + " " + lastMessageLastName);
callbackPayload.addProperty("chat_id", callbackQuery.message().chat().id());
callbackPayload.addProperty("callback_id", callbackQuery.id());
callbackPayload.addProperty("reply_id", callbackData[0]);
callbackPayload.addProperty("text", callbackData[1]);
triggerEvent(CALLBACKEVENT, callbackPayload.toString());
triggerEvent(CALLBACKRAWEVENT, callbackRaw.toString());

logger.debug("Received callbackId {} for chatId {} and replyId {}", callbackQuery.id(), chatId,
replyId);
} else {
logger.warn("The received callback query {} has not the right format (must be seperated by spaces)",
update.callbackQuery().data());
callbackQuery.data());
}
}
updateChannel(CHATID, chatId != null ? new StringType(chatId.toString()) : UnDefType.NULL);
Expand Down Expand Up @@ -376,6 +460,10 @@ public void updateChannel(String channelName, State state) {
updateState(new ChannelUID(getThing().getUID(), channelName), state);
}

public void triggerEvent(String channelName, String payload) {
triggerChannel(channelName, payload);
}

@Override
public Collection<Class<? extends ThingHandlerService>> getServices() {
return Collections.singleton(TelegramActions.class);
Expand Down
Loading

0 comments on commit 604e7a7

Please sign in to comment.