nodeICHC
A node.js module to interact with the "I Can Haz Chat" API for the purpose of creating bots.
Dependencies
- superagent - Run
npm install superagent
in console.
Usage
Including the module is simple. Just a single line is needed. Update the path to ICHC.js relative to your script.
var ICHC = require('./ICHC.js');
Creating a bot
Calling the ICHC
function creates a new bot. It takes a single parameter of an object of configuration options:
* = optional
-
user - The username of your bot
-
apiKey - The API key for your account (Don't have an API key? get one!)
-
room - The room your bot will join
-
_pingInterval_* - How often your bot will poll the server in ms. Default:
2000
(2 seconds) -
_pingTimeout_* - Number of failed pings before the bot is considered disconnected. Default:
30
-
_autoReconnect_* - Should the bot try to reconnect when disconnected? Default:
true
-
_reconnectInterval_* - How often to attempt reconnects in ms. Default:
30000
(30 seconds) -
_debug_* - Enables debug logging of all requests/repsonses from the server. Default:
false
Here's an example:
var bot = ICHC({
user: 'someusername',
apiKey: 'someapikey',
room: 'someroom'
});
Bot functions
These functions allow you to control your bot. All functions are chainable. All success/fail callback functions can use this
as a reference to the bot.
* = optional
- .connect(_success_, _fail_)** - Connects the bot to the room
- success* - Success callback function
- fail* - Fail callback function
bot.connect();
- .send(message, _success_, _fail_)** - Sends a message or command to the room
- message - Message or command to send
- success* - Success callback function
- fail* - Fail callback function
bot.send('Hello world!');
- .whisper(username, message, _success_, _fail_)** - Shortcut for /msg
- username - Username to whisper to
- message - Message to send
- success* - Success callback function
- fail* - Fail callback function
bot.whisper('SomeUser', 'Pssst! Hey you!');
- .pm(username, message, _success_, _fail_)** - Shortcut for /privmsg
- username - Username to PM
- message - Message to send
- success* - Success callback function
- fail* - Fail callback function
bot.pm('SomeUser', 'Hello there!');
- .on(eventType, eventHandler) - Binds an event handler to one or more events
- eventType - A string of one or more event types. For multiple events, seperate them by spaces
- eventHandler - Function to handle this event. The function should accept one parameter, which is an object of data about the event
// binding to a single event
bot.on('message', function(data){
console.log('Chat message recieved from ' + data.username + ': ' + data.message);
});
// binding to multiple events
bot.on('message whisper pm', function(data){
console.log('Some kind of message recieved from ' + data.username + ': ' + data.message);
});
- .off(_eventType_, _eventHandler_)** - Unbinds an event handler to one or more events
- eventType* - A string of one or more event types. For multiple events, seperate them by spaces. If this parameter is left out, it will remove all event handlers from all events
- eventHandler* - A reference to a specific event handler function. If this parameter left out, it will remove all event handlers bound to the event type
// unbinding a single event
bot.off('message', someHandler);
// unbinding all 'message' events
bot.off('message');
// unbinding all events
bot.off();
Event types
Here is a list of all available event types for .on
and .off
with descriptions of the data they pass to the event handler function. All event handlers can use this
as a reference to the bot.
All events have at least one data property eventType
, which contains the name of the event type that was triggered.
-
connect - Fires when the bot connects to the room
- (no extra event data)
-
disconnect - Fires when the bot is disconnected from the room
- (no extra event data)
-
ping - Fires whenever a ping is made to the server
- (no extra event data)
-
message - Fires when a message is recieved in chat
- username - The username who sent the message
- message - The message body
- emote - A boolean value whether or not the message was an emote (/me)
-
whisper - Fires when the bot recieves a whisper
- username - The username who sent the whisper
- message - The message body
-
pm - Fires when the bot recieves a PM
- username - The username who sent the PM
- message - The message body
-
userJoin - Fires when a user joins the room
- username - The username who joined
-
userQuit - Fires when a user leaves the room
- username - The username who left
-
userKick - Fires when a user is kicked from the room
- username - The username who was kicked
- kickedBy - The username who kicked that user
-
userCamUp - Fires when a user cams up
- username - The username who cammed up
-
userCamDown - Fires when a user cams down
- username - The username who cammed down
-
send - Fires when the bot sends a message
- message - The message that was sent
-
error - Fires when an error occurs
- message - Message containing information about the error