Node.js module for creating bots with ICQ New BotAPI
So, recommend you to see ICQ New BotAPI documentation before working with this module. There you'll see facilities of API, which realized here. Any additional features didn't add intend...
npm i icq-bot-nodeSome dependecies will be installed with icq-bot-node. Mainly, node-fetch and form-data for queries
Bot object is ICQLife class here
const {ICQLife} = require('icq-bot-node');
const TOKEN = '000.000000000.000000000:00000000'; //dont't forget about bot token, which you must get from ICQ New special service
//
const bot = new ICQLife(TOKEN);
ICQLife constructor gets only one argument - secret bot token. At once it run checking - you'l see in console this yellow-font message:
Checking and finding information about this bot (/there will be token/)...If checking will be succesfull, console write green-font (what is surprisingly, german) message. Else, it wil be red-font message with error description, like:
Bot checking error: Error response from ICQ. Description: invalid token. Token: (/there will be your invalid token/)Checking is asynchronously, so you can use two event-prototypes of ICQLife class: onCheckSuccess and onCheckFail:
const {ICQLife} = require('icq-bot-node');
const TOKEN = '000.000000000.000000000:00000000';
//
const bot = new ICQLife(TOKEN);
bot.onCheckSuccess = (bot) => {
console.log(bot.me); //you'll know about property me further
};
bot.onCheckFail = (bot) => {
console.log(bot.me);
};
You can create several ICQLife with one token. They will be work in parallel
ICQLife class give this properties and methods:
(ICQLife).token //bot secret token (only for reading; string)
(ICQLife).me //bot information (only for reading; form after checking; object). You can see object, which stores in this property in there
(ICQLife).store //special user store (writable, defaultly - empty; object)
(ICQLife).waitings //binded waitings (you'll know about ICQWaiting in appropriate section) (only for reading, defaultly - empty; array)
(ICQLife).listen() //run event-listening of bot. It's asynchronously function and exist special ICQLife event onlisten
(ICQLife).stopListen() //pause event-listening of bot. It's asynchronously function and exist special ICQLife event onStopListen
(ICQLife).bindWaitings(/waitings array/) //bind one or more ICQWaiting classes to bot (you'll know about ICQWaiting in appropriate section). It's synchronously function, returned object with property waitingsLength, contained number of binded waitings
(ICQLife).unbindWaitings(/waiting index or nothing/) //unbind one or all ICQWaiting classes out of bot. Unbind all binded waitings on calling without argument. It's synchronously function, returned object with property waitingsLength, contained number of binded waitings
Every function of this module returns object. If it isn't any information for returning, function can return empty object. If error happends, function necessarily return object with property error. Also red-font message with error description is written in console.
const result = bot.bindWaitings(waiting1, waiting2); //there is error - waiting isn't combined in array
if (result.hasOwnProperty('error')) {
console.log('Erorr');
} else bot.listen();
Bot begins listening for events with listen(). But work with gotten events ICQWaiting class
const {ICQLife, ICQWaiting} = require('icq-bot-node');
const TOKEN = '000.000000000.000000000:00000000';
//
const waiting = new ICQWaiting('newMessage');
const bot = new ICQLife(TOKEN);
bot.onCheckSuccess = (bot) => {
bot.bindWaitings([waiting]);
bot.listen();
};
ICQWaiting constructor get one argument - waiting type. It matches event types in ICQ New BotAPI documentation (there). Here is a list of this types:
'newMessage'
'pinnedMessage'
'unpinnedMessage'
'newChatMembers'
'leftChatMembers'
'callbackQuery'
After binding with bot waitings are available in ICQLife property array waitings by index, given in order of binding:
const waiting1 = new ICQWaiting('newMessage');
const waiting2 = new ICQWaiting('editedMessage');
const waiting3 = new ICQWaiting('deletedMessage');
//
let checking = bot.bindWaitings([waiting1, waiting2, waiting3]);
if (!checking.hasOwnProperty('error')) {
console.log(bot.waitings[0].type); //'newMessage'
console.log(bot.waitings[1].type); //'editedMessage'
console.log(bot.waitings[2].type); //'deletedMessage'
};
ICQWaiting class give this properties and methods:
(ICQWaiting).type //type of waiting (only for reading; string)
(ICQWaiting).myBot //bot information (only for reading; form after binding waiting with any ICQLife; object). You can see object, which stores in this property there
(ICQWaiting).actions //binded actions (you'll know about ICQAction in appropriate section) (only for reading, defaultly - empty; array)
(ICQWaiting).conditions //special conditions, which waiting uses for detecting right event source. It is object, consisted of three writable and defaultly empty array properties:
chats (you can push id of chats, then this waiting will be ignore all events, gotten from other chats)
ignoreChats (you can push id of chats, then this waiting will be ignore all events, gotten from this chats)
typeChats (you can push type of chats, then this waiting will be ignore all events, gotten from chats of other type. There are three chat types: private, group and channel)
When all properties of conditions empty, waiting react to all gotten events
(ICQWaiting).stop() //pause waiting. It won't react to gotten events after this method calling
(ICQWaiting).run() //run waiting, which was paused
(ICQWaiting).bindActions(/actions array/) //bind one or more ICQAction classes to waiting (you'll know about ICQAction in appropriate section). It's synchronously function, returned object with property actionsLength, contained number of binded actions
(ICQWaiting).unbindActions(/action index or nothing/) //unbind one or more ICQAction classes out of waiting (you'll know about ICQAction in appropriate section). Unbind all binded actions on calling without argument. It's synchronously function, returned object with property actionsLength, contained number of binded actions
After binding to ICQLife waiting copies in ICQLife property waitings and stores by his index there. If you change original ICQWaiting class it isn't affect on binded copy. Also changings of binded waitings are ignored by original ICQWaiting
const waiting = new ICQWaiting('pinMessage');
waiting.conditions.typeChats.push('private');
//
const bot = new ICQLife(TOKEN);
bot.onCheckSuccess = () => {
bot.bindWaitings([waiting]);
bot.waitings[0].conditions.typeChats = [];
console.log(bot.waitings[0].conditions.typeChats); //[]
console.log(waiting.conditions.typeChats); //['private']
//
waitings.conditions.typeChats.push('channel');
console.log(bot.waitings[0].conditions.typeChats); //[]
console.log(waiting.conditions.typeChats); //['private', 'channel']
};
But waitings only wait for event getting and filter their. It is useless without binded actions
Bot answers events with special actions. There are two types of it: user and built-in. User actions are simple desired asynchronous functions, binded with ICQWaiting. Built-in actions are calling of special method of ICQAction object
const {ICQLife, ICQWaiting, ICQAction} = require('icq-bot-node');
const TOKEN = '000.000000000.000000000:00000000';
//
const action1 = async (bot, token, event, interResult) => { //this is user action
ICQAction.act({ //this is built-in action
actionType: 'sendText',
text: 'Hello, world!',
chatId: 'artem'
}, token);
let chance = Math.round(Math.random());
if (chance === 0) {
return false;
}
else return true;
};
const action2 = async (bot, token, event, interResult) => { //this is user action
if (!interResult) {
ICQAction.act({ //this is built-in action
actionType: 'sendText',
text: 'Unluck! I dont wont talk with you now...',
chatId: 'artem'
}, token);
bot.waitings[0].conditions.chatsId = [];
bot.waitings[0].conditions.ignoreChats.push('artem');
};
ICQAction.act({ //this is built-in action
actionType: 'sendText',
text: 'Luck! But you really play with fire...',
chatId: 'artem'
}, token);
};
//
const waiting = new ICQWaiting('newMessage');
waiting.conditions.chatsId.push('artem');
waiting.bindActions([action1, action2]);
//
const bot = new ICQLife(TOKEN);
bot.onCheckSuccess = (bot) => {
bot.bindWaitings([waiting]);
bot.listen();
};
User action get four arguments:
first argument is ICQLife class
second argument is token of this bot
third argument is object with information about gotten event. You can see examples of object, which you can meet in this argument there
four argument is returned data of last done user action
Built-in action activates with method act(), which has two arguments: object with type of action and data for action (you can see ICQ New BotAPI documentation and know about properties need for action query) and token. There is a list of action types:
'sendText'
'sendFile'
'sendVoice'
'editText'
'deleteMessages'
'sendActions'
'getChatInfo' //name of this type differs from original - you can find information about it in documentation section '/chats/getInfo'
'getFileInfo' //name of this type differs from original - you can find information about it in documentation section '/files/getInfo'
'getAdmins'
'getMembers'
'getBlockedUsers'
'getPendingUsers'
'blockUser'
'unclockUser'
'resolvePending'
'setTitle'
'setAbout'
'setRules'
'pinMessage'
'unpinMessage'
'answerCallbackQuery'
Set of properties, need for actions, equals to documentation, except sendFile and sendVoice. You can send uploaded file and write property 'fileId' or upload new file and send it. In second case you must write two properties instead of 'chatId': 'location' (local path to file) and 'fileName' (necessarilly with format)
ICQAction.act() returns object, described in ICQ New BotAPI documentation
I know, I could explain badly for public. You can write questions here, in issues or send it to me: artomich.work.1@gmail.com