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 function
• err error object if there is an error, null otherwise
• response 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 otherwise
• capabilities, 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 rooms
• room_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 or private)

Results:

• err, array of rooms
• room_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 to 0.
  • 'max-results': <int> - Optional. The maximum number of results. Defaults to 100.
  • '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.

HipChat API reference

Parameters:

• param (object) - Optional. query string parameters (optional)
  • 'start-index': <int> - Optional. The start index for the result set. Defaults to 0.
  • 'max-results': <int> - Optional. The maximum number of results. Defaults to 100.
  • '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.

HipChat API reference

Parameters:

• param (int) - Required. id for single emoticon. or
• param (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 id
• options (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 id
• options (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
  • 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 id
• webhook_id (string) - the id for the webhook that was returned from create_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 id
• webhook_id (string) - the id for the webhook that was returned from create_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 user
• npm test