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);
    
    // 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 will be true if there's an error, null if there's not
• response the direct response from the HipChat API (JSON)

Documentation

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.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[items.length-1].message);
});

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, err_response

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, err_response

Usage

hipchatter.create_webhook('Hipchatter Room', 
    {
        url: 'http://yourdomain.com',
        event: 'room_message'
    }, function(err){
        if (err == null) console.log('Successfully created webhook.');
});

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, err_response

Usage

hipchatter.deleted_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, err_response

Usage

hipchatter.delete_all_webhooks('Hipchatter Room', function(err){
    if (err == null) console.log('All webhooks sucessfully deleted');
});

How to Test

• Clone this repo
• Copy /test/settings.example.json to /test/settings.json
• Fill out your creds
• npm install
• mocha -t 5000