Class: HipChat::API

Inherits:
Object
  • Object
show all
Includes:
HTTParty
Defined in:
lib/hipchat-api.rb,
lib/hipchat-api/version.rb

Constant Summary collapse

DEFAULT_TIMEOUT =

Default timeout of 3 seconds

3
DEFAULT_HEADERS =

Default headers for HTTP requests

{
  'User-Agent' => "HipChat gem #{VERSION}",
}
HIPCHAT_API_URL =

HipChat API URL

'https://api.hipchat.com/v1'
VERSION = 
'1.0.6'.freeze

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(token, hipchat_api_url = HIPCHAT_API_URL) ⇒ API

Create a new instance of the HipChat::API for interacting with HipChat

Parameters:

  • token (String) —

    HipChat access token

  • hipchat_api_url (String) (defaults to: HIPCHAT_API_URL) —

    HipChat API URL



33
34
35
36
 
# File 'lib/hipchat-api.rb', line 33

def initialize(token, hipchat_api_url = HIPCHAT_API_URL)
  @token = token
  @hipchat_api_url = hipchat_api_url
end

Instance Attribute Details

#hipchat_api_url ⇒ Object

HipChat API URL



24
25
26
 
# File 'lib/hipchat-api.rb', line 24

def hipchat_api_url
  @hipchat_api_url
end

#token ⇒ Object

HipChat access token



27
28
29
 
# File 'lib/hipchat-api.rb', line 27

def token
  @token
end

Instance Method Details

#debug(location = $stderr) ⇒ Object

Turn on HTTParty debugging

Parameters:

  • location (Object) (defaults to: $stderr) —

    Output “sink” for HTTP debugging



41
42
43
 
# File 'lib/hipchat-api.rb', line 41

def debug(location = $stderr)
  self.class.debug_output(location)
end

#rooms_create(name, owner_user_id, privacy = 'public', topic = '', guest_access = 0) ⇒ Object

Creates a new room.

Parameters:

  • name (String) —

    Name of the room.

  • owner_user_id (int) —

    User ID of the room’s owner.

  • privacy (String, 'public') (defaults to: 'public') —

    Privacy setting for room.

  • topic (String, '') (defaults to: '') —

    Room topic.

  • guest_access (int, 0) (defaults to: 0) —

    Whether or not to enable guest access for this room. 0 = false, 1 = true. (default: 0).

See Also:



69
70
71
72
 
# File 'lib/hipchat-api.rb', line 69

def rooms_create(name, owner_user_id, privacy = 'public', topic = '', guest_access = 0)
  self.class.post(hipchat_api_url_for('rooms/create'), :body => {:auth_token => @token, :name => name, :owner_user_id => owner_user_id,
    :topic => topic, :privacy => privacy, :guest_access => guest_access})
end

#rooms_delete(room_id) ⇒ Object

Deletes a room and kicks the current participants.

Parameters:

  • room_id (int) —

    ID of the room

See Also:



79
80
81
 
# File 'lib/hipchat-api.rb', line 79

def rooms_delete(room_id)
  self.class.post(hipchat_api_url_for('rooms/delete'), :body => {:auth_token => @token, :room_id => room_id})
end

#rooms_history(room_id, date, timezone) ⇒ Object

Fetch chat history for this room.

Parameters:

  • room_id (int) —

    ID of the room.

  • date (String) —

    Either the date to fetch history for in YYYY-MM-DD format, or “recent” to fetch the latest 50 messages.

  • timezone (String) —

    Your timezone. Must be a supported PHP timezone. (default: UTC)

See Also:



90
91
92
93
 
# File 'lib/hipchat-api.rb', line 90

def rooms_history(room_id, date, timezone)
  self.class.get(hipchat_api_url_for('rooms/history'), :query => {:auth_token => @token, :room_id => room_id, :date => date,
    :timezone => timezone})
end

#rooms_list ⇒ Object

List rooms for this group.

See Also:



98
99
100
 
# File 'lib/hipchat-api.rb', line 98

def rooms_list
  self.class.get(hipchat_api_url_for('rooms/list'), :query => {:auth_token => @token})
end

#rooms_message(room_id, from, message, notify = 0, color = 'yellow', message_format = 'html') ⇒ Object

Send a message to a room.

Parameters:

  • room_id (int) —

    ID of the room.

  • from (String) —

    Name the message will appear be sent from. Must be less than 15 characters long. May contain letters, numbers, -, _, and spaces.

  • message (String) —

    The message body. Must be valid XHTML. HTML entities must be escaped (e.g.: & instead of &). May contain basic tags: a, b, i, strong, em, br, img, pre, code. 5000 characters max.

  • notify (int) (defaults to: 0) —

    Boolean flag of whether or not this message should trigger a notification for people in the room (based on their individual notification preferences). 0 = false, 1 = true. (default: 0)

  • color (String) (defaults to: 'yellow') —

    Background color for message. One of “yellow”, “red”, “green”, “purple”, or “random”. (default: yellow)

  • message_format (String) (defaults to: 'html') —

    Determines how the message is treated by HipChat’s server and rendered inside HipChat applications. One of “html” or “text”. (default: html)

See Also:



111
112
113
114
 
# File 'lib/hipchat-api.rb', line 111

def rooms_message(room_id, from, message, notify = 0, color = 'yellow', message_format = 'html')
  self.class.post(hipchat_api_url_for('rooms/message'), :body => {:auth_token => @token, :room_id => room_id, :from => from,
    :message => message, :notify => notify, :color => color, :message_format => message_format})
end

#rooms_show(room_id) ⇒ Object

Get room details.

