bthos / wb-telegram-bot

Телеграм-бот на wb-rules

telegram2wb

Описание

Телеграм-бот на wb-rules:

• Реагирует только на сообщения от известных ему пользователей.
• Одновременно с ботом могут работать несколько пользователей — он ответит каждому индивидуально.
• Можно добавить бота в групповой чат, тогда сообщения бота будут видны всем. Бот понимает, когда к нему обращаются, поэтому ставит в очередь только адресованные ему команды. Тип чата можно посмотреть в cmd.chatType, а список упоминаний в сообщении в cmd.mentions, имя бота можно узнать в bot.getUserName().
• Ведёт очередь команд — это полезно, если бот не мог связаться с сервером, а команды продолжали поступать.
• Понимает несколько команд в одном сообщении и их аргументы.
• Может отправлять сообщения, документы и фото. Фото и документы отправить можно только по одному в каждом сообщении.
• Игнорирует сообщения без команды.

Бот создаёт виртуальное устройство telegram2wb (Telegram Bot) с топиками:

• Enabled — переключает состояние бота.
• Debug — управляет выводом отладочных сообщений.
• Cmd — топик, куда бот записывает принятые команды.
• Callback — топик, куда бот записывает принятые данные от Inline Keyboard.
• Msg — топик, откуда бот читает сообщения, которые нужно отправить.
• rawMsg — топик, откуда бот читает необработанные сообщения, которые нужно отправить.

Команды и сообщения должны быть в формате JSON.

В боте нет логики обработки команд — это ваша задача. Подробнее смотрите в разделе «Принцип работы», а простой пример можно найти в файле example/telegram2wb-logic.js.

Установка и настройка

Бот выполнен модулем wb-rules, поэтому для установки скопируйте файл src/telegram2wb.js в папку /etc/wb-rules-modules/ и перезапустите wb-rules systemctl restart wb-rules.

После этого подключите модуль к скрипту wb-rules и инициализируйте бота:

var bot = require("telegram2wb"); // подключаем модуль

token = ""; // Токен бота, можно узнать у @BotFather 
allowUsers = ["username"]; // Пользователи, которым разрешено общаться с ботом. Можно указать несколько: ["user1", "user2", …]

bot.init(token, allowUsers);

Если у вас несколько ботов, то вы можете использовать один модуль, для этого при инициализации нужно указать разные токены и имена виртуальных устройств:

// Скрипт 1.js
var bot = require("telegram2wb"); // подключаем модуль
bot.init("token1", ["allowUser1"], "device-name-1");

// Скрипт 2.js
var bot = require("telegram2wb"); // подключаем модуль
bot.init("token2", ["allowUser1"], "device-name-2");

В этом случае каждый бот будет работать самостоятельно и не знать о существовании другого.

Для удобства модуль экспортирует несколько переменных и функций, которые использовать не обязательно:

bot.parseMode; // режим оформления отправляемых сообщений
bot.pollInterval; // интервал опроса
bot.mqttCmd; // имя топика команд
bot.mqttMsg; // имя топика сообщений
bot.mqttRawMsg; // имя топика для отправки необработанных сообщений
bot.mqttCallback; // имя топика, куда возвращаются данные от Inline Keyboard
bot.getUserName() // имя бота, полученное с сервера в формате @username

Пример работы с ботом смотрите в файле example/telegram2wb-logic.js.

Принцип работы

Бот запрашивает с сервера сообщения, выбирает из них те, что с командами и упаковывает команды в структуру:

cmd = {
    chatId: chatId, //chatId пользователя, отправившего сообщение
    chatType, // тип чата — group или private
    mentions, // упоминания — массив упоминаний в сообщении ["@username1", "@username2"]
    messageId: messageId, //идентификатор сообщения
    command: command, // полученная команда
    args: args, // аргументы команды
    rawText: rawText // исходный сообщения
  }

После разбора бот помещает команду в очередь. Если сообщение содержало несколько команд, то каждая из них будет помещена в очередь отдельно.

За аргумент бот принимает все символы, идущие после команды и до следующего слеша. Начальные и конечные пробелы отбрасываются. Поэтому, если в аргументе есть слеш, например, путь к файлу, то аргумент нужно заключить в двойные кавычки:

/getfile "/path/to/file"

Если в топике виртуального устройства Cmd записано {} и в очереди есть сообщения, то бот извлекает из очереди самую раннюю команду и публикует её в топик Cmd в JSON формате:

{"chatId":662750197,"messageId":2969,"command":"/command","args":"argument"}

Вы должны в своих скриптах подписаться на изменение топика Cmd, считывать оттуда команды и после чтения записывать в топик {}, чтобы бот мог поместить туда следующую команду.

Чтобы отправить сообщение, запишите его в JSON-строку:

{
    "chatId":662750197, 
    "text":"Текст сообщения", 
    "messageId":2969,
    "document":"/path/to/file",
    "photo":"/path/to/file",
    "keyboard": "{'keyboard':[['/cputemp'],['Close keyboard']],'resize_keyboard':true}"
}

Обязательные параметры:

• chatId — chatId пользователя, которому нужно отправить сообщение
• text — текст сообщения / описание документа или фото

Необязательные параметры:

• messageId — идентификатор сообщения, на которое нужно ответить
• document — путь к документу, который нужно отправить
• photo — путь к фото, которое нужно отправить
• keyboard — код клавиатуры, подробнее смотрите в документации.

Опубликуйте JSON-строку с сообщением в топике Msg. Бот получит строку, вытащит сообщение и отправит его, а в топик запишет {}.

Также вы можете самостоятельно сформировать JSON-строку сообщения и отправить его в топик rawMsg:

function sendRawMessage(chatId, text){
   rawMsg = {
        "method": "sendMessage",      // метод, который будет вызван: sendMessage, deleteMessage и т.п.
        "chat_id": chatId,            // параметр chat_id
        "text": "'{}'".format(text),  // параметр text
    }
    
    writeRawMsgToMqtt(rawMsg);
}

function writeRawMsgToMqtt(rawMsg) {
    dev[rawMsgTopic] = JSON.stringify(rawMsg);
}    

Здесь мы в method передаём метод, который нужно использовать для передачи параметров, а ниже идёт перечень параметров со значениями. Полный перечень методов и параметров, смотрите в описании Telegram Bot API.