Class: HelpScout

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

Defined Under Namespace

Modules: TokenStorage Classes: ForbiddenError, InternalServerError, InvalidDataError, NotFoundError, NotImplementedError, ServiceUnavailable, TooManyRequestsError, ValidationError

Constant Summary collapse

HTTP_OK =

Status codes used by Help Scout, not all are implemented in this gem yet. developer.helpscout.com/mailbox-api/overview/status_codes/

200
HTTP_CREATED = 
201
HTTP_NO_CONTENT = 
204
HTTP_BAD_REQUEST = 
400
HTTP_UNAUTHORIZED = 
401
HTTP_FORBIDDEN = 
403
HTTP_NOT_FOUND = 
404
HTTP_TOO_MANY_REQUESTS = 
429
HTTP_INTERNAL_SERVER_ERROR = 
500
HTTP_SERVICE_UNAVAILABLE = 
503
CONVERSATION_STATUSES =

developer.helpscout.com/mailbox-api/endpoints/conversations/list/

["active", "closed", "open", "pending", "spam"]
VERSION = 
"2.0.0"

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(api_key, api_secret, token_storage = TokenStorage::Memory.new) ⇒ HelpScout

Returns a new instance of HelpScout.



53
54
55
56
57
 
# File 'lib/help_scout.rb', line 53

def initialize(api_key, api_secret, token_storage = TokenStorage::Memory.new)
  @api_key = api_key
  @api_secret = api_secret
  @token_storage = token_storage
end

Instance Attribute Details

#last_response ⇒ Object

Returns the value of attribute last_response.



51
52
53
 
# File 'lib/help_scout.rb', line 51

def last_response
  @last_response
end

Instance Method Details

#create_conversation(data) ⇒ Object

Public: Create conversation

data - hash with data note: since v2 the status is now required, which had a default of “active” in v1.

More info: developer.helpscout.com/mailbox-api/endpoints/conversations/create/

Returns conversation ID



67
68
69
70
71
72
73
 
# File 'lib/help_scout.rb', line 67

def create_conversation(data)
  # required_fields = ["subject", "type", "mailboxId", "status", "customer", "threads"]

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

  last_response.headers["Resource-ID"]
end

#create_customer_email(customer_id, data) ⇒ Object

Public: Create email

More info: developer.helpscout.com/mailbox-api/endpoints/customers/emails/create/



283
284
285
 
# File 'lib/help_scout.rb', line 283

def create_customer_email(customer_id, data)
  post("customers/#{customer_id}/emails", { body: data })
end

#create_customer_phone(customer_id, data) ⇒ Object

Public: Create phone number

More info: developer.helpscout.com/mailbox-api/endpoints/customers/phones/create/



269
270
271
 
# File 'lib/help_scout.rb', line 269

def create_customer_phone(customer_id, data)
  post("customers/#{customer_id}/phones", { body: data })
end

#create_note(conversation_id:, text:, user: nil, imported: false) ⇒ Object

Public: Create note thread

imported: no outgoing e-mails or notifications will be generated

More info: developer.helpscout.com/mailbox-api/endpoints/conversations/threads/note/



198
199
200
201
202
203
204
205
206
207
 
# File 'lib/help_scout.rb', line 198

def create_note(conversation_id:, text:, user: nil, imported: false)
  data = {
    text: text,
    user: user,
    imported: imported,
  }
  post("conversations/#{conversation_id}/notes", body: data)

  last_response.code == HTTP_CREATED
end

#create_phone(conversation_id:, text:, customer:, imported: false) ⇒ Object

Public: Create phone thread

More info: developer.helpscout.com/mailbox-api/endpoints/conversations/threads/phone/



212
213
214
215
216
217
218
219
220
221
222
223
224
225
 
# File 'lib/help_scout.rb', line 212

def create_phone(conversation_id:, text:, customer:, imported: false)
  # Note, hs does not list user as an accepted type
  # https://developer.helpscout.com/mailbox-api/endpoints/conversations/threads/phone/
  data = {
    text: text,
    customer: {
      id: customer
    },
    imported: imported,
  }
  post("conversations/#{conversation_id}/phones", body: data)

  last_response.code == HTTP_CREATED
end

#create_reply(conversation_id:, text:, customer:, user: nil, imported: false) ⇒ Object

Public: Create reply thread

More info: developer.helpscout.com/mailbox-api/endpoints/conversations/threads/reply/



230
231
232
233
234
235
236
237
238
239
240
241
242
 
# File 'lib/help_scout.rb', line 230

def create_reply(conversation_id:, text:, customer:, user: nil, imported: false)
  data = {
    text: text,
    user: user,
    customer: {
      id: customer
    },
    imported: imported,
  }
  post("conversations/#{conversation_id}/reply", body: data)

  last_response.code == HTTP_CREATED
end

#delete_conversation(id) ⇒ Object

Public: Delete conversation

id - conversation id

More info: developer.helpscout.com/mailbox-api/endpoints/conversations/delete/