Parameters:

  • room_id (int) —

    ID of the room.

See Also:



132
133
134
 
# File 'lib/hipchat-api.rb', line 132

def rooms_show(room_id)
  self.class.get(hipchat_api_url_for('rooms/show'), :query => {:auth_token => @token, :room_id => room_id})
end

#rooms_topic(room_id, topic, from = 'API') ⇒ Object

Set a room’s topic. Useful for displaying statistics, important links, server status, you name it!

Parameters:

  • room_id (int) —

    ID of the room.

  • topic (String) —

    The topic body. 250 characters max.

  • from (String, 'API') (defaults to: 'API') —

    Name of the service changing the topic. (default: API).

See Also:



123
124
125
 
# File 'lib/hipchat-api.rb', line 123

def rooms_topic(room_id, topic, from = 'API')
  self.class.post(hipchat_api_url_for('rooms/topic'), :body => {:auth_token => @token, :room_id => room_id, :topic => topic, :from => from})
end

#set_http_headers(http_headers = {}) ⇒ Object

Set new HTTP headers for requests

Parameters:

  • http_headers (Hash) (defaults to: {}) —

    HTTP headers



48
49
50
51
 
# File 'lib/hipchat-api.rb', line 48

def set_http_headers(http_headers = {})
  http_headers.merge!(DEFAULT_HEADERS)
  self.class.headers(http_headers)
end

#set_timeout(timeout) ⇒ Object

Set new HTTP timeout for requests

Parameters:

  • timeout (int) —

    Timeout in seconds



56
57
58
 
# File 'lib/hipchat-api.rb', line 56

def set_timeout(timeout)
  self.class.default_timeout(timeout)
end

#users_create(email, name, title, is_group_admin = 0, password = nil, timezone = 'UTC') ⇒ Object

Create a new user in your group.

Parameters:

  • email (String) —

    User’s email.

  • name (String) —

    User’s full name.

  • title (String) —

    User’s title.

  • is_group_admin (int) (defaults to: 0) —

    Whether or not this user is an admin. 0 = false, 1 = true. (default: 0)

  • password (String, nil) (defaults to: nil) —

    User’s password. If not provided, a randomly generated password will be returned.

  • timezone (String, 'UTC') (defaults to: 'UTC') —

    User’s timezone. Must be a PHP supported timezone. (default: UTC)

See Also:



146
147
148
149
 
# File 'lib/hipchat-api.rb', line 146

def users_create(email, name, title, is_group_admin = 0, password = nil, timezone = 'UTC')
  self.class.post(hipchat_api_url_for('users/create'), :body => {:auth_token => @token, :email => email, :name => name, :title => title,
    :is_group_admin => is_group_admin, :password => password, :timezone => timezone}.reject{|key, value| value.nil?})
end

#users_delete(user_id) ⇒ Object

Delete a user.

Parameters:

  • user_id (String) —

    ID or email address of the user.

See Also:



156
157
158
 
# File 'lib/hipchat-api.rb', line 156

def users_delete(user_id)
  self.class.post(hipchat_api_url_for('users/delete'), :body => {:auth_token => @token, :user_id => user_id})
end

#users_list(include_deleted = 0) ⇒ Object

List all users in the group.

Parameters:

  • notify (bool) —

    Boolean flag of whether or not include deleted users 0 = false, 1 = true. (default: 0)

See Also:



165
166
167
168
169
 
# File 'lib/hipchat-api.rb', line 165

def users_list(include_deleted = 0)
  query = {:auth_token => @token}
  query[:include_deleted] = 1 if include_deleted == 1
  self.class.get(hipchat_api_url_for('users/list'), :query => query)
end

#users_show(user_id) ⇒ Object

Get a user’s details.

Parameters:

  • user_id (String) —

    ID or email address of the user.

See Also:



176
177
178
 
# File 'lib/hipchat-api.rb', line 176

def users_show(user_id)
  self.class.get(hipchat_api_url_for('users/show'), :query => {:auth_token => @token, :user_id => user_id})
end

#users_undelete(user_id) ⇒ Object

Undelete a user. They will be sent an email requiring them to click a link to reactivate the account.

Parameters:

  • user_id (String) —

    ID or email address of the user.

See Also:



185
186
187
 
# File 'lib/hipchat-api.rb', line 185

def users_undelete(user_id)
  self.class.post(hipchat_api_url_for('users/undelete'), :body => {:auth_token => @token, :user_id => user_id})
end

#users_update(user_id, email = nil, name = nil, title = nil, is_group_admin = nil, password = nil, timezone = nil) ⇒ Object

Update a user.

Parameters:

  • email (String) (defaults to: nil) —

    User’s email.

  • name (String) (defaults to: nil) —

    User’s full name.

  • title (String) (defaults to: nil) —

    User’s title.

  • is_group_admin (int) (defaults to: nil) —

    Whether or not this user is an admin. 0 = false, 1 = true. (default: 0)

  • password (String, nil) (defaults to: nil) —

    User’s password.

  • timezone (String, nil) (defaults to: nil) —

    User’s timezone. Must be a PHP supported timezone. (default: UTC)

See Also:



199
200
201
202
 
# File 'lib/hipchat-api.rb', line 199

def users_update(user_id, email = nil, name = nil, title = nil, is_group_admin = nil, password = nil, timezone = nil)
  self.class.post(hipchat_api_url_for('users/update'), :body => {:auth_token => @token, :user_id => user_id, :email => email,
    :name => name, :title => title, :is_group_admin => is_group_admin, :password => password, :timezone => timezone}.reject{|key, value| value.nil?})
end