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 http://developer.helpscout.net/conversations/list/

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.



265
266
267
268
269
270
271
272
273
274
275
 
# File 'lib/helpscout/client.rb', line 265

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

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

Sends a POST request to create a single item from the Help Scout API.

url String A string representing the url to POST. params Hash A hash of POST parameters to use for this particular request.

Response Name Type Notes Location String https://api.helpscout.net/v1/conversations/id.json



238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
 
# File 'lib/helpscout/client.rb', line 238

def self.create_item(auth, url, params = {})
  begin
    response = Client.post(url, {:basic_auth => auth, :headers => { 'Content-Type' => 'application/json' }, :body => params })
  rescue SocketError => se
    raise StandardError, se.message
  end

  if response.code == 201
    if response["item"]
      response["item"]
    else
      response["Location"]
    end
  else
    raise StandardError.new("Server Response: #{response.code} #{response.message}")
  end
end

.request_count(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



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
224
225
 
# File 'lib/helpscout/client.rb', line 197

def self.request_count(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

.request_item(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
118
119
 
# File 'lib/helpscout/client.rb', line 85

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

  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 = 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

.request_items(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



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
176
177
 
# File 'lib/helpscout/client.rb', line 141

def self.request_items(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

#attachment_data(attachmentId) ⇒ Object

Get Attachment Data http://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



765
766
767
768
769
770
771
772
773
774
 
# File 'lib/helpscout/client.rb', line 765

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

  attachmentData
end

#conversation(conversationId) ⇒ Object

Get Conversation http://developer.helpscout.net/conversations/get/

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



469
470
471
472
473
474
475
476
477
478
479
480
481
 
# File 'lib/helpscout/client.rb', line 469

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

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

#conversation_count(mailboxId, status, modifiedSince) ⇒ Object

Conversation Count http://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.



725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
 
# File 'lib/helpscout/client.rb', line 725

def conversation_count(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.request_count(@auth, url, options)
  rescue StandardError => e
    puts "Conversation Count Request failed: #{e.message}"
  end
end

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



569
570
571
572
573
574
575
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
 
# File 'lib/helpscout/client.rb', line 569

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.request_items(@auth, url, options)
    items.each do |item|
      conversations << Conversation.new(item)
    end
    page = page + 1
  rescue StandardError => e
    puts "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

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

List Conversations in Folder http://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.



651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
 
# File 'lib/helpscout/client.rb', line 651

def conversations_in_folder(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.request_items(@auth, url, options)
    items.each do |item|
      conversations << Conversation.new(item)
    end
    page = page + 1
  rescue StandardError => e
    puts "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

#create_conversation(conversation) ⇒ Object

Create Conversation http://developer.helpscout.net/conversations/create/

Creates a new Conversation.

Request REST Method: POST URL: https://api.helpscout.net/v1/conversations.json

POST Parameters Name Type Required Notes conversation Conversation Yes
import boolean No The import parameter enables conversations to be created for historical purposes (i.e. if moving from a different platform, you can import your history). When import is set to true, no outgoing emails or notifications will be generated. reload boolean No Set this parameter to 'true' to return the created conversation in the response.



508
509
510
511
512
513
514
515
516
517
518
519
520
 
# File 'lib/helpscout/client.rb', line 508

def create_conversation(conversation)
  if !conversation
    raise StandardError.new("Missing Conversation")
  end

  url = "/conversations.json"

  begin
    response = Client.create_item(@auth, url, conversation.to_json)
  rescue StandardError => e
    puts "Could not create conversation: #{e.message}"
  end
end

#create_customer(customer) ⇒ Object

Create Customer http://developer.helpscout.net/customers/create/

Creates a new Customer.

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

POST Parameters Name Type Required Notes customer Customer Yes The body of the request
reload boolean No Set to true to return the customer in the response. Response Response Name Type Notes Header Status Integer 201 Header Location String https://api.helpscout.net/v1/customer/id.json



894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
 
# File 'lib/helpscout/client.rb', line 894

def create_customer(customer)
  if !customer
    raise StandardError.new("Missing Customer")
  end

  url = "/customers.json"
  params = JSON.parse(customer.to_json)

  begin
    response = Client.create_item(@auth, url, customer.to_json)
    true
  rescue StandardError => e
    puts "Could not create customer: #{e.message}"
    false
  end
end

#customer(customerId) ⇒ Object

Get Customer http://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



792
793
794
795
796
797
798
799
800
801
 
# File 'lib/helpscout/client.rb', line 792

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

  customer
end

#customers(limit = 0, firstName = nil, lastName = nil, email = nil) ⇒ Object

List Customers http://developer.helpscout.net/customers/

Customers can be filtered on any combination of first name, last name, and email.

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
Name       Type    Required  Default
firstName  String  No
lastName   String  No
email      String  No
page       Int     No        1

Response Name Type items Array Collection of Customer objects.



828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
 
# File 'lib/helpscout/client.rb', line 828

def customers(limit=0, firstName=nil, lastName=nil, email=nil)
  url = "/customers.json"

  page = 1
  options = {}

  if limit < 0
    limit = 0
  end

  if firstName
    options["firstName"] = firstName
  end

  if lastName
    options["lastName"] = lastName
  end

  if email
    options["email"] = email
  end

  customers = []

  begin
    options["page"] = page
    items = Client.request_items(@auth, url, options)
    items.each do |item|
      customers << Customer.new(item)
    end
    page = page + 1
  rescue StandardError => e
    puts "Request failed: #{e.message}"
  end while items && items.count > 0 && (limit == 0 || customers.count < limit)

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

  customers
end

#customers_by_email(email) ⇒ Object

Helper method to find customers by email



871
872
873
 
# File 'lib/helpscout/client.rb', line 871

def customers_by_email(email)
  customers(0, nil, nil, email)
end

#folders_in_mailbox(mailboxId) ⇒ Object

Get Folders http://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



443
444
445
446
447
448
449
450
451
 
# File 'lib/helpscout/client.rb', line 443

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

#mailbox(mailboxId) ⇒ Object

Get Mailbox http://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



413
414
415
416
417
418
419
420
421
 
# File 'lib/helpscout/client.rb', line 413

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

#mailboxes ⇒ Object

List Mailboxes http://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



383
384
385
386
387
388
389
390
391
392
393
394
395
 
# File 'lib/helpscout/client.rb', line 383

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

#user(userId) ⇒ Object

Get User http://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/conversations/conversationId.json

GET Parameters Name Type conversationId Int id of the Conversation being requested

Response Name Type item User



297
298
299
300
301
302
303
304
305
 
# File 'lib/helpscout/client.rb', line 297

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

#users ⇒ Object

List Users http://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



325
326
327
328
329
330
331
332
333
 
# File 'lib/helpscout/client.rb', line 325

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

#users_in_mailbox(mailboxId) ⇒ Object

List Users by Mailbox http://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



355
356
357
358
359
360
361
362
363
 
# File 'lib/helpscout/client.rb', line 355

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