icq-bot

icq-bot

Интерфейс для работы с ICQ ботами для NodeJS/TypeScript. В этом пакете я (разработчик) попытался максимально избавится от всех зависимостей и сделал максимально похожий код и интерфейс на версию "bot-python" из pip от mail.ru

Все интерфейсы ответов сервера, сущностей и доступны для работы с TypeScrip и готовы к экспорту.

Тестирование проекта выполняется с помощью фреймворка mocha.

Также имеется описание проекта на английском языке в README.EN.md доступное после скачивания.

Создержание

• Вступление
• Регистрация
• Установка
• Использование
• Пример кода
• Описание API

Вступление

Библиотека поддерживает Bot API 1.0 интерфейс и совместимый с NodeJS верси 13.10.1

Регистрация

Что бы создать собственного бота необходимо зарегистрироваться в ICQ и написать в чат Metabot команду

/newbot 

Далее следуйте инструкции.

Метобот сможет ответить вам если вы добавите его в список контактов или сами начнёте диалог.

Установка

Установка с использованием npm:

npm install icq-bot -s

Обратите внимание на актуальную мажерную версию бота

Использование

Инициализация для JS проекта

const ICQ = requier("icq-bot").default;
const TOKEN = "XXX.XXX.XXX:XXX"
const bot = new ICQ.Bot(TOKEN);

где XXX.XXX.XXX:XXX - токен, который выдал метобот в диалоге

Конструктор класса поддерживает два параметра

const options = { 
    apiUrlBase: string, 
    name:       string, 
    version:    string, 
    timeoutS:   number, 
    pollTimeS:  number
};

new ICQ.Bot(TOKEN, options);

где:

• apiUrlBase - Базовая ссылка на API. по умолчанию: https://api.icq.net/bot/v1
• name - имя бота
• version - версия бота (используется в запросах в заголовке в параметре User-Agent)
• timeoutS - Время на ответ. не используется нигде.
• pollTimeS - время максимально разрещенного запроса

Отправка сообщений чрез API

const chatId = "XXX";
bot.sendText(charID,"TEXT HERE..").then( response =>{ console.log( response.ok ) });

где XXX - номер чата

Как использовать пулинг

Для начала нужно созать обработчик. Вы можете использовать следующие обработчики (Хэндлеры): ICQ.Handler.* :

• HelpCommand - пользователь отправил команду help
• Message - пользователь отправил сообщение
• NewChatMembers - пользователь присоединился к общему чату
• LeftChatMembers - пользователь покинул чат
• PinnedMessage - пользователь закрепил запись в чате
• UnPinnedMessage - пользователь открепил запись в чате
• EditedMessage - пользователь отредактировал запись
• DeletedMessage - пользователь удалил сообщение
• Command - пользователь отправил команду в которая команда это первое слово
• StartCommand - пользователь отправил команду start
• FeedbackCommand - пользователь отправил команду "feedback текст" и в ответ администратор (указанный в параметрах обработчика) получает сообщение с номером чата и текстом
• UnknownCommand - Все не обработанные команды другими обработчиками
• BotButtonCommandHandler - пользователь нажал на кнопку с командой

Хэндлер должен быть помещён в экземпляр класса дипечер в экземпляре класса бот. Для этого в ранее созданном боте необходимо вызвать метод getDispatcher() который вернёт актуальный диспетчер.

Далее следует вызвать метод addHanler( handler: BaseHandler ) и поместить один из выше перечисленных созданных обработчиков. В примере приведен обработчик Message

let handler = new ICQ.Handler.Message(null, (bot, event) => { });
bot.getDispatcher().addHandler(handler);
bot.startPolling(); 

Как использовать фильтры для обработчиков

Вы можете использовать следующие фильтры: ICQ.Filters.* :

