Class: Cubscout::Conversation

Inherits:
Object
  • Object
show all
Defined in:
lib/cubscout/conversation.rb

Overview

the Conversation class encapsulates a helpscout conversation.

Instance Attribute Summary

Attributes inherited from Object

#attributes

Class Method Summary collapse

Instance Method Summary collapse

Methods inherited from Object

#initialize, #method_missing

Methods included from Scopes

included

Constructor Details

This class inherits a constructor from Cubscout::Object

Dynamic Method Handling

This class handles dynamic methods through the method_missing method in the class Cubscout::Object

Class Method Details

.create_note(id, text:, **attributes) ⇒ Boolean

Create a note to a conversation.

Examples:

Cubscout::Conversation.create_note(123, text: "This is a note")
Cubscout::Conversation.create_note(123, text: "This is a note", attachments: [{fileName: "file.txt", mimeType: "plain/text", data: "ZmlsZQ=="}])

Parameters:

  • id (Integer) —

    the conversation ID

  • text (String) —

    the note’s text

  • attributes (Hash) —

    a customizable set of options

Options Hash (**attributes):

  • :user (Integer) — default: Resource Owner —

    ID of the user creating the note.

  • :imported (Boolean) — default: false —

    The imported field enables thread to be created for historical purposes (i.e. if moving from a different platform, you can import your history). When imported is set to true, no outgoing emails or notifications will be generated.

  • :createdAt (String) —

    Optional creation date to be used when importing conversations and threads. It can only be used with imported field set to true

  • :attachments (Array<Hash>) —

    Optional list of attachments to be attached to this thread

    • :fileName (String) Attachment’s file name

    • :mimeType (String) Attachment’s mime type

    • :data (String) Base64-encoded stream of data.

Returns:

  • (Boolean) —

    success status



34
35
36
 
# File 'lib/cubscout/conversation.rb', line 34

def create_note(id, text:, **attributes)
  Cubscout.connection.post("#{path}/#{id}/notes", attributes.merge(text: text).to_json).body
end

.threads(id) ⇒ Array<Object>

Get the threads of a conversation. In Helpscout lingo, threads are all the items following a conversation: notes, replies, assignment to users, etc.

Parameters:

  • id (Integer) —

    the conversation ID

Returns:

  • (Array<Object>) —

    thread items



11
12
13
 
# File 'lib/cubscout/conversation.rb', line 11

def threads(id)
  Cubscout.connection.get("#{path}/#{id}/threads").body.dig("_embedded", "threads").map { |item| ThreadItem.new(item) }
end

.update(id, op:, path:, **attributes) ⇒ Object

Update a conversation.

Parameters:

  • id (Integer) —

    the conversation ID

  • op (String) —

    Patch operation to be carried out, one of move, remove, replace

  • path (String) —

    Path of the value to be changed, one of: /assignTo, /draft, /mailboxId, /primaryCustomer.id, /status, /subject

  • attributes (Hash) —

    a customizable set of options

Options Hash (**attributes):



46
47
48
 
# File 'lib/cubscout/conversation.rb', line 46

def update(id, op:, path:, **attributes)
  Cubscout.connection.patch("#{Conversation.path}/#{id}", attributes.merge(op: op, path: path).to_json).body
end

Instance Method Details

#assignee(fetch: false) ⇒ User?

Get the assignee of the conversation

Parameters:

  • fetch (Boolean) (defaults to: false) —

    Optional query to helpscout to fetch full user data. By default, use limited data provided in conversation payload

Returns:

  • (User, nil) —

    User assigned to the conversation. Can be nil



55
56
57
58
59
60
61
62
63
64
65
66
 
# File 'lib/cubscout/conversation.rb', line 55

def assignee(fetch: false)
  return nil unless self.attributes.has_key?("assignee")
  if fetch
    User.find(self.attributes.dig("assignee", "id"))
  else
    user_attributes = self.attributes.fetch("assignee").merge(
      "firstName" => self.attributes.dig("assignee", "first"),
      "lastName" => self.attributes.dig("assignee", "last")
    )
    User.new(user_attributes)
  end
end

#create_note(attributes) ⇒ Boolean

Create a note to a conversation.

Parameters:

  • attributes (Hash) —

    a customizable set of options

Options Hash (attributes):

  • :text (String) —

    the note’s text. Required.

  • :user (Integer) — default: Resource Owner —

    ID of the user creating the note.

  • :imported (Boolean) — default: false —

    The imported field enables thread to be created for historical purposes (i.e. if moving from a different platform, you can import your history). When imported is set to true, no outgoing emails or notifications will be generated.

  • :createdAt (String) —

    Optional creation date to be used when importing conversations and threads. It can only be used with imported field set to true

  • :attachments (Array<Hash>) —

    Optional list of attachments to be attached to this thread

    • :fileName (String) Attachment’s file name

    • :mimeType (String) Attachment’s mime type

    • :data (String) Base64-encoded stream of data.

Returns:

  • (Boolean) —

    success status



99
100
101
 
# File 'lib/cubscout/conversation.rb', line 99

def create_note(attributes)
  Conversation.create_note(self.id, attributes)
end

#threads(fetch: false) ⇒ Array<Object>

Get the threads of the conversation. In Helpscout lingo, threads are all the items following a conversation: notes, replies, assignment to users, etc.

Parameters:

  • fetch (Boolean) (defaults to: false) —

    Optional query to helpscout to fetch threads data. By default, use data provided in conversation payload. Note that the threads are only embedded to the conversation payload on demand, example: Cubscout::Conversation.all(tag: ‘blue,red’, embed: ‘threads’) Cubscout::Conversation.find(1234567, embed: ‘threads’)

Returns:

  • (Array<Object>) —

    thread items



76
77
78
79
80
81
82
 
# File 'lib/cubscout/conversation.rb', line 76

def threads(fetch: false)
  if fetch
    Conversation.threads(self.id)
  else
    self.attributes.dig("_embedded", "threads").map { |item| ThreadItem.new(item) }
  end
end

#update(attributes) ⇒ Object

Update a conversation.

Parameters:

  • attributes (Hash) —

    a customizable set of options

Options Hash (attributes):

  • :op (String) —

    Patch operation to be carried out, one of move, remove, replace. Required

  • :path (String) —

    Path of the value to be changed, one of: /assignTo, /draft, /mailboxId, /primaryCustomer.id, /status, /subject. Required

  • :value (Varies) —

    Value to be used in operation, refer to this documentation for valid types: developer.helpscout.com/mailbox-api/endpoints/conversations/update/#valid-paths-and-operations. In case of status update (op: “replace”, path: “/status”), :value must be one of active, closed, open, pending, spam



110
111
112
 
# File 'lib/cubscout/conversation.rb', line 110

def update(attributes)
  Conversation.update(self.id, attributes)
end