hipchatter
v1.0.0
Published
Wrapper for the HipChat API (v2)
Downloads
2,172
Maintainers
Readme
HipChatter
Node.js wrapper for the HipChat API (v2)
See the full HipChat API v2 Documentation at https://www.hipchat.com/docs/apiv2
You can generate an API token by going to https://hipchat.com/account/api. You must have admin access.
Source is available at http://github.com/charltoons/hipchatter.git. Pull requests welcome!
Note: This is a work-in-progress, and will improve over time.
How to Install
In your project folder:
npm install hipchatter --save
In your project's js file:
var Hipchatter = require('hipchatter');
var hipchatter = new Hipchatter(your_auth_token [, hipchat_api_root]);
// this will list all of your rooms
hipchatter.rooms(function(err, rooms){
if(!err) console.log(rooms)
});
Usage
hipchatter.<endpoint>(params, callback(err, response){
console.log(response);
});
<endpoint>
is the hipchatter function you are using.params
are the parameter required by the functionerr
error object if there is an error, null otherwiseresponse
the direct response from the HipChat API (JSON)
Documentation
hipchatter.capabilities
Returns the capabilities descriptor for HipChat.
Parameters: None
Results:
err
, error object if the request failed, null otherwisecapabilities
, an object containing the capabilities of the HipChat API
Usage
hipchatter.capabilities(function(err, capabilities){
console.log(capabilities);
});
hipchatter.rooms
Returns all of the rooms you have access to.
Parameters: None
Results: err
, array of rooms
Usage
hipchatter.rooms(function(err, rooms){
console.log(rooms);
});
hipchatter.get_room
Returns the details of a single room.
Parameters: room
(string) - the room name or id
Results:
err
, array of roomsroom_details
, an object of the rooms details
hipchatter.create_room
Creates a new room.
Parameters:
params
(object) - Required. Options for the new room.'guest_access': <bool>
- Optional. Whether or not to enable guest access for this room. Defaults to false.'name': <string>
- Required. Name of the room'owner_user_id': <string>
- User ID or email address of the room's owner.'privacy': <string>
- Whether the room is available for access by other users or not. (public
orprivate
)
Results:
err
, array of roomsroom_details
, an object of the rooms details
Usage
hipchatter.create_room({name: 'Such Room'}, function(err, room){
console.log(room);
});
hipchatter.delete_room
Delete a room.
Parameters:
room_name
(string) - Required. The name of the new room.
Results:
err
Usage
hipchatter.delete_room('Such Room', function(err){
if(!err) console.log('"Such Room" successfully deleted.');
});
hipchatter.history
The history of one room.
Parameters: room
(string) — the room name or id
Results: err
, history (object) — the history object, the messages are in history.items (array)
Usage
hipchatter.history('Hipchatter Room', function(err, history){
// print the last message
console.log(history.items[history.items.length-1].message);
});
hipchatter.users
Returns all of the users.
Parameters:
param
(object) - Optional. query string parameters (optional)'start-index': <int>
- Optional. The start index for the result set. Defaults to0
.'max-results': <int>
- Optional. The maximum number of results. Defaults to100
.'include-guests': <boolean>
- Optional. Include active guest users in response. Otherwise, no guest users will be included. Defaults to'false'
.'include-deleted': <boolean>
- Optional. Include deleted users in response. Defaults to'false'
.
Results: err
, response (array: list of users)
Usage
// default: returns array of all emoticons
hipchatter.users(function(err, users){
console.log(users);
});
hipchatter.emoticons({'start-index': 20, 'max-results': 40}, function(err, users){
console.log(users);
});
hipchatter.emoticons
Returns up to 100 emoticons.
Parameters:
param
(object) - Optional. query string parameters (optional)'start-index': <int>
- Optional. The start index for the result set. Defaults to0
.'max-results': <int>
- Optional. The maximum number of results. Defaults to100
.'type': <string>
- Optional. The type of emoticons to get. Defaults to'all'
.
param
(int) - Optional. id for single emoticon.param
(string) - Optional. shortcut for single emoticon.
Results: err
, response (array: list of emoticons) (object: single emoticon)
Usage
// default: returns array of all emoticons
hipchatter.emoticons(function(err, emoticons){
console.log(emoticons);
});
hipchatter.emoticons({'start-index': 20, 'max-results': 40, 'type': 'group'}, function(err, emoticons){
console.log(emoticons);
});
hipchatter.emoticons(34, function(err, emoticon){
console.log(emoticon);
});
hipchatter.emoticons('fonzie', function(err, emoticon){
console.log(emoticon);
});
hipchatter.get_emoticon
Get an emoticon by id or shortcut.
Parameters:
param
(int) - Required. id for single emoticon. orparam
(string) - Required. shortcut for single emoticon.
Results: err
, response (object) - single emoticon details
Usage
hipchatter.get_emoticon(34, function(err, emoticon){
console.log(emoticon);
});
hipchatter.get_emoticon('fonzie', function(err, emoticon){
console.log(emoticon);
});
}
hipchatter.notify
Send a room notification.
Parameters:
room
(string) — the room name or idoptions
(object)- message (string) - Required. Message to be sent
- token (string) - Required. The Room notification auth token. You can generate one by going to HipChat.com > Rooms tab > Click the room you want > Select Tokens [BETA] on the left-hand side > generate a new token
- color (string) - yellow (default), red, green, purple, gray, random
- message_format - html (default), text
- notify (boolean) - false (default), true
Results: err
Usage
hipchatter.notify('Hipchatter Room',
{
message: 'Hello World',
color: 'green',
token: '<room notification token>'
}, function(err){
if (err == null) console.log('Successfully notified the room.');
});
hipchatter.create_webhook
Create a webhook for HipChat to ping when a certain event happens in a room.
Parameters:
room
(string) — the room name or idoptions
(object)- url - for HipChat to ping
- pattern - regex to match message against
- event - the event to listen for.
- Valid values:
room_message
,room_notification
,room_exit
,room_enter
,room_topic_change
- Valid values:
- name - name for this webhook
Results: err
Usage
hipchatter.create_webhook('Hipchatter Room',
{
url: 'http://yourdomain.com',
event: 'room_message'
}, function(err, webhook){
if (err == null) console.log('Successfully created webhook id:'+webhook.id+'.');
});
hipchatter.get_webhook
Get the details of a specific webhook.
Parameters:
room
(string) — the room name or idwebhook_id
(string) - the id for the webhook that was returned fromcreate_webhook
Results: err
, webhook_info
Usage
hipchatter.get_webhook('Hipchatter Room', '12345', function(err, hook){
console.log(hook);
});
hipchatter.webhooks
Get all webhooks for a room.
Parameters: room
(string) — the room name or id
Results: err
, webhooks
(array)
Usage
hipchatter.webhooks('Hipchatter Room', function(err, hooks){
console.log(hooks);
});
hipchatter.delete_webhook
Remove a webhook.
Parameters:
room
(string) - the room name or idwebhook_id
(string) - the id for the webhook that was returned fromcreate_webhook
Results: err
Usage
hipchatter.delete_webhook('Hipchatter Room', '12345', function(err){
if (err == null) console.log('Webhook sucessfully deleted');
});
hipchatter.delete_all_webhooks
A convenience function to delete all webhooks associated with a room.
Parameters: room
(string) - the room name or id
Results: err
Usage
hipchatter.delete_all_webhooks('Hipchatter Room', function(err){
if (err == null) console.log('All webhooks sucessfully deleted');
});
hipchatter.set_topic
Set the topic of a room.
Parameters:
room
(string) - Required. The room name or id.topic
(string) - Required. The topic that this room will be set to.
Results: err
Usage
hipchatter.set_topic('Hipchatter Room', 'We Are All Talking About This', function(err){
if (err == null) console.log('New Topic Set');
});
TODO
- [] Get all tests to pass
- [] Migrate docs to the wiki
- [] Error events for things like rate limits
- [] Addon helpers
- [] Add support for
expand
(https://www.hipchat.com/docs/apiv2/expansion) - [] Get the tests to check if the required stubs exist before running
How to Test
- Clone this repo
- Copy
/test/settings.example.json
to/test/settings.json
- Fill out your creds and strip comments from the JSON
npm install
grunt stub
which creates the test room and test usernpm test