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

hipchatter hipchatter copied to clipboard

Metadata

HipChatter

How to Install

Usage

Documentation

hipchatter.capabilities

Usage

hipchatter.rooms

Usage

hipchatter.get_room

hipchatter.create_room

Usage

hipchatter.delete_room

Usage

hipchatter.history

Usage

hipchatter.users

Usage

hipchatter.emoticons

Usage

hipchatter.get_emoticon

Usage

hipchatter.notify

Usage

hipchatter.create_webhook

Usage

hipchatter.get_webhook

Usage

hipchatter.webhooks

Usage

hipchatter.delete_webhook

Usage

hipchatter.delete_all_webhooks

Usage

hipchatter.set_topic

Usage

TODO

How to Test

← Metadata

Owner

Metadata

hipchatter
hipchatter copied to clipboard