Class: HelpScout::Client

Inherits:
Object
  • Object
show all
Includes:
HTTParty
Defined in:
lib/helpscout/client.rb

Constant Summary collapse

CONVERSATION_FILTER_STATUS_ACTIVE =

List Conversations developer.helpscout.net/conversations/

Fetches conversations in a mailbox with a given status

mailboxId Int id of the Mailbox being requested status String Filter by conversation status limit Int This function will page through 

CollectionsEnvelopes until all items are 
returned, unless a limit is specified.

modifiedSince DateTime Returns conversations that have been modified 

since the given date/time.

Possible values for status include:

  • CONVERSATION_FILTER_STATUS_ALL (Default)

  • CONVERSATION_FILTER_STATUS_ACTIVE

  • CONVERSATION_FILTER_STATUS_PENDING

Request 

REST Method: GET
URL: https://api.helpscout.net/v1/mailboxes/{mailboxId}/conversations.json

Parameters:
 Name           Type      Required  Default  Notes
 page           Int       No        1 
 status         String    No        all      Active/Pending only applies 
                                             to the following folders: 
                                             Unassigned
                                             My Tickets
                                             Drafts
                                             Assigned
 modifiedSince  DateTime  No                 Returns conversations that 
                                             have been modified since the
                                             given date/time.

Response

Name   Type
items  Array  Collection of Conversation objects. Conversation threads 
              are not returned on this call. To get the conversation 
              threads, you need to retrieve the full conversation object 
              via the Get Conversation call.

"active"
CONVERSATION_FILTER_STATUS_ALL = 
"all"
CONVERSATION_FILTER_STATUS_PENDING = 
"pending"

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(key = nil) ⇒ Client

HelpScout::Client.new

Initializes the Help Scout Client. Once called, you may use any of the HelpScout::Client methods to query the Help Scout API.

key String Help Scout API Key. Optional. If not passed, the key will be

loaded from @@settings, which defaults to helpscout.yml.



233
234
235
236
237
238
239
240
241
242
243
 
# File 'lib/helpscout/client.rb', line 233

def initialize(key = nil)
  Client.settings
  
  if key.nil?
    key = @@settings["api_key"]
  end

  # The Help Scout API uses Basic Auth, where username is your API Key. 
  # Password can be any arbitrary non-zero-length string.
  @auth = { :username => key, :password => "X" }
end

Class Method Details

.requestCount(auth, url, params = {}) ⇒ Object

Requests a collections of items from the Help Scout API. Should return the total count for this collection, or raise an error with an ErrorEnvelope.

url String A string representing the url for the REST endpoint to be 

queried.

params Hash A hash of GET parameters to use for this particular 

request.

Response

         Name    Type   Notes
Header   Status  Int    200
Body     page    Int    Current page that was passed in on the request
         pages   Int    Total number of pages available
         count   Int    Total number of objects available
         items   Array  Collection of objects



195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
 
# File 'lib/helpscout/client.rb', line 195

def self.requestCount(auth, url, params={})
  request_url = ""
  request_url << url
  if params
    query = ""
    params.each { |k,v| query += "#{k}=#{v}&" }
    request_url << "?" + query
  end

  begin
    response = Client.get(request_url, {:basic_auth => auth})
  rescue SocketError => se
    raise StandardError, se.message
  end

  if 200 <= response.code && response.code < 300
    envelope = CollectionsEnvelope.new(response)
    envelope.count
  elsif 400 <= response.code && response.code < 500
    if response["message"]
      envelope = ErrorEnvelope.new(response)
      raise StandardError, envelope.message
    else
      raise StandardError, response["error"]
    end
  else
    raise StandardError, "Server Response: #{response.code}"
  end     
end

.requestItem(auth, url, params = {}) ⇒ Object

Requests a single item from the Help Scout API. Should return either an item from the SingleItemEnvelope, or raise an error with an ErrorEnvelope.

