class HelpScout::Client

Constants

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:

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.
CONVERSATION_FILTER_STATUS_ALL
CONVERSATION_FILTER_STATUS_PENDING

Public Class Methods

create_item(auth, url, params = {}) click to toggle source

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
# 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
new(key=nil) click to toggle source

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.
# 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
request_count(auth, url, params = {}) click to toggle source

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
# 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 = {}) click to toggle source

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
# 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 = {}) click to toggle source

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
# 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() click to toggle source

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.
# 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

Public Instance Methods

attachment_data(attachmentId) click to toggle source

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
# 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) click to toggle source

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
# 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) click to toggle source

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:

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.
# 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) click to toggle source
# 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) click to toggle source

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:

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.
# 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) click to toggle source

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.
# 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) click to toggle source

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
# 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) click to toggle source

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
# 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) click to toggle source

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.
# 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) click to toggle source

Helper method to find customers by email

# File lib/helpscout/client.rb, line 871
def customers_by_email(email)
  customers(0, nil, nil, email)
end
folders_in_mailbox(mailboxId) click to toggle source

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
# 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) click to toggle source

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
# 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() click to toggle source

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
# 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) click to toggle source

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
# 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() click to toggle source

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
# 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) click to toggle source

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