Need help with hipchatter?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

charltoons
123 Stars 37 Forks GNU General Public License v2.0 156 Commits 5 Opened issues

Description

Node.js wrapper for the HipChat API (v2)

Services available

!
?

Need anything else?

Contributors list

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.

NPM

How to Install

In your project folder:

bash
    npm install hipchatter --save

In your project's js file: ````javascript var Hipchatter = require('hipchatter'); var hipchatter = new Hipchatter(yourauthtoken [, hipchatapiroot]);

// this will list all of your rooms
hipchatter.rooms(function(err, rooms){
    if(!err) console.log(rooms)
});
Usage
----
````javascript
    hipchatter.(params, callback(err, response){
        console.log(response);
    });
  •  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': 
      - Optional. Whether or not to enable guest access for this room. Defaults to false.
    • 'name': 
      - Required. Name of the room
    • 'owner_user_id': 
      - User ID or email address of the room's owner.
    • 'privacy': 
      - 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': 
      - Optional. The start index for the result set. Defaults to
      0
      .
    • 'max-results': 
      - Optional. The maximum number of results. Defaults to
      100
      .
    • 'include-guests': 
      - Optional. Include active guest users in response. Otherwise, no guest users will be included. Defaults to
      'false'
      .
    • 'include-deleted': 
      - 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': 
      - Optional. The start index for the result set. Defaults to
      0
      .
    • 'max-results': 
      - Optional. The maximum number of results. Defaults to
      100
      .
    • 'type': 
      - 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: ''
    }, 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

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.