url String A string representing the url for the REST endpoint to be

queried.

params Hash A hash of GET parameters to use for this particular 

request.

Response

         Name    Type   Notes     
Header   Status  Int    200
Body     item



85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
 
# File 'lib/helpscout/client.rb', line 85

def self.requestItem(auth, url, params={})
  item = nil

  request_url = ""
  request_url << url
  if params
    request_url << "?" + params.to_query
  end

  begin
    response = Client.get(request_url, {:basic_auth => auth})
  rescue SocketError => se
    raise StandardError, se.message
  end

  if 200 <= response.code && response.code < 300
    envelope = SingleItemEnvelope.new(response)
    if envelope.item
      item = envelope.item
    end
  elsif 400 <= response.code && response.code < 500
    if response["message"]
      envelope = ErrorEnvelope.new(response)
      raise StandardError, envelope.message
    else
      raise StandardError, response["error"]
    end
  else
    raise StandardError, "Server Response: #{response.code}"
  end

  item
end

.requestItems(auth, url, params = {}) ⇒ Object

Requests a collections of items from the Help Scout API. Should return either an array of items from the CollectionsEnvelope, or raise an error with an ErrorEnvelope.

Collections return a maximum of 50 records per page.

url String A string representing the url for the REST endpoint to be 

queried.

params Hash A hash of GET parameters to use for this particular 

request.

Response

         Name    Type   Notes     
Header   Status  Int    200
Body     page    Int    Current page that was passed in on the request
         pages   Int    Total number of pages available
         count   Int    Total number of objects available
         items   Array  Collection of objects



139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
 
# File 'lib/helpscout/client.rb', line 139

def self.requestItems(auth, url, params={})
  items = []

  request_url = ""
  request_url << url
  if params
    query = ""
    params.each { |k,v| query += "#{k}=#{v}&" }
    request_url << "?" + query
  end

  begin
    response = Client.get(request_url, {:basic_auth => auth})
  rescue SocketError => se
    raise StandardError, se.message
  end

  if 200 <= response.code && response.code < 300
    envelope = CollectionsEnvelope.new(response)
    if envelope.items
      envelope.items.each do |item|
        items << item
      end
    end
  elsif 400 <= response.code && response.code < 500
    if response["message"]
      envelope = ErrorEnvelope.new(response)
      raise StandardError, envelope.message
    else
      raise StandardError, response["error"]
    end
  else
    raise StandardError, "Server Response: #{response.code}"
  end

  items
end

.settings ⇒ Object

Returns the current Help Scout Client settings. If no settings have been loaded yet, this function will load its configuration from helpscout.yml

Settings api_key String Help Scout API Key. The API is currently available for 

paying Help Scout accounts (Basic or Standard plan). You
can generate a key from your User Profile, on the API 
Keys tab.



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

def self.settings
  if @@settings.nil?
    path = "config/helpscout.yml"
    if File.exist?(path)
      @@settings = YAML.load(ERB.new(File.new(path).read).result)
    end
  end
  @@settings
end

Instance Method Details

#attachmentData(attachmentId) ⇒ Object

Get Attachment Data developer.helpscout.net/conversations/

Fetches the AttachmentData from a given Attachment

attachmentId Int id of the Attachment being requested

Request 

REST Method: GET
URL: https://api.helpscout.net/v1/attachments/{id}/data.json

Response

Name  Type
item  Conversation::AttachmentData



690
691
692
693
694
695
696
697
698
699
 
# File 'lib/helpscout/client.rb', line 690

def attachmentData(attachmentId)
  url = "/attachments/#{attachmentId}/data.json"
  item = Client.requestItem(@auth, url, nil)
  attachmentData = nil
  if item
    attachmentData = Conversation::AttachmentData.new(item)
  end

  attachmentData
end

#conversation(conversationId) ⇒ Object

Get Conversation developer.helpscout.net/conversations/

