HipChat Wrapper

A very basic wrapper for the HipChat HTTP API.

CI Status

Requirements

Ruby 1.9.3 or higher
HipChat Account, sign up here!

Installation

Gemfile

gem 'hipchat'

Install

gem install hipchat

Usage

API v1

client = HipChat::Client.new(api_token)
# 'username' is the name for which the message will be presented as from
client['my room'].send('username', 'I talk')

# Send notifications to users (default false)
client['my room'].send('username', 'I quit!', :notify => true)

# Color it red. or "yellow", "green", "purple", "random" (default "yellow")
client['my room'].send('username', 'Build failed!', :color => 'red')

# Have your message rendered as text in HipChat (see https://www.hipchat.com/docs/api/method/rooms/message)
client['my room'].send('username', '@coworker Build faild!', :message_format => 'text')

# Update the topic of a room in HipChat (see https://www.hipchat.com/docs/api/method/rooms/topic)
client['my room'].topic('Free Ice Cream in the kitchen')

# Change the from field for a topic update (default "API")
client['my room'].topic('Weekely sales: $10,000', :from => 'Sales Team')

# Get history from a room
client['my room'].history()

# Get history for a date in time with a particular timezone (default is latest 75 messages, timezone default is 'UTC')
client['my room'].history(:date => '2010-11-19', :timezone => 'PST')

# Create a new room, V1 requires owner_user_id (see https://www.hipchat.com/docs/api/method/rooms/create)
client.create_room("Name", :owner_user_id => 'user_id')

API v2

client = HipChat::Client.new(api_token, :api_version => 'v2')
# 'username' is the name for which the message will be presented as from
client['my room'].send('username', 'I talk')

# Send notifications to users (default false)
client['my room'].send('username', 'I quit!', :notify => true)

# Color it red. or "yellow", "green", "purple", "random" (default "yellow")
client['my room'].send('username', 'Build failed!', :color => 'red')

# Have your message rendered as text in HipChat (see https://www.hipchat.com/docs/apiv2/method/send_room_notification)
client['my room'].send('username', '@coworker Build faild!', :message_format => 'text')

# Update the topic of a room in HipChat (see https://www.hipchat.com/docs/apiv2/method/set_topic)
client['my room'].topic('Free Ice Cream in the kitchen')

# Change the from field for a topic update (default "API")
client['my room'].topic('Weekely sales: $10,000', :from => 'Sales Team')

# Get history from a room
client['my room'].history()

# Get history for a date in time with a particular timezone (default is latest 75 messages, timezone default is 'UTC')
client['my room'].history(:date => '2010-11-19', :timezone => 'PST')

# Get statistics from a room
client['my room'].statistics()

# Create a new room (see https://www.hipchat.com/docs/apiv2/method/create_room)
client.create_room("Name", options = {})

# Get room data (see https://www.hipchat.com/docs/apiv2/method/get_room)
client['my room'].get_room

# Update room data (see https://www.hipchat.com/docs/apiv2/method/update_room)
It's recommended to call client['my room'].get_room then pass in modified hash attributes to #update_room
client['my room'].update_room(options = {})

# Invite user to room (see https://www.hipchat.com/docs/apiv2/method/invite_user)
client['my room'].invite("USER_ID_OR_NAME", options = {})

# Sends a user a private message. Valid value for user are user id or email address
client.user('foo@bar.org').send('I can send private messages')

Custom Server URL

client = HipChat::Client.new(api_token, :api_version => 'v2', :server_url => 'https://domain.com')
# 'username' is the name for which the message will be presented as from
client['my room'].send('username', 'I talk')

# Send notifications to users (default false)
client['my room'].send('username', 'I quit!', :notify => true)

# Color it red. or "yellow", "green", "purple", "random" (default "yellow")
client['my room'].send('username', 'Build failed!', :color => 'red')

# Have your message rendered as text in HipChat (see https://www.hipchat.com/docs/apiv2/method/send_room_notification)
client['my room'].send('username', '@coworker Build faild!', :message_format => 'text')

# Update the topic of a room in HipChat (see https://www.hipchat.com/docs/apiv2/method/set_topic)
client['my room'].topic('Free Ice Cream in the kitchen')

# Change the from field for a topic update (default "API")
client['my room'].topic('Weekely sales: $10,000', :from => 'Sales Team')

# Get history from a room
client['my room'].history()