182
183
184
 
# File 'lib/help_scout.rb', line 182

def delete_conversation(id)
  delete("conversations/#{id}")
end

#delete_customer_email(customer_id, email_id) ⇒ Object

Public: Delete email

More info: developer.helpscout.com/mailbox-api/endpoints/customers/emails/delete/



290
291
292
 
# File 'lib/help_scout.rb', line 290

def delete_customer_email(customer_id, email_id)
  delete("customers/#{customer_id}/emails/#{email_id}")
end

#delete_customer_phone(customer_id, phone_id) ⇒ Object

Public: Delete phone number

More info: developer.helpscout.com/mailbox-api/endpoints/customers/phones/delete/



276
277
278
 
# File 'lib/help_scout.rb', line 276

def delete_customer_phone(customer_id, phone_id)
  delete("customers/#{customer_id}/phones/#{phone_id}")
end

#generate_oauth_token ⇒ Object

developer.helpscout.com/mailbox-api/overview/authentication/#client-credentials-flow



35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
 
# File 'lib/help_scout.rb', line 35

def generate_oauth_token
  options = {
    headers: {
      "Content-Type": "application/json"
    },
    body: {
      grant_type: "client_credentials",
      client_id: @api_key,
      client_secret: @api_secret,
    }
  }
  options[:body] = options[:body].to_json
  response = HTTParty.post("https://api.helpscout.net/v2/oauth2/token", options)
  JSON.parse(response.body)["access_token"]
end

#get_conversation(id, embed_threads: false) ⇒ Object

Public: Get conversation

id - conversation ID embed_threads - boolean - This will load in subentities, currently only Threads are supported by HS

More info: developer.helpscout.com/mailbox-api/endpoints/conversations/get/

Returns hash from HS with conversation data



84
85
86
87
88
89
90
 
# File 'lib/help_scout.rb', line 84

def get_conversation(id, embed_threads: false)
  if embed_threads
    get("conversations/#{id}?embed=threads")
  else
    get("conversations/#{id}")
  end
end

#get_customer(id) ⇒ Object

Public: Get customer

id - customer id

More info: developer.helpscout.com/mailbox-api/endpoints/customers/get/



249
250
251
 
# File 'lib/help_scout.rb', line 249

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

#get_mailboxes ⇒ Object

Public: List all mailboxes

More info: developer.helpscout.com/mailbox-api/endpoints/mailboxes/list/



189
190
191
 
# File 'lib/help_scout.rb', line 189

def get_mailboxes
  get("mailboxes")
end

#search_conversations(query) ⇒ Object

Public: Search for conversations

query - term to search for

More info: developer.helpscout.com/mailbox-api/endpoints/conversations/list/



173
174
175
 
# File 'lib/help_scout.rb', line 173

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

#update_conversation(id, data) ⇒ Object

Public: Update conversation

id - conversation id data - hash with data

More info: developer.helpscout.com/mailbox-api/endpoints/conversations/update/



98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
 
# File 'lib/help_scout.rb', line 98

def update_conversation(id, data)
  instructions = []

  if data[:subject]
    instructions << {
      op: "replace",
      path: "/subject",
      value: data[:subject],
    }
  end
  if data[:mailboxId]
    instructions << {
      op: "move",
      path: "/mailboxId",
      value: data[:mailboxId],
    }
  end
  if data[:status]
    status = data[:status]
    if !CONVERSATION_STATUSES.include?(status)
      raise InvalidDataError.new("status \"#{status}\" not supported, must be one of #{CONVERSATION_STATUSES}")
    end

    instructions << {
      op: "replace",
      path: "/status",
      value: data[:status],
    }
  end
  if data.key?(:assignTo)
    # change owner
    if data[:assignTo]
      instructions << {
        op: "replace",
        path: "/assignTo",
        value: data[:assignTo],
      }
    else
      # un assign
      instructions << {
        op: "remove",
        path: "/assignTo",
      }
    end
  end

  # Note: HelpScout currently does not support multiple
  # instructions in the same request, well have to do them
  # individually :-)
  instructions.each do |instruction|
    patch("conversations/#{id}", { body: instruction })
  end
end

#update_conversation_custom_fields(id, fields) ⇒ Object

Public: Update conversation custom fields

More info: developer.helpscout.com/mailbox-api/endpoints/conversations/custom_fields/update/



163
164
165
166
 
# File 'lib/help_scout.rb', line 163

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

#update_conversation_tags(id, tags) ⇒ Object

Public: Update conversation tags

More info: developer.helpscout.com/mailbox-api/endpoints/conversations/tags/update/



155
156
157
158
 
# File 'lib/help_scout.rb', line 155

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

#update_customer(id, data) ⇒ Object

Public: Update customer

Note: to update address, chat handles, emails, phones, social profiles or websites, separate endpoints have to be used.

id - customer id data - hash with data

More info: developer.helpscout.com/mailbox-api/endpoints/customers/update/



262
263
264
 
# File 'lib/help_scout.rb', line 262

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