Fetches a single Conversation

conversationId Int id of the Conversation being requested

Request 

REST Method: GET
URL: https://api.helpscout.net/v1/conversations/{id}.json

Response

Name  Type
item  Conversation



433
434
435
436
437
438
439
440
441
442
443
444
445
 
# File 'lib/helpscout/client.rb', line 433

def conversation(conversationId)
  url = "/conversations/#{conversationId}.json"

  begin
    item = Client.requestItem(@auth, url, nil)
    conversation = nil
    if item
      conversation = Conversation.new(item)
    end
  rescue StandardError => e
    print "Could not fetch conversation with id #{conversationId}: " + e.message
  end
end

#conversationCount(mailboxId, status, modifiedSince) ⇒ Object

Conversation Count developer.helpscout.net/conversations/

Returns a count for conversations in a mailbox with a given status

mailboxId Int id of the Mailbox being requested status String Filter by conversation status modifiedSince DateTime id of the Mailbox being requested

Possible values for status include:

  • CONVERSATION_FILTER_STATUS_ALL (Default)

  • CONVERSATION_FILTER_STATUS_ACTIVE

  • CONVERSATION_FILTER_STATUS_PENDING

Request 

REST Method: GET
URL: https://api.helpscout.net/v1/mailboxes/{mailboxId}/conversations.json

Parameters:
 Name           Type      Required  Default  Notes
 page           Int       No        1 
 status         String    No        all      Active/Pending only applies 
                                             to the following folders: 
                                             Unassigned
                                             My Tickets
                                             Drafts
                                             Assigned
 modifiedSince  DateTime  No                 Returns conversations that 
                                             have been modified since the
                                             given date/time.

Response

Name   Type
count  Integer  Count of Conversation objects.



650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
 
# File 'lib/helpscout/client.rb', line 650

def conversationCount(mailboxId, status, modifiedSince)
  url = "/mailboxes/#{mailboxId}/conversations.json"

  page = 1
  options = {}

  if status && (status == CONVERSATION_FILTER_STATUS_ACTIVE || status == CONVERSATION_FILTER_STATUS_ALL || status == CONVERSATION_FILTER_STATUS_PENDING)
    options["status"] = status
  end

  if modifiedSince
    options["modifiedSince"] = modifiedSince
  end

  conversations = []

  begin
    options["page"] = page
    count = Client.requestCount(@auth, url, options)
  rescue StandardError => e
    print "Conversation Count Request failed: " + e.message
  end
end

#conversations(mailboxId, status, limit = 0, modifiedSince) ⇒ Object 



494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
 
# File 'lib/helpscout/client.rb', line 494

def conversations(mailboxId, status, limit=0, modifiedSince)
  url = "/mailboxes/#{mailboxId}/conversations.json"

  page = 1
  options = {}

  if limit < 0
    limit = 0
  end

  if status && (status == CONVERSATION_FILTER_STATUS_ACTIVE || status == CONVERSATION_FILTER_STATUS_ALL || status == CONVERSATION_FILTER_STATUS_PENDING)
    options["status"] = status
  end

  if modifiedSince
    options["modifiedSince"] = modifiedSince
  end

  conversations = []

  begin
    options["page"] = page
    items = Client.requestItems(@auth, url, options)
    items.each do |item|
      conversations << Conversation.new(item)
    end
    page = page + 1
  rescue StandardError => e
    print "List Conversations Request failed: " + e.message
  end while items && items.count > 0 && (limit == 0 || conversations.count < limit)

  if limit > 0 && conversations.count > limit
    conversations = conversations[0..limit-1]
  end

  conversations
end

#conversationsInFolder(mailboxId, folderId, status, limit = 0, modifiedSince) ⇒ Object

List Conversations in Folder developer.helpscout.net/conversations/

Return conversations in a specific folder of a mailbox.

mailboxId Int id of the Mailbox being requested folderId Int id of the Folder being requested status String Filter by conversation status limit Int This function will page through 

