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.
In your project folder:
npm install hipchatter --saveIn 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)
}); hipchatter.<endpoint>(params, callback(err, response){
console.log(response);
});<endpoint>is the hipchatter function you are using.paramsare the parameter required by the functionerrerror object if there is an error, null otherwiseresponsethe direct response from the HipChat API (JSON)
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
hipchatter.capabilities(function(err, capabilities){
console.log(capabilities);
});Returns all of the rooms you have access to.
Parameters: None
Results: err, array of rooms
hipchatter.rooms(function(err, rooms){
console.log(rooms);
});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
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. (publicorprivate)
Results:
err, array of roomsroom_details, an object of the rooms details
hipchatter.create_room({name: 'Such Room'}, function(err, room){
console.log(room);
});Delete a room.
Parameters:
room_name(string) - Required. The name of the new room.
Results:
err
hipchatter.delete_room('Such Room', function(err){
if(!err) console.log('"Such Room" successfully deleted.');
});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)
hipchatter.history('Hipchatter Room', function(err, history){
// print the last message
console.log(history.items[history.items.length-1].message);
});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)
// 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);
});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)
// 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);
});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
hipchatter.get_emoticon(34, function(err, emoticon){
console.log(emoticon);
});
hipchatter.get_emoticon('fonzie', function(err, emoticon){
console.log(emoticon);
});
}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
hipchatter.notify('Hipchatter Room',
{
message: 'Hello World',
color: 'green',
token: '<room notification token>'
}, function(err){
if (err == null) console.log('Successfully notified the room.');
});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
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+'.');
});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
hipchatter.get_webhook('Hipchatter Room', '12345', function(err, hook){
console.log(hook);
});Get all webhooks for a room.
Parameters: room (string) — the room name or id
Results: err, webhooks (array)
hipchatter.webhooks('Hipchatter Room', function(err, hooks){
console.log(hooks);
});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
hipchatter.delete_webhook('Hipchatter Room', '12345', function(err){
if (err == null) console.log('Webhook sucessfully deleted');
});A convenience function to delete all webhooks associated with a room.
Parameters: room (string) - the room name or id
Results: err
hipchatter.delete_all_webhooks('Hipchatter Room', function(err){
if (err == null) console.log('All webhooks sucessfully deleted');
});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
hipchatter.set_topic('Hipchatter Room', 'We Are All Talking About This', function(err){
if (err == null) console.log('New Topic Set');
});- [] 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
- Clone this repo
- Copy
/test/settings.example.jsonto/test/settings.json - Fill out your creds and strip comments from the JSON
npm installgrunt stubwhich creates the test room and test usernpm test
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent