====== Работа с Telegram API внутри OpenSCADA. ======


Для чего это надо? Я бы использовал только для уведомлений. Некоторые, возможно, захотят и управление реализовывать через команды боту. Минимально для работы нужно реализовать два метода: отправка сообщения и прием.

Всю базовую информацию по созданию ботов в Telegram можно прочитать в тысяче статей по всему интернету, но если парой слов, то для создания бота вам нужно написать @BotFather и получить ключ API.

===== Подготовка к работе =====

Требуется создать транспорт для общения с серверами Telegram. Для этого в дереве проекта переходим в раздел ''Транспорты > SSL'' и создаем выходной транспорт. Имя можно выбрать любое, но в библиотеке, приложенной к статье, используется имя по умолчанию ''Telegram''. Требуется именно SSL, а не просто сокет.

В транспорте нельзя указывать протокол HTTPS, но известно, что для обмена через HTTPS используется порт 443. Адрес у транспорта указываем следующий:
<code>api.telegram.org:443</code> 

===== Отправка сообщения =====

Для отправки используется метод ''sendMessage'' [[https://core.telegram.org/method/messages.sendMessage|Telegram API]]. В качестве аргументов ему требуется передать ''chat_id'' и текст. Аргументов может быть и больше, но в базовом варианте, когда передаем только текст, этого достаточно.

В коде ниже есть 4 переменных.
|Имя|Тип|Описание|
|Transport|Строка|Имя транспорта в "Транспорты > SSL"|
|APIKey|Строка|Ключ, полученный от @BotFather|
|ChatID|Целочисленный|Уникальный идентификатор переписки|
|Message|Строка|Текст сообщения|

<code java>
tr = SYS.Transport.SSL.nodeAt("out_" + Transport);

req = SYS.XMLNode("POST");
req.setAttr("URI", "/bot" + APIKey + "/sendMessage");
req.childAdd("cnt").setAttr("name", "chat_id").setText(ChatID.toString());
req.childAdd("cnt").setAttr("name", "text").setText(Message);
req.childAdd("cnt").setAttr("name", "disable_notification").setText("true");
tr.messIO(req,"HTTP");
</code>

===== Получение сообщений =====

Для получения сообщений используется метод ''getUpdates'' [[https://telegram-bot-sdk.readme.io/reference/getupdates|Telegram API]]. Ответы от сервера приходят в формате JSON. Данный формат не поддерживается "из коробки", однако сообществом разработана [[json|библиотека]], которая преобразует JSON строку в объект, с которым удобно работать в JavaLikeCalc.

В коде ниже используются 3 переменных.
|Имя|Тип|Описание|
|Transport|Строка|Имя транспорта в "Транспорты > SSL"|
|APIKey|Строка|Ключ, полученный от @BotFather|
|updateId|Целочисленный|ID последнего полученного сообщения, при первом запуске значение 0|

<code java>
jsonLib = SYS.DAQ.JavaLikeCalc.lib_Json;

tr = SYS.Transport.SSL.nodeAt("out_" + Transport);

messagesCount = 1;

while(messagesCount){
    updateId += 1;
    req = SYS.XMLNode("POST");
    req.setAttr("URI", "/bot" + APIKey + "/getUpdates");
    req.childAdd("cnt").setAttr("name", "offset").setText(updateId.toString());
    tr.messIO(req,"HTTP");

    deser_err = "";
    outputObject = jsonLib.deserialize(req.text(), deser_err);

    messagesCount = outputObject.result.length;
    for (var i = 0; i < outputObject.result.length; i++){
        item = outputObject.result[i];
        updateId = max(updateId, item.update_id);
        username = item.message.from.username;
        chatID = item.message.from.id;
        messageText = item.message.text;
    }
}
</code>

Данный код будет загружать все доступные сообщения. Между вызовами требуется хранить последнее значение ''updateId'', так как этот параметр позволяет пропускать уже обработанные сообщения