CollectionsEnvelopes until all items are 
returned, unless a limit is specified.

modifiedSince DateTime Returns conversations that have been modified 

since the given date/time.

Possible values for status include:

  • CONVERSATION_FILTER_STATUS_ALL (Default)

  • CONVERSATION_FILTER_STATUS_ACTIVE

  • CONVERSATION_FILTER_STATUS_PENDING

Request 

REST Method: GET
URL: https://api.helpscout.net/v1/mailboxes/{mailboxId}/folders/{folderId}/conversations.json

Parameters:
 Name           Type      Required  Default  Notes
 page           Int       No        1 
 status         String    No        all      Active/Pending only applies 
                                             to the following folders: 
                                             Unassigned
                                             My Tickets
                                             Drafts
                                             Assigned
 modifiedSince  DateTime  No                 Returns conversations that 
                                             have been modified since the
                                             given date/time.

Response

Name   Type
items  Array  Collection of Conversation objects. Conversation threads 
              are not returned on this call. To get the conversation 
              threads, you need to retrieve the full conversation object 
              via the Get Conversation call.



576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
 
# File 'lib/helpscout/client.rb', line 576

def conversationsInFolder(mailboxId, folderId, status, limit=0, modifiedSince)
  url = "/mailboxes/#{mailboxId}/folders/#{folderId}/conversations.json"

  page = 1
  options = {}

  if limit < 0
    limit = 0
  end

  if status && (status == CONVERSATION_FILTER_STATUS_ACTIVE || status == CONVERSATION_FILTER_STATUS_ALL || status == CONVERSATION_FILTER_STATUS_PENDING)
    options["status"] = status
  end

  if modifiedSince
    options["modifiedSince"] = modifiedSince
  end

  conversations = []

  begin
    options["page"] = page
    items = Client.requestItems(@auth, url, options)
    items.each do |item|
      conversations << Conversation.new(item)
    end
    page = page + 1
  rescue StandardError => e
    print "List Conversations In Folder Request failed: " + e.message
  end while items && items.count > 0 && (limit == 0 || conversations.count < limit)

  if limit > 0 && conversations.count > limit
    conversations = conversations[0..limit-1]
  end

  conversations
end

#customer(customerId) ⇒ Object

Get Customer developer.helpscout.net/customers/

Fetches a single Customer

customerId Int id of the Customer being requested

Request 

REST Method: GET
URL: https://api.helpscout.net/v1/customers/{id}.json

Response

Name  Type
item  Customer



717
718
719
720
721
722
723
724
725
726
 
# File 'lib/helpscout/client.rb', line 717

def customer(customerId)
  url = "/customers/#{customerId}.json"
  item = Client.requestItem(@auth, url, nil)
  customer = nil
  if item
    customer = Customer.new(item)
  end

  customer
end

#customers ⇒ Object

List Customers developer.helpscout.net/customers/

Fetches all customers. Customers are returned by createdAt date, from newest to oldest.

Request 

REST Method: GET
URL: https://api.helpscout.net/v1/customers.json

Parameters:
 Name           Type      Required  Default  Notes
 page           Int       No        1

Response

Name   Type
items  Array  Collection of Customer objects.



747
748
749
750
751
752
753
754
755
756
 
# File 'lib/helpscout/client.rb', line 747

def customers
  url = "/customers.json"
  items = Client.requestItems(@auth, url, :page => 1)
  customers = []
  items.each do |item|
    customers << Customer.new(item)
  end

  customers
end

#foldersInMailbox(mailboxId) ⇒ Object

Get Folders developer.helpscout.net/mailboxes/

Fetches all Folders in a given mailbox

mailboxId Int id of the Mailbox being requested

Request 

REST Method: GET
URL: https://api.helpscout.net/v1/mailboxes/{id}/folders.json