• message * - обработчик фильтрует только сообщения с текстом
• command * - филтрует только сообщения с префиксом команд "/" или "."
• file * - обработчик фильтрует только отправку файлов
• image * - только отправка файлов изображений
• video * - только отправка файлов видео
• audio * - только отправка файлов со звуковыми расширениями
• media * - фильтрует файлы изображений, видео и аудио
• sticker * - отправлен стикер
• url * - только ссылки в сообщениях за исключением отправки файлов
• regexp - фильтр по регулярному выражению
• mention - сообщения с упомянанием вас
• forward * - только сообщение с типом Forward (Пересланное сообщение из другого чата)
• reply * - только сообщения с типом Reply (Цитируемое сообщение)
• sender - только сообщения конкретного пользователя

Все фильтры с * возвращают уже созданные объекты. Все остальные возвращают классы.

• new ICQ.Filters.regexp(pattern: RegExp)
• new ICQ.Filters.mention(userId: Number)
• new ICQ.Filters.sender(userId: Number)

Также доступен класс FilterComposite с тремя статическими методами:

• FilterComposite.or(filter, filter)
• FilterComposite.and(filter, filter)
• FilterComposite.not (filter) На вход он принемает любые фильтры, которые будут пременяться согласно выбранного правила обработки.

let handler = new ICQ.Handler.Message(ICQ.Filter.url, (bot, event) => { 
   // code here...
});
bot.getDispatcher().addHandler(handler);
bot.startPolling(); 

Обратите внимание, что обработчики будут вызывать функцию обратного вызова каждый раз когда они подходят фильтру. Если у вас 2 обработчика, например ICQ.Handler.Message(null,... и ICQ.Handler.Message(ICQ.Filter.url,... то на сообщение со ссылкой будут вызваны оба обработчика, а на сообщение без ссылки только один обработчик.

Создание кнопок

Кнопки вынесены в отдельный класс ICQButton

let buttonOk = new ICQ.Button("Ok", "1319184")
let buttonOpenWeb = new ICQ.Button("Ok", null, "https://fake-mm.ru")

• text - Текст, который будет отображен на кнопке. Допустимо использовать \n для того, чтобы текст был на несколько строк
• callbackData - Данные, которые будут отправлены боту в момент нажатия на кнопку
• url - который необходимо открыть по нажатию на кнопку

Пример кода

Команды в терминале bash

# Создаём директорию
mkdir testBot
# Переходим в неё
cd ./testBot
# Создаём npm проект по умолчанию
npm init --force
# Устанавливаем зависимость icq-bot
npm i icq-bot -s

Далее создаём и вставляем в index.js код ниже со своим токеном.

• Файл index.js

// Импортируем бота
const ICQ = require('icq-bot').default;

// Создаём фасад пакета ICQ
const bot = new ICQ.Bot(ВАШ_ТОКЕН_БОТА);

// Создаём обработчик для новых сообщений
const handlerNewMessage = new ICQ.Handler.Message(null, (bot, event) => {
    // Получаем номер чата из объекта event
    const chatId = event.fromChatId;
    // Выводим в консоль тип события и номер чата
    console.log(`New Message event.fromChatID = ${chatId}`); 
    // Отправляем сообщение в чат отправителя
    bot.sendText(chatId, "Привет!");
});

// Создаём обработчик для удалённых сообщений
const handlerDeleteMessage = new ICQ.Handler.DeletedMessage(null, (bot, event) => { 
    // Получаем номер чата из объекта event
    const chatId = event.fromChatId;
    // Выводим в консоль тип события и номер чата
    console.log(`Deleted Message event.fromChatID = ${chatId}`); 
    // Отправляем сообщение в чат отправителя
    bot.sendText(chatId, "Зачем!");
});
 
// Получаем диспетчер бота и добавляем в него обработчики 
bot.getDispatcher().addHandler(handlerNewMessage);
bot.getDispatcher().addHandler(handlerDeleteMessage);

// Запускаем пулинг для получения команд обработчикам
bot.startPolling();
 

Далее остаётся запустить нашего бота

# Запускаем проект
node index.js

API description

• icq.com/botapi/
• agent.mail.ru/botapi/