# Get history for a date in time with a particular timezone (default is latest 75 messages, timezone default is 'UTC')
client['my room'].history(:date => '2010-11-19', :timezone => 'PST')

# Create a new room (see https://www.hipchat.com/docs/apiv2/method/create_room)
client.create_room("Name", options = {})

# Get room data (see https://www.hipchat.com/docs/apiv2/method/get_room)
client['my room'].get_room

# Update room data (see https://www.hipchat.com/docs/apiv2/method/update_room)
It's easiest to call client['my room'].get_room, parse the json and then pass in modified hash attributes
client['my room'].update_room(options = {})

# Invite user to room (see https://www.hipchat.com/docs/apiv2/method/invite_user)
client['my room'].invite("USER_ID_OR_NAME", options = {})

# Sends a user a private message. Valid value for user are user id or email address
client.user('foo@bar.org').send('I can send private messages')

Capistrano

Capfile

require 'hipchat/capistrano'

deploy.rb

# Required
set :hipchat_token, "<your token>"
set :hipchat_room_name, "Your room" # If you pass an array such as ["room_a", "room_b"] you can send announcements to multiple rooms.
# Optional
set :hipchat_enabled, true # set to false to prevent any messages from being sent
set :hipchat_announce, false # notify users
set :hipchat_color, 'yellow' #normal message color
set :hipchat_success_color, 'green' #finished deployment message color
set :hipchat_failed_color, 'red' #cancelled deployment message color
set :hipchat_message_format, 'html' # Sets the deployment message format, see https://www.hipchat.com/docs/api/method/rooms/message
set :hipchat_options, {
  :api_version  => "v2" # Set "v2" to send messages with API v2
}

Who did it?

To determine the user that is currently running the deploy, the capistrano tasks will look for the following:

The $HIPCHAT_USER environment variable
The hipchat_human capistrano var.
The git user.name var.
The $USER environment variable.

Commit log notification (only for Capistrano 2)

Send commit log with deploy notification. We currently support git and svn.

set :hipchat_commit_log, true
# Optional
set :hipchat_commit_log_format, ":time :user\n:message\n"
set :hipchat_commit_log_time_format, "%Y/%m/%d %H:%M:%S"
set :hipchat_commit_log_message_format, "^PROJECT-\d+" # extracts ticket number from message

Rails 3 Rake Task

Send a message using a rake task:

rake hipchat:send["hello world"]

rake hipchat:send MESSAGE="hello world"

Options like the room, API token, user name and notification flag can be set in YAML.

RAILS_ROOT/config/hipchat.yml:

token: "<your token>"
room: ["Room name(s) or id(s)"] # this is an array
user: "Your name" # Default to `whoami`
notify: true # Defaults to false
api_version: "v2" # optional, defaults to v1
color: "yellow"

Engine Yard

Use a deploy hook to send messages from Engine Yard’s Cloud platform.

RAILS_ROOT/deploy/after_restart.rb:

on_app_master do
  message  = "Deploying revision #{config.active_revision} to #{config.environment_name}"
  message += " (with migrations)" if config.migrate?
  message += "."

  # Send a message via rake task assuming a hipchat.yml in your config like above
  run "cd #{config.release_path} && bundle exec rake hipchat:send MESSAGE='#{message}'"
end

Chef Handler

APIv1 ONLY, use APIv1 Key
NOTE: APIv2 required for HipChatServer Beta

Report on Chef runs.

Within a Recipe:

include_recipe 'chef_handler'

gem_package 'hipchat'

chef_handler 'HipChat::NotifyRoom' do
  action :enable
  arguments ['API_KEY', 'HIPCHAT_ROOM']
  source File.join(Gem.all_load_paths.grep(/hipchat/).first,
                   'hipchat', 'chef.rb')
end

With client.rb:

   require 'hipchat/chef'
   hipchat_handler = HipChat::NotifyRoom.new("API_KEY", "HIPCHAT_ROOM")
   exception_handlers << hipchat_handler

With HipChat Server Beta

Add an “options” hash to set api v2 and your URL:

arguments [‘API_KEY’, ‘HIPCHAT_ROOM’, options={api_version: “v2”, server_url: “https://hipchat.example.com”}]
hipchat_handler = HipChat::NotifyRoom.new(“API_KEY”, “HIPCHAT_ROOM”, options={api_version: “v2”, server_url: “https://hipchat.example.com”})

rubemz/hipchat-rb