Parameters:
 Name  Type  Required  Default  Notes
 page  Int   No        1

Response

Name   Type
items  Array  Collection of Mailbox objects



407
408
409
410
411
412
413
414
415
 
# File 'lib/helpscout/client.rb', line 407

def foldersInMailbox(mailboxId)
  url = "/mailboxes/#{mailboxId}/folders.json"
  items = Client.requestItems(@auth, url, :page => 1)
  folders = []
  items.each do |item|
    folders << Folder.new(item)
  end
  folders
end

#mailbox(mailboxId) ⇒ Object

Get Mailbox developer.helpscout.net/mailboxes/

Fetches a single Mailbox

mailboxId Int id of the Mailbox being requested

Request 

REST Method: GET
URL: https://api.helpscout.net/v1/mailboxes/{id}.json

Response

Name  Type
item  Mailbox



377
378
379
380
381
382
383
384
385
 
# File 'lib/helpscout/client.rb', line 377

def mailbox(mailboxId)
  url = "/mailboxes/#{mailboxId}.json"
  item = Client.requestItem(@auth, url, nil)
  mailbox = nil
  if item
    mailbox = Mailbox.new(item)
  end
  mailbox
end

#mailboxes ⇒ Object

List Mailboxes developer.helpscout.net/mailboxes/

Fetches all mailboxes

Request 

REST Method: GET
URL: https://api.helpscout.net/v1/mailboxes.json

Parameters:
 Name  Type  Required  Default  Notes
 page  Int   No        1

Response

Name   Type
items  Array  Collection of Mailbox objects



347
348
349
350
351
352
353
354
355
356
357
358
359
 
# File 'lib/helpscout/client.rb', line 347

def mailboxes
  url = "/mailboxes.json"
  mailboxes = []
  begin
    items = Client.requestItems(@auth, url, {})
    items.each do |item|
      mailboxes << Mailbox.new(item)
    end
  rescue StandardError => e
    print "List Mailbox Request failed: " + e.message
  end
  mailboxes
end

#user(userId) ⇒ Object

Get User developer.helpscout.net/users/

Fetches a single user by id.

userId Int id of the User being requested

Request 

REST Method: GET
URL: https://api.helpscout.net/v1/users/{id}.json

Response

Name  Type
item  User



261
262
263
264
265
266
267
268
269
 
# File 'lib/helpscout/client.rb', line 261

def user(userId)
  url = "/users/#{userId}.json"
  item = Client.requestItem(@auth, url, nil)
  user = nil
  if item
    user = User.new(item)
  end
  user
end

#users ⇒ Object

List Users developer.helpscout.net/users/

Fetches all users

Request 

REST Method: GET
URL: https://api.helpscout.net/v1/users.json

Parameters:
 Name  Type  Required  Default  Notes
 page  Int   No        1

Response

Name   Type
items  Array  Collection of User objects



289
290
291
292
293
294
295
296
297
 
# File 'lib/helpscout/client.rb', line 289

def users
  url = "/users.json"
  items = Client.requestItems(@auth, url, :page => 1)
  users = []
  items.each do |item|
    users << User.new(item)
  end
  users
end

#usersInMailbox(mailboxId) ⇒ Object

List Users by Mailbox developer.helpscout.net/users/

Fetches all users in a single mailbox

mailboxId Int id of the Mailbox being requested

Request 

REST Method: GET
URL: https://api.helpscout.net/v1/mailboxes/{id}/users.json

Parameters:
 Name  Type  Required  Default  Notes
 page  Int   No        1

Response

Name   Type
items  Array  Collection of User objects



319
320
321
322
323
324
325
326
327
 
# File 'lib/helpscout/client.rb', line 319

def usersInMailbox(mailboxId)
  url ="/mailboxes/#{mailboxId}/users.json"
  items = Client.requestItems(@auth, url, :page => 1)
  users = []
  items.each do |item|
    users << User.new(item)
  end
  users
end