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