Class: HelpScout

Inherits:
Object
  • Object
show all
Defined in:
lib/help_scout.rb,
lib/help_scout/version.rb

Defined Under Namespace

Classes: NotImplementedError, ValidationError

Constant Summary collapse

HTTP_CREATED = 
201
HTTP_BAD_REQUEST = 
400
VERSION = 
"0.5.0"

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(api_key) ⇒ HelpScout

Returns a new instance of HelpScout.



13
14
15
 
# File 'lib/help_scout.rb', line 13

def initialize(api_key)
  @api_key = api_key
end

Instance Attribute Details

#last_response ⇒ Object

Returns the value of attribute last_response.



11
12
13
 
# File 'lib/help_scout.rb', line 11

def last_response
  @last_response
end

Instance Method Details

#create_conversation(data) ⇒ Object

Public: Create conversation

data - hash with data

More info: developer.helpscout.net/help-desk-api/conversations/create/

Returns conversation ID



24
25
26
27
28
29
30
31
32
33
34
35
36
37
 
# File 'lib/help_scout.rb', line 24

def create_conversation(data)
  post("conversations", { body: data })

  if last_response.code == HTTP_CREATED
    # Extract ID of created conversation from the Location header
    conversation_uri = last_response.headers["location"]
    return conversation_uri.match(/(\d+)\.json$/)[1]
  elsif last_response.code == HTTP_BAD_REQUEST
    # Validation failed so return the errors
    raise ValidationError, last_response.parsed_response["message"]
  else
    raise NotImplementedError, "Help Scout returned something that is not implemented by the help_scout gem yet: #{last_response.code}: #{last_response.parsed_response["message"] if last_response.parsed_response}"
  end
end

#create_thread(conversation_id:, thread:, imported: nil, reload: nil) ⇒ Object

Public: Creates conversation thread

conversion_id - conversation id thread - thread content to be created imported - When set to true no outgoing emails or notifications will be

generated

reload - Set to true to get the entire conversation in the result

More info: developer.helpscout.net/help-desk-api/conversations/create-thread/

Returns true if created, false otherwise



129
130
131
132
133
134
135
136
137
138
 
# File 'lib/help_scout.rb', line 129

def create_thread(conversation_id:, thread:, imported: nil, reload: nil)
  query = {}
  { reload: reload, imported: imported }.each do |key, value|
    query[key] = value unless value.nil?
  end

  post("conversations/#{conversation_id}", body: thread, query: query)

  last_response.code == HTTP_CREATED
end

#get_conversation(id) ⇒ Object

Public: Get conversation

id - conversation ID

More info: developer.helpscout.net/help-desk-api/objects/conversation/

Returns hash from HS with conversation data



46
47
48
 
# File 'lib/help_scout.rb', line 46

def get_conversation(id)
  get("conversations/#{id}")
end

#get_conversations(mailbox_id, page = 1, modified_since = nil) ⇒ Object

Public: Get conversations

mailbox_id - ID of mailbox (find these with get_mailboxes) page - integer of page to fetch (default: 1) modified_since - Only return conversations that have been modified since

this UTC datetime (default: nil)

More info: developer.helpscout.net/help-desk-api/conversations/list/

Returns hash from HS with conversation data



60
61
62
63
64
65
66
67
68
69
 
# File 'lib/help_scout.rb', line 60

def get_conversations(mailbox_id, page = 1, modified_since = nil)
  options = {
    query: {
      page: page,
      modifiedSince: modified_since,
    }
  }

  get("mailboxes/#{mailbox_id}/conversations", options)
end

#get_customer(id) ⇒ Object

Public: Get customer

id - customer id

More info: developer.helpscout.net/help-desk-api/customers/get/



95
96
97
 
# File 'lib/help_scout.rb', line 95

def get_customer(id)
  get("customers/#{id}")
end

#get_mailboxes ⇒ Object 



99
100
101
 
# File 'lib/help_scout.rb', line 99

def get_mailboxes
  get("mailboxes")
end

#reports_user_ratings(user_id, rating, start_date, end_date, options) ⇒ Object

Public: Get ratings

More info: developer.helpscout.net/help-desk-api/reports/user/ratings/ ‘rating’ parameter required: 0 (for all ratings), 1 (Great), 2 (Okay), 3 (Not Good)



107
108
109
110
111
112
113
114
115
116
 
# File 'lib/help_scout.rb', line 107

def reports_user_ratings(user_id, rating, start_date, end_date, options)
  options = {
    user: user_id,
    rating: rating,
    start: start_date,
    end: end_date,
  }

  get("reports/user/ratings", options)
end

#search_conversations(query) ⇒ Object

Public: Search for conversations

query - term to search for

More info: developer.helpscout.net/help-desk-api/search/conversations/



86
87
88
 
# File 'lib/help_scout.rb', line 86

def search_conversations(query)
  search("search/conversations", query)
end

#update_conversation(id, data) ⇒ Object

Public: Update conversation

id - conversation id data - hash with data

More info: developer.helpscout.net/help-desk-api/conversations/update/



77
78
79
 
# File 'lib/help_scout.rb', line 77

def update_conversation(id, data)
  put("conversations/#{id}", { body: data })
end

#update_customer(id, data) ⇒ Object

Public: Update Customer

id - customer id data - hash with data

More info: developer.helpscout.net/help-desk-api/customers/update/



146
147
148
 
# File 'lib/help_scout.rb', line 146

def update_customer(id, data)
  put("customers/#{id}", { body: data })
end