HipChat HTTP API Wrapper in Ruby with Capistrano hooks
Clone or download
Latest commit 523578e Mar 23, 2018
Permalink
Failed to load latest commit information.
lib Support passing query options when fetching users/rooms Aug 29, 2017
spec Add some specs for room pagination Aug 29, 2017
.coveralls.yml
.document
.gitignore
.ruby-gemset
.ruby-version
.travis.yml
Gemfile
LICENSE
README.textile
Rakefile
hipchat.gemspec
tests.py

README.textile

HipChat Wrapper

A very basic wrapper for the HipChat HTTP API.

CI Status


Coverage Status

Requirements

  • Ruby 2.0.0 or higher
  • HipChat Account, sign up here!

Installation

Gemfile

gem 'hipchat'

Install

gem install hipchat

Usage

API v1

client = HipChat::Client.new(api_token, :api_version => 'v1')
# Set http proxy
client = HipChat::Client.new(api_token, :api_version => 'v1', :http_proxy => 'http://proxy_host:proxy_port')

# '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)
# Set http proxy
client = HipChat::Client.new(api_token, :http_proxy => 'http://proxy_host:proxy_port')

# '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 = {})

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

# 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')

# Update a user status.  Available options for show are 'away', 'chat', 'dnd', 'xa'
client.user('foo@bar.org').status('this is my status',
        :name=>'Foo Bar',
        :status=>'Doing very important stuff',
        :show=>'xa',
        :mention_name=>'foo',
        :email=>'foo@barr.org')

Custom Server URL

client = HipChat::Client.new(api_token, :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:

  1. The $HIPCHAT_USER environment variable
  2. The hipchat_human capistrano var.
  3. The git user.name var.
  4. 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"]

or

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 v2
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 HipChat Server & HipChat Data Center

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 Data Center and HipChat Server

Add an “options” hash to set your URL:

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

Copyright

Copyright © 2017 Atlassian. See LICENSE for details.