hipchat

h1. HipChat Wrapper

A very basic wrapper for the HipChat HTTP API.

h2. CI Status

"!https://travis-ci.org/hipchat/hipchat-rb.svg!":https://travis-ci.org/hipchat/hipchat-rb !https://coveralls.io/repos/hipchat/hipchat-rb/badge.svg(Coverage Status)!:https://coveralls.io/r/hipchat/hipchat-rb

h2. Requirements

• Ruby 2.0.0 or higher
• HipChat Account, sign up "here!":https://hipchat.com/

h2. Installation

h3. Gemfile

bc. gem 'hipchat'

h3. Install

bc. gem install hipchat

h1. Usage

h2. "API v1":https://www.hipchat.com/docs/api

bc.. 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/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')

h2. "API v2":https://www.hipchat.com/docs/apiv2

bc.. client = HipChat::Client.new(api_token, :api_version => 'v2')

Set http proxy

client = HipChat::Client.new(api_token, :api_version => 'v2', :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('[e-mail]').send('I can send private messages')

Update a user status. Available options for show are 'away', 'chat', 'dnd', 'xa'

client.user('[e-mail]').status('this is my status',
:name=>'Foo Bar', :status=>'Doing very important stuff', :show=>'xa', :mention_name=>'foo', :email=>'[e-mail]')

h2. Custom Server URL

bc.. 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('[e-mail]').send('I can send private messages')

h2. Capistrano

Capfile

bc. require 'hipchat/capistrano'

deploy.rb

bc.. # Required set :hipchat_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 }

h3. 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.

h3. Commit log notification (only for Capistrano 2)

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

bc.. 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

h2. Rails 3 Rake Task

Send a message using a rake task:

bc. rake hipchat:send["hello world"]

or

bc. 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:

bc.. 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"

h2. Engine Yard

Use a "deploy hook":http://bit.ly/qnbIkP to send messages from Engine Yard's Cloud platform.

RAILS_ROOT/deploy/after_restart.rb:

bc.. 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

h2. Chef Handler

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

Report on Chef runs.

h3. Within a Recipe:

bc.. 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

h3. With client.rb:

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

h3. With HipChat Server Beta

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

• arguments ['API_KEY', 'HIPCHAT_ROOM', options={hipchat_options: {api_version: "v2", server_url: "https://hipchat.example.com"}}]
• hipchat_handler = HipChat::NotifyRoom.new("API_KEY", "HIPCHAT_ROOM", options={hipchat_options: {api_version: "v2", server_url: "https://hipchat.example.com"}})

h2. Copyright

Copyright (c) 2012 Atlassian. See LICENSE for details.