icq-bot-node
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...
Installation
npm i icq-bot-nodeSome dependencies will be installed with icq-bot-node. Mainly, node-fetch and form-data for queries
Life
Creating
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 runs checking - you'll 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
Methods and properties
ICQLife class give these 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 the object, which stores in this property there
(ICQLife).store //special user store (writable, is empty default; object)
(ICQLife).waitings //bound waitings (you'll know about ICQWaiting in the appropriate section) (only for reading, is empty default; array)
(ICQLife).listen() //run event-listening of bot. It's asynchronously function. Special ICQLife event onlisten exists for beginning of listening detecting
(ICQLife).stopListen() //pause event-listening of bot. It's asynchronously function. Special ICQLife event onStopListen exist for stopping of listening detecting
(ICQLife).bindWaitings(/waitings array/) //bind one or more ICQWaiting classes to the bot (you'll know about ICQWaiting in the appropriate section). It's synchronously function, returned object with property waitingsLength, contained a number of bound waitings
(ICQLife).unbindWaitings(/waiting index or nothing/) //unbind one or all ICQWaiting classes out of bot. Unbind all bound waitings on call without argument. It's synchronously function, returned object with property waitingsLength, contained a number of bound waitings
Every function of this module returns an object. If it isn't any information for returning, the function can return an empty object. If any error happens, function necessarily returns an object with property error. Also, a red-font message with error description is written in the 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();
Waiting
Creating
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 gets one argument - waiting type. It matches event types in ICQ New BotAPI documentation (there). Here is a list of these 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'
};
Methods and properties
ICQWaiting class give these 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 the object, which stores in this property there
(ICQWaiting).actions //bound actions (you'll know about ICQAction in the appropriate section) (only for reading,
is empty default; array)
(ICQWaiting).conditions //special conditions, which waiting uses for detecting right event source. It is an object, consisted of three writable and default empty array properties:
chats (you can push id of chats, then this waiting will ignore all events, gotten from other chats)
ignoreChats (you can push id of chats, then this waiting will ignore all events, gotten from this chats)
typeChats (you can push type of chats, then this waiting will 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 reacts to all gotten events
(ICQWaiting).stop() //pause waiting. It won't react to gotten events after this method call
(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 a number of bound 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 bound actions on call without argument. It's synchronously function, returned object with property actionsLength, contained a number of bound actions
Waiting copies in ICQLife property waitings and stores by his index there after binding to ICQLife. If you change original ICQWaiting class it doesn't affect on a bound copy. Also, changings of bound 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 them. It is useless without bound actions
Action
Bot answers events with special actions. There are two types of it: user and built-in. User actions are simple desired asynchronous functions, bound with ICQWaiting. Built-in actions are calls 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 the second case, you must write two properties instead of 'chatId': 'location' (local path to file) and 'fileName' (necessarily with format)
ICQAction.act() returns object, described in ICQ New BotAPI documentation
Conclusion
You can write questions in issues or send it to me: artomich.work.1@gmail.com