https://github.com/hipchat/hipchat-rb
HipChat HTTP API Wrapper in Ruby with Capistrano hooks
https://github.com/hipchat/hipchat-rb
Last synced: 8 months ago
JSON representation
HipChat HTTP API Wrapper in Ruby with Capistrano hooks
- Host: GitHub
- URL: https://github.com/hipchat/hipchat-rb
- Owner: hipchat
- License: mit
- Created: 2010-10-25T19:20:10.000Z (about 15 years ago)
- Default Branch: master
- Last Pushed: 2018-03-23T11:06:36.000Z (almost 8 years ago)
- Last Synced: 2025-04-14T16:56:46.240Z (9 months ago)
- Language: Ruby
- Homepage: https://www.hipchat.com/docs/apiv2
- Size: 388 KB
- Stars: 336
- Watchers: 25
- Forks: 170
- Open Issues: 12
-
Metadata Files:
- Readme: README.textile
- License: LICENSE
Awesome Lists containing this project
- awesome-ruby - hipchat-rb - HipChat HTTP API Wrapper in Ruby with Capistrano hooks. (Third-party APIs)
- fucking-awesome-ruby - hipchat-rb - HipChat HTTP API Wrapper in Ruby with Capistrano hooks. (Third-party APIs)
- awesome-ruby - hipchat-rb - HipChat HTTP API Wrapper in Ruby with Capistrano hooks. (Third-party APIs)
README
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, :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')
h2. "API v2":https://www.hipchat.com/docs/apiv2
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/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')
h2. Custom Server URL
bc.. 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')
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 v2
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 HipChat Server & HipChat Data Center
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 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"}})
h2. Copyright
Copyright (c) 2017 Atlassian. See LICENSE for details.