helpscout.models package

Submodules

helpscout.models.address module

class helpscout.models.address.Address(**kwargs)

Bases: helpscout.base_model.BaseModel

This represents an address.

Required Properties:

• city (String): City, a unicode string
• country (String): Country, a unicode string
• created_at (DateTime): UTC time when this address was created., a datetime object
• id (Integer): Unique identifier, an integer
• lines (a list of String): Address line strings, a list (each item is a unicode string)
• modified_at (DateTime): UTC time when this address was modified., a datetime object
• postal_code (String): Postal Code, a unicode string
• state (String): State, a unicode string

city

City

country

Country

created_at

UTC time when this address was created.

lines

Address line strings

modified_at

UTC time when this address was modified.

postal_code

Postal Code

state

State

helpscout.models.attachment module

class helpscout.models.attachment.Attachment(**kwargs)

Bases: helpscout.models.attachment_data.AttachmentData

Required Properties:

• data (String): base64 encoded data., a unicode string
• file_name (String): File Name, a unicode string
• hash (String): Unique hash., a unicode string
• height (Integer): Image height, an integer
• id (Integer): Unique identifier, an integer
• mime_type (String): Mime Type, a unicode string
• size (Integer): Size of the attachment in bytes., an integer
• url (String): Public-facing url where attachment can be downloaded., a unicode string
• width (Integer): Image width, an integer

file_name

File Name

hash

Unique hash.

height

Image height

mime_type

Mime Type

size

Size of the attachment in bytes.

url

Public-facing url where attachment can be downloaded.

width

Image width

helpscout.models.attachment_data module

class helpscout.models.attachment_data.AttachmentData(**kwargs)

Bases: helpscout.base_model.BaseModel

Required Properties:

• data (String): base64 encoded data., a unicode string
• id (Integer): Unique identifier, an integer

data

base64 encoded data.

raw_data

Raw (decoded) attachment data (possibly binary).

helpscout.models.base_conversation module

class helpscout.models.base_conversation.BaseConversation(**kwargs)

Bases: helpscout.base_model.BaseModel

This represents a basic conversation, meant to be subclassed.

Required Properties:

• id (Integer): Unique identifier, an integer
• modified_at (DateTime): UTC time when a user last modified this conversation., a datetime object
• number (Integer): The conversation number displayed in the UI. This number can be used in combination with the id to construct a URI to the conversation on the Help Scout website. Example: https://secure.helpscout.net/conversation/<id>/<number>/, an integer
• preview (String): Conversation preview., a unicode string
• status (StringChoice): Status of the conversation., any of “active”, “pending”, “closed”, “spam”, Default: pending
• subject (String): The subject of the conversation., a unicode string
• thread_count (Integer): This count represents the number of published threads found on the conversation (it does not include line items, drafts or threads held for review by Traffic Cop)., an integer

modified_at

UTC time when a user last modified this conversation.

number

The conversation number displayed in the UI. This number can be used in combination with the id to construct a URI to the conversation on the Help Scout website. Example – https -- //secure.helpscout.net/conversation/<id>/<number>/

preview

Conversation preview.

status

Status of the conversation.

subject

The subject of the conversation.

thread_count

This count represents the number of published threads found on the conversation (it does not include line items, drafts or threads held for review by Traffic Cop).

helpscout.models.chat module

class helpscout.models.chat.Chat(**kwargs)

Bases: helpscout.base_model.BaseModel

This represents a chat (IM) address.

Required Properties:

• id (Integer): Unique identifier, an integer
• type (StringChoice): Type, any of “aim”, “gtalk”, “icq”, “xmpp”, “msn”, “skype”, “yahoo”, “qq”, “other”, Default: other
• value (String): Value, a unicode string

type

Type

value

Value

helpscout.models.conversation module

class helpscout.models.conversation.Conversation(**kwargs)

Bases: helpscout.models.base_conversation.BaseConversation

This represents a full conversation result.

Required Properties:

• bcc (a list of String): Emails that are BCCd., a list (each item is a unicode string)
• cc (a list of String): Emails that are CCd., a list (each item is a unicode string)
• closed_at (DateTime): UTC time when this conversation was closed. Null if not closed., a datetime object
• closed_by (Person): The Help Scout user who closed this conversation., an instance of Person
• created_at (DateTime): UTC time when this conversation was created., a datetime object
• created_by (Person): The Person who created this conversation. The type property will specify whether it was created by a user or a customer., an instance of Person
• created_by_type (String): The type of user that created this conversation., a unicode string
• customer (Person): The customer who this conversation is associated with., an instance of Person
• draft (Bool): Is this a draft conversation? This property duplicates is_draft, but both are received in API responses at the same time so neither can be considered “deprecated”., a boolean
• folder_id (Integer): ID of the Mailbox Folder to which this conversation resides., an integer
• id (Integer): Unique identifier, an integer
• is_draft (Bool): Is this a draft conversation? This property duplicates draft, but both are received in API responses at the same time so neither can be considered “deprecated”., a boolean
• locked (Bool): If this conversation is locked from editing., a boolean
• mailbox (MailboxRef): The mailbox to which this conversation belongs., an instance of MailboxRef
• modified_at (DateTime): UTC time when a user last modified this conversation., a datetime object
• number (Integer): The conversation number displayed in the UI. This number can be used in combination with the id to construct a URI to the conversation on the Help Scout website. Example: https://secure.helpscout.net/conversation/<id>/<number>/, an integer
• owner (Person): The Help Scout user who is currently assigned to this conversation., an instance of Person
• preview (String): Conversation preview., a unicode string
• source (Source): Specifies the method in which this conversation was created., an instance of Source
• spam (Bool): If this conversation is marked as SPAM., a boolean
• status (StringChoice): Status of the conversation., any of “active”, “pending”, “closed”, “spam”, Default: pending
• subject (String): The subject of the conversation., a unicode string
• tags (a list of String): Tags for the conversation, a list (each item is a unicode string)
• thread_count (Integer): This count represents the number of published threads found on the conversation (it does not include line items, drafts or threads held for review by Traffic Cop)., an integer
• threads (a list of Thread): Threads associated with the conversation., a list (each item is an instance of Thread)
• type (StringChoice): The type of conversation., any of “email”, “chat”, “phone”, “spam”
• user_modified_at (DateTime): Last time that this conversation was edited by a user., a datetime object

bcc

Emails that are BCCd.

cc

Emails that are CCd.

closed_at

UTC time when this conversation was closed. Null if not closed.

closed_by

The Help Scout user who closed this conversation.

created_at

UTC time when this conversation was created.

created_by

The Person who created this conversation. The type property will specify whether it was created by a user or a customer.

created_by_type

The type of user that created this conversation.

customer

The customer who this conversation is associated with.

draft

Is this a draft conversation? This property duplicates is_draft, but both are received in API responses at the same time so neither can be considered “deprecated”.

folder_id

ID of the Mailbox Folder to which this conversation resides.

is_draft

Is this a draft conversation? This property duplicates draft, but both are received in API responses at the same time so neither can be considered “deprecated”.

locked

If this conversation is locked from editing.

mailbox

The mailbox to which this conversation belongs.

owner

The Help Scout user who is currently assigned to this conversation.

source

Specifies the method in which this conversation was created.

spam

If this conversation is marked as SPAM.

tags

Tags for the conversation

threads

Threads associated with the conversation.

type

The type of conversation.

user_modified_at

Last time that this conversation was edited by a user.

helpscout.models.custom_field module

class helpscout.models.custom_field.CustomField(**kwargs)

Bases: helpscout.base_model.BaseModel

This represents optional data that can defined for specific mailbox

and filled when creating or updating a Conversation.

Required Properties:

• field_name (String): The name of the field; note that this may change if a field is renamed, but the id will not., a unicode string
• field_type (StringChoice): Type of the field., any of “SINGLE_LINE”, “MULTI_LINE”, “DATA”, “NUMBER”, “DROPDOWN”, Default: SINGLE_LINE
• id (Integer): Unique identifier, an integer
• options (a list of Option): Field options, a list (each item is an instance of Option)
• order (Integer): Relative order of the custom field. Can be null or a number between 0 and 255., an integer in range [0, 255]
• required (Bool): Flag for UI to mark the field as required., a boolean

field_name

The name of the field; note that this may change if a field is renamed, but the id will not.

field_type

Type of the field.

options

Field options

order

Relative order of the custom field. Can be null or a number between 0 and 255.

required

Flag for UI to mark the field as required.

helpscout.models.customer module

class helpscout.models.customer.Customer(**kwargs)

Bases: helpscout.models.search_customer.SearchCustomer

This represents a customer, which is a type of person.

Required Properties:

• address (Address): The address for this customer., an instance of Address
• age (String): Age (or age range) of this customer., a unicode string
• background (String): This is the Notes field from the user interface., a unicode string
• chats (a list of Chat): Chat addresses for this customer., a list (each item is an instance of Chat)
• created_at (DateTime): UTC time when this customer was created., a datetime object
• email (String): Email, a unicode string
• emails (a list of Email): Email addresses for this customer., a list (each item is an instance of Email)
• first_name (String): First name, a unicode string
• full_name (String): Full name for the customer, a unicode string
• gender (StringChoice): Gender of this customer., any of “female”, “male”, “unknown”, Default: unknown
• id (Integer): Unique identifier, an integer
• job_title (String): Job title at company/organization., a unicode string
• last_name (String): Last name, a unicode string
• location (String): Location, a unicode string
• modified_at (DateTime): UTC time when this customer was modified., a datetime object
• organization (String): Company/Organization the customer identifies with., a unicode string
• phone (String): Phone is only populated when the Person is a customer associated with a Conversation of type phone and a phone number was specified at the time the conversation was created., a unicode string
• phones (a list of Phone): Phone numbers for this customer., a list (each item is an instance of Phone)
• photo_type (StringChoice): Type of photo., any of “unknown”, “gravatar”, “twitter”, “facebook”, “googleprofile”, “googleplus”, “linkedin”
• photo_url (String): The user’s photo, if one exists., a unicode string
• social_profiles (a list of SocialProfile): Social profiles that represent this customer., a list (each item is an instance of SocialProfile)
• type (StringChoice): The type of person., any of “user”, “customer”, “team”, Default: customer
• websites (a list of Website): Websites for this customer., a list (each item is an instance of Website)

Other Properties:

• customer_person_type (dynamic Bool): customer boolean, a boolean

address

The address for this customer.

background

This is the Notes field from the user interface.

chats

Chat addresses for this customer.

emails

Email addresses for this customer.

phones

Phone numbers for this customer.

social_profiles

Social profiles that represent this customer.

websites

Websites for this customer.

helpscout.models.email module

class helpscout.models.email.Email(**kwargs)

Bases: helpscout.base_model.BaseModel

Required Properties:

• id (Integer): Unique identifier, an integer
• location (StringChoice): Location for this email address., any of “home”, “work”, “other”, Default: other
• value (String): Email Address, a unicode string

location

Location for this email address.

value

Email Address

helpscout.models.field module

class helpscout.models.field.Field(**kwargs)

Bases: helpscout.base_model.BaseModel

The field object represents a user’s response to a custom field

in the context of a single conversation.

Required Properties:

• field_id (Integer): The field definition identifier; note that multiple conversations will each have values for the same field identifier., an integer
• id (Integer): Unique identifier, an integer
• label (String): String representation of the custom field’s value. Unlike value it contains the actual dropdown option value for DROPDOWN custom field., a unicode string
• name (String): The name of the field; note that this may change if a field is renamed, but the field_id will not., a unicode string
• type (StringChoice): Type of the custom field., any of “SINGLE_LINE”, “MULTI_LINE”, “DATE”, “NUMBER”, “DROPDOWN”
• value (String): The value the user specified for the field., a unicode string

field_id

The field definition identifier; note that multiple conversations will each have values for the same field identifier.

label

String representation of the custom field’s value. Unlike value it contains the actual dropdown option value for DROPDOWN custom field.

name

The name of the field; note that this may change if a field is renamed, but the field_id will not.

type

Type of the custom field.

value

The value the user specified for the field.

helpscout.models.folder module

class helpscout.models.folder.Folder(**kwargs)

Bases: helpscout.base_model.BaseModel

Required Properties:

• active_count (Integer): Total number of conversations in this folder that are in an active state (vs pending)., an integer
• id (Integer): Unique identifier, an integer
• modified_at (DateTime): UTC time when this folder was modified., a datetime object
• name (String): Folder name, a unicode string
• total_count (Integer): Total number of conversations in this folder., an integer
• type (StringChoice): The type of folder., any of “needsattention”, “drafts”, “assigned”, “open”, “closed”, “spam”, “mine”, “team”, Default: drafts
• user_id (Integer): If the folder type is MyTickets, this represents the Help Scout user to which this folder belongs. Otherwise it is empty., an integer

active_count

Total number of conversations in this folder that are in an active state (vs pending).

modified_at

UTC time when this folder was modified.

name

Folder name

total_count

Total number of conversations in this folder.

type

The type of folder.

user_id

If the folder type is MyTickets, this represents the Help Scout user to which this folder belongs. Otherwise it is empty.

helpscout.models.mailbox module

class helpscout.models.mailbox.Mailbox(**kwargs)

Bases: helpscout.models.mailbox_ref.MailboxRef

Required Properties:

• created_at (DateTime): UTC time when this mailbox was created., a datetime object
• email (String): Email address, a unicode string
• folders (a list of Folder): Folders that this mailbox contains., a list (each item is an instance of Folder)
• id (Integer): Unique identifier, an integer
• modified_at (DateTime): UTC time when this mailbox was modified., a datetime object
• name (String): Name of the Mailbox., a unicode string
• slug (String): Key used to represent this Mailbox., a unicode string

created_at

UTC time when this mailbox was created.

email

Email address

folders

Folders that this mailbox contains.

modified_at

UTC time when this mailbox was modified.

slug

Key used to represent this Mailbox.

helpscout.models.mailbox_ref module

class helpscout.models.mailbox_ref.MailboxRef(**kwargs)

Bases: helpscout.base_model.BaseModel

The mailbox ref is a subset of the full Mailbox object.

Required Properties:

• id (Integer): Unique identifier, an integer
• name (String): Name of the Mailbox., a unicode string

name

Name of the Mailbox.

helpscout.models.option module

class helpscout.models.option.Option(**kwargs)

Bases: helpscout.base_model.BaseModel

This represents option for a custom field of type DROPDOWN.

Required Properties:

• id (Integer): Unique identifier, an integer
• label (String): Label of the option., a unicode string
• order (Integer): Relative order of the custom field. Can be null or a number between 0 and 255., an integer in range [0, 255]

label

Label of the option.

order

Relative order of the custom field. Can be null or a number between 0 and 255.

helpscout.models.person module

class helpscout.models.person.Person(**kwargs)

Bases: helpscout.base_model.BaseModel

This is a subset of the data representing a Customer, User or Team.

The type property will specify if this person is represented by a user, customer or team.

Required Properties:

• created_at (DateTime): UTC time when this customer was created., a datetime object
• email (String): Email, a unicode string
• emails (a list of String): Email addresses for this person., a list (each item is a unicode string)
• first_name (String): First name, a unicode string
• full_name (String): Full name for the customer, a unicode string
• id (Integer): Unique identifier, an integer
• last_name (String): Last name, a unicode string
• modified_at (DateTime): UTC time when this customer was modified., a datetime object
• phone (String): Phone is only populated when the Person is a customer associated with a Conversation of type phone and a phone number was specified at the time the conversation was created., a unicode string
• photo_url (String): The user’s photo, if one exists., a unicode string
• type (StringChoice): The type of person., any of “user”, “customer”, “team”, Default: customer

Other Properties:

• customer_person_type (dynamic Bool): customer boolean, a boolean

created_at

UTC time when this customer was created.

customer_person_type

customer boolean

email

Email

emails

Email addresses for this person.

first_name

First name

full_name

Full name for the customer

last_name

Last name

modified_at

UTC time when this customer was modified.

phone

Phone is only populated when the Person is a customer associated with a Conversation of type phone and a phone number was specified at the time the conversation was created.

photo_url

The user’s photo, if one exists.

type

The type of person.

helpscout.models.phone module

class helpscout.models.phone.Phone(**kwargs)

Bases: helpscout.base_model.BaseModel

Required Properties:

• id (Integer): Unique identifier, an integer
• location (StringChoice): Location for this phone number., any of “home”, “fax”, “mobile”, “pager”, “work”, “other”, Default: other
• value (String): Phone Number, a unicode string

location

Location for this phone number.

value

Phone Number

helpscout.models.rating module

class helpscout.models.rating.Rating(**kwargs)

Bases: helpscout.base_model.BaseModel

Required Properties:

• comments (String): Additional comments, a unicode string
• created_at (DateTime): UTC time when this rating was created., a datetime object
• customer (Customer): Partial customer object., an instance of Customer
• id (Integer): Unique identifier, an integer
• mailbox (MailboxRef): Reference to the mailbox that the conversation belongs to., an instance of MailboxRef
• modified_at (DateTime): UTC time when this rating was modified., a datetime object
• rating (StringChoice): Satisfaction rating., any of “Great”, “Okay”, “Bad”
• thread_id (Integer): Thread ID, an integer
• ticket_id (Integer): Ticket ID, an integer

comments

Additional comments

created_at

UTC time when this rating was created.

customer

Partial customer object.

mailbox

Reference to the mailbox that the conversation belongs to.

modified_at

UTC time when this rating was modified.

rating

Satisfaction rating.

thread_id

Thread ID

ticket_id

Ticket ID

helpscout.models.search_conversation module

class helpscout.models.search_conversation.SearchConversation(**kwargs)

Bases: helpscout.models.base_conversation.BaseConversation

This represents a conversation as returned by search results.

Required Properties:

• customer_email (String): Email address of the customer, a unicode string
• customer_name (String): Name of the customer this conversation is regarding., a unicode string
• has_attachments (Bool): True when the conversation has at least one attachment., a boolean
• id (Integer): Unique identifier, an integer
• mailbox_id (Integer): The ID of the mailbox this conversation is in., an integer
• modified_at (DateTime): UTC time when a user last modified this conversation., a datetime object
• number (Integer): The conversation number displayed in the UI. This number can be used in combination with the id to construct a URI to the conversation on the Help Scout website. Example: https://secure.helpscout.net/conversation/<id>/<number>/, an integer
• preview (String): Conversation preview., a unicode string
• status (StringChoice): Status of the conversation., any of “active”, “pending”, “closed”, “spam”, Default: pending
• subject (String): The subject of the conversation., a unicode string
• thread_count (Integer): This count represents the number of published threads found on the conversation (it does not include line items, drafts or threads held for review by Traffic Cop)., an integer

customer_email

Email address of the customer

customer_name

Name of the customer this conversation is regarding.

has_attachments

True when the conversation has at least one attachment.

mailbox_id

The ID of the mailbox this conversation is in.

helpscout.models.search_customer module

class helpscout.models.search_customer.SearchCustomer(**kwargs)

Bases: helpscout.models.person.Person

This represents a customer as returned by a search.

Required Properties:

• age (String): Age (or age range) of this customer., a unicode string
• created_at (DateTime): UTC time when this customer was created., a datetime object
• email (String): Email, a unicode string
• emails (a list of String): Email addresses for the customer., a list (each item is a unicode string)
• first_name (String): First name, a unicode string
• full_name (String): Full name for the customer, a unicode string
• gender (StringChoice): Gender of this customer., any of “female”, “male”, “unknown”, Default: unknown
• id (Integer): Unique identifier, an integer
• job_title (String): Job title at company/organization., a unicode string
• last_name (String): Last name, a unicode string
• location (String): Location, a unicode string
• modified_at (DateTime): UTC time when this customer was modified., a datetime object
• organization (String): Company/Organization the customer identifies with., a unicode string
• phone (String): Phone is only populated when the Person is a customer associated with a Conversation of type phone and a phone number was specified at the time the conversation was created., a unicode string
• photo_type (StringChoice): Type of photo., any of “unknown”, “gravatar”, “twitter”, “facebook”, “googleprofile”, “googleplus”, “linkedin”
• photo_url (String): The user’s photo, if one exists., a unicode string
• type (StringChoice): The type of person., any of “user”, “customer”, “team”, Default: customer

Other Properties:

• customer_person_type (dynamic Bool): customer boolean, a boolean

age

Age (or age range) of this customer.

emails

Email addresses for the customer.

gender

Gender of this customer.

job_title

Job title at company/organization.

location

Location

organization

Company/Organization the customer identifies with.

photo_type

Type of photo.

helpscout.models.social_profile module

class helpscout.models.social_profile.SocialProfile(**kwargs)

Bases: helpscout.base_model.BaseModel

Required Properties:

• id (Integer): Unique identifier, an integer
• type (StringChoice): Type of social profile., any of “twitter”, “facebook”, “linkedin”, “aboutme”, “google”, “googleplus”, “tungleme”, “quora”, “foursquare”, “youtube”, “flickr”, “other”, Default: other
• value (String): Username, a unicode string

type

Type of social profile.

value

Username

helpscout.models.source module

class helpscout.models.source.Source(**kwargs)

Bases: helpscout.base_model.BaseModel

Required Properties:

• id (Integer): Unique identifier, an integer
• type (StringChoice): The method from which this conversation (or thread) was created., any of “email”, “web”, “notification”, “emailfwd”, “api”, “chat”, Default: api
• via (StringChoice): Indicates what type of entity this source represents (customer, user)., either “customer” or “user”

type

The method from which this conversation (or thread) was created.

via

Indicates what type of entity this source represents (customer, user).

helpscout.models.tag module

class helpscout.models.tag.Tag(**kwargs)

Bases: helpscout.base_model.BaseModel

Required Properties:

• color (Color): The tag color., a color
• count (Integer): The number of times the tag is used., an integer
• created_at (DateTime): UTC time when this tag was created., a datetime object
• id (Integer): Unique identifier, an integer
• modified_at (DateTime): UTC time when this tag was modified., a datetime object
• slug (String): Slugified version of the tag value., a unicode string
• tag (String): The tag value., a unicode string

color

The tag color.

count

The number of times the tag is used.

created_at

UTC time when this tag was created.

modified_at

UTC time when this tag was modified.

slug

Slugified version of the tag value.

tag

The tag value.

helpscout.models.thread module

class helpscout.models.thread.Thread(**kwargs)

Bases: helpscout.base_model.BaseModel

Required Properties:

• action_source_id (Integer): Associated with the action_type property.
• If action_type is movedFromMailbox, this will be the id of the mailbox the conversation was moved from.
• If action_type is merged, this will be the id of the original conversation.
• If action_type is imported, this will be null.
• If action_type is workflow, this will be the id of the workflow that was run.

, an integer * action_type (StringChoice): Describes an optional action associated with the line item., any of “movedFromMailbox”, “merged”, “imported”, “workflow”, “importedExternal”, “changedTicketCustomer”, “deletedTicket”, “restoredTicket”, “originalCreator” * assigned_to (Person): The Help Scout user assigned to this conversation., an instance of Person * attachments (a list of Attachment): Attachments, a list (each item is an instance of Attachment) * bcc (a list of String): BCC to, a list (each item is a unicode string) * body (String): Body text, a unicode string * cc (a list of String): CC to, a list (each item is a unicode string) * created_at (DateTime): UTC time when this thread was created., a datetime object * created_by (Person): The Person who created this thread. The type property will specify whether it was created by a user or a customer., an instance of Person * created_by_customer (Bool): Equivalent to created_by.type == "customer"., a boolean * customer (Person): If thread type is message, this is the customer associated with the conversation. If thread type is customer, this is the the customer who initiated the thread., an instance of Person * from_mailbox (MailboxRef): If the conversation was moved, this represents the MailboxRef from which it was moved., an instance of MailboxRef * id (Integer): Unique identifier, an integer * opened_at (DateTime): UTC time when this thread was viewed by the customer. Only applies to threads with a type of message., a datetime object * saved_reply_id (Integer): ID of Saved reply that was used to create this Thread., an integer * source (Source): Origin of thread, an instance of Source * state (StringChoice): The state of the thread. A state of underreview means the thread has been stopped by Traffic Cop and is waiting to be confirmed (or discarded) by the person that created the thread. A state of hidden means the thread was hidden (or removed) from customer-facing emails., any of “published”, “draft”, “underreview”, “hidden” * status (StringChoice): Status of the thread., any of “nochange”, “active”, “pending”, “closed”, “spam” * to (a list of String): Email to, a list (each item is a unicode string) * type (StringChoice): The type of thread. A lineitem represents a change of state on the conversation. This could include, but not limited to, the conversation was assigned, the status changed, the conversation was moved from one mailbox to another, etc. A line item won’t have a body, to/cc/bcc lists, or attachments. When a conversation is forwarded, a new conversation is created to represent the forwarded conversation. forwardparent ``is the type set on the thread of the original conversation that initiated the forward event. ``forwardchild is the type set on the first thread of the new forwarded conversation., any of “lineitem”, “note”, “message”, “chat”, “customer”, “forwardparent”, “forwardchild”, “phone”

action_source_id

Associated with the action_type property.

• If action_type is movedFromMailbox, this will be the id of the mailbox the conversation was moved from.
• If action_type is merged, this will be the id of the original conversation.
• If action_type is imported, this will be null.
• If action_type is workflow, this will be the id of the workflow that was run.

action_type

Describes an optional action associated with the line item.

assigned_to

The Help Scout user assigned to this conversation.

attachments

Attachments

bcc

BCC to

body

Body text

cc

CC to

created_at

UTC time when this thread was created.

created_by

The Person who created this thread. The type property will specify whether it was created by a user or a customer.

created_by_customer

Equivalent to created_by.type == "customer".

customer

If thread type is message, this is the customer associated with the conversation. If thread type is customer, this is the the customer who initiated the thread.

from_mailbox

If the conversation was moved, this represents the MailboxRef from which it was moved.

opened_at

UTC time when this thread was viewed by the customer. Only applies to threads with a type of message.

saved_reply_id

ID of Saved reply that was used to create this Thread.

source

Origin of thread

state

The state of the thread. A state of underreview means the thread has been stopped by Traffic Cop and is waiting to be confirmed (or discarded) by the person that created the thread. A state of hidden means the thread was hidden (or removed) from customer-facing emails.

status

Status of the thread.

to

Email to

type

The type of thread. A lineitem represents a change of state on the conversation. This could include, but not limited to, the conversation was assigned, the status changed, the conversation was moved from one mailbox to another, etc. A line item won’t have a body, to/cc/bcc lists, or attachments. When a conversation is forwarded, a new conversation is created to represent the forwarded conversation. forwardparent ``is the type set on the thread of the original conversation that initiated the forward event. ``forwardchild is the type set on the first thread of the new forwarded conversation.

helpscout.models.user module

class helpscout.models.user.User(**kwargs)

Bases: helpscout.models.person.Person

Required Properties:

• created_at (DateTime): UTC time when this customer was created., a datetime object
• email (String): Email, a unicode string
• emails (a list of String): Email addresses for this person., a list (each item is a unicode string)
• first_name (String): First name, a unicode string
• full_name (String): Full name for the customer, a unicode string
• id (Integer): Unique identifier, an integer
• last_name (String): Last name, a unicode string
• modified_at (DateTime): UTC time when this customer was modified., a datetime object
• phone (String): Phone is only populated when the Person is a customer associated with a Conversation of type phone and a phone number was specified at the time the conversation was created., a unicode string
• photo_url (String): The user’s photo, if one exists., a unicode string
• role (StringChoice): Role of this user., any of “owner”, “admin”, “user”
• timezone (String): Name of the user’s time zone., a unicode string
• type (StringChoice): The type of user., either “user” or “team”

Other Properties:

• customer_person_type (dynamic Bool): customer boolean, a boolean

role

Role of this user.

timezone

Name of the user’s time zone.

type

The type of user.

helpscout.models.web_hook module

class helpscout.models.web_hook.WebHook(**kwargs)

Bases: helpscout.base_model.BaseModel

Required Properties:

• events (a list of StringChoice): The events to subscribe to., a list (each item is any of “convo.agent.reply.created” (An agent replied to the conversation.), “convo.assigned” (Conversation was assigned.), “convo.created” (Conversation was created.), “convo.customer.reply.created” (The customer replied to the conversation.), “convo.deleted” (Conversation was deleted.), “convo.merged” (Conversation was merged.), “convo.moved” (Conversation was moved.), “convo.note.created” (A note was added to the conversation.), “convo.status” (Conversation status was updated.), “convo.tags” (Conversation tags were updated.), “customer.created” (A customer was created.), “satisfaction.ratings” (A rating was received.))
• id (Integer): Unique identifier, an integer
• secret_key (String): A randomly-generated (by you) string of 40 characters or less used to create signatures for each webhook method. Help Scout uses this secret key to generate a signature for each webhook message. When the message is received at your callback URL, you can calculate a signature and compare to the one Help Scout sends. If the signatures match, you know it’s from Help Scout., a unicode string
• url (String): The callback URL where Help Scout will post your webhook events. This is the script or location where you’ll handle the data received from Help Scout., a unicode string

events

The events to subscribe to.

secret_key

A randomly-generated (by you) string of 40 characters or less used to create signatures for each webhook method. Help Scout uses this secret key to generate a signature for each webhook message. When the message is received at your callback URL, you can calculate a signature and compare to the one Help Scout sends. If the signatures match, you know it’s from Help Scout.

url

The callback URL where Help Scout will post your webhook events. This is the script or location where you’ll handle the data received from Help Scout.

helpscout.models.web_hook_event module

class helpscout.models.web_hook_event.WebHookEvent(**kwargs)

Bases: helpscout.base_model.BaseModel

Required Properties:

• event_type (StringChoice): The event type that this object represents., any of “convo.agent.reply.created” (An agent replied to the conversation.), “convo.assigned” (Conversation was assigned.), “convo.created” (Conversation was created.), “convo.customer.reply.created” (The customer replied to the conversation.), “convo.deleted” (Conversation was deleted.), “convo.merged” (Conversation was merged.), “convo.moved” (Conversation was moved.), “convo.note.created” (A note was added to the conversation.), “convo.status” (Conversation status was updated.), “convo.tags” (Conversation tags were updated.), “customer.created” (A customer was created.), “satisfaction.ratings” (A rating was received.)
• id (Integer): Unique identifier, an integer
• record (BaseModel): The parsed data record that was received in the request., an instance of BaseModel

event_type

The event type that this object represents.

record

The parsed data record that was received in the request.

helpscout.models.website module

class helpscout.models.website.Website(**kwargs)

Bases: helpscout.base_model.BaseModel

Required Properties:

• id (Integer): Unique identifier, an integer
• value (String): URI, a unicode string

value

URI

helpscout.models.workflow module

class helpscout.models.workflow.Workflow(**kwargs)

Bases: helpscout.base_model.BaseModel

Required Properties:

• created_at (DateTime): UTC time when this workflow was created., a datetime object
• id (Integer): Unique identifier, an integer
• mailbox_id (Integer): The mailbox ID that this workflow is associated with., an integer
• modified_at (DateTime): UTC time when this workflow was modified., a datetime object
• name (String): Workflow name., a unicode string
• order (Integer): The order of the workflow., an integer, Default: 1
• status (StringChoice): The status of the workflow., any of “active”, “inactive”, “invalid”, Default: invalid
• type (StringChoice): The type of workflow., either “automatic” or “manual”, Default: manual

created_at

UTC time when this workflow was created.

mailbox_id

The mailbox ID that this workflow is associated with.

modified_at

UTC time when this workflow was modified.

name

Workflow name.

order

The order of the workflow.

status

The status of the workflow.

type

The type of workflow.

Module contents

class helpscout.models.Address(**kwargs)

Bases: helpscout.base_model.BaseModel

This represents an address.

Required Properties:

• city (String): City, a unicode string
• country (String): Country, a unicode string
• created_at (DateTime): UTC time when this address was created., a datetime object
• id (Integer): Unique identifier, an integer
• lines (a list of String): Address line strings, a list (each item is a unicode string)
• modified_at (DateTime): UTC time when this address was modified., a datetime object
• postal_code (String): Postal Code, a unicode string
• state (String): State, a unicode string

city

City

country

Country

created_at

UTC time when this address was created.

lines

Address line strings

modified_at

UTC time when this address was modified.

postal_code

Postal Code

state

State

class helpscout.models.Attachment(**kwargs)

Bases: helpscout.models.attachment_data.AttachmentData

Required Properties:

• data (String): base64 encoded data., a unicode string
• file_name (String): File Name, a unicode string
• hash (String): Unique hash., a unicode string
• height (Integer): Image height, an integer
• id (Integer): Unique identifier, an integer
• mime_type (String): Mime Type, a unicode string
• size (Integer): Size of the attachment in bytes., an integer
• url (String): Public-facing url where attachment can be downloaded., a unicode string
• width (Integer): Image width, an integer

file_name

File Name

hash

Unique hash.

height

Image height

mime_type

Mime Type

size

Size of the attachment in bytes.

url

Public-facing url where attachment can be downloaded.

width

Image width

class helpscout.models.AttachmentData(**kwargs)

Bases: helpscout.base_model.BaseModel

Required Properties:

• data (String): base64 encoded data., a unicode string
• id (Integer): Unique identifier, an integer

data

base64 encoded data.

raw_data

Raw (decoded) attachment data (possibly binary).

class helpscout.models.BaseConversation(**kwargs)

Bases: helpscout.base_model.BaseModel

This represents a basic conversation, meant to be subclassed.

Required Properties:

• id (Integer): Unique identifier, an integer
• modified_at (DateTime): UTC time when a user last modified this conversation., a datetime object
• number (Integer): The conversation number displayed in the UI. This number can be used in combination with the id to construct a URI to the conversation on the Help Scout website. Example: https://secure.helpscout.net/conversation/<id>/<number>/, an integer
• preview (String): Conversation preview., a unicode string
• status (StringChoice): Status of the conversation., any of “active”, “pending”, “closed”, “spam”, Default: pending
• subject (String): The subject of the conversation., a unicode string
• thread_count (Integer): This count represents the number of published threads found on the conversation (it does not include line items, drafts or threads held for review by Traffic Cop)., an integer

modified_at

UTC time when a user last modified this conversation.

number

The conversation number displayed in the UI. This number can be used in combination with the id to construct a URI to the conversation on the Help Scout website. Example – https -- //secure.helpscout.net/conversation/<id>/<number>/

preview

Conversation preview.

status

Status of the conversation.

subject

The subject of the conversation.

thread_count

This count represents the number of published threads found on the conversation (it does not include line items, drafts or threads held for review by Traffic Cop).

class helpscout.models.Chat(**kwargs)

Bases: helpscout.base_model.BaseModel

This represents a chat (IM) address.

Required Properties:

• id (Integer): Unique identifier, an integer
• type (StringChoice): Type, any of “aim”, “gtalk”, “icq”, “xmpp”, “msn”, “skype”, “yahoo”, “qq”, “other”, Default: other
• value (String): Value, a unicode string

type

Type

value

Value

class helpscout.models.Conversation(**kwargs)

Bases: helpscout.models.base_conversation.BaseConversation

This represents a full conversation result.

Required Properties:

• bcc (a list of String): Emails that are BCCd., a list (each item is a unicode string)
• cc (a list of String): Emails that are CCd., a list (each item is a unicode string)
• closed_at (DateTime): UTC time when this conversation was closed. Null if not closed., a datetime object
• closed_by (Person): The Help Scout user who closed this conversation., an instance of Person
• created_at (DateTime): UTC time when this conversation was created., a datetime object
• created_by (Person): The Person who created this conversation. The type property will specify whether it was created by a user or a customer., an instance of Person
• created_by_type (String): The type of user that created this conversation., a unicode string
• customer (Person): The customer who this conversation is associated with., an instance of Person
• draft (Bool): Is this a draft conversation? This property duplicates is_draft, but both are received in API responses at the same time so neither can be considered “deprecated”., a boolean
• folder_id (Integer): ID of the Mailbox Folder to which this conversation resides., an integer
• id (Integer): Unique identifier, an integer
• is_draft (Bool): Is this a draft conversation? This property duplicates draft, but both are received in API responses at the same time so neither can be considered “deprecated”., a boolean
• locked (Bool): If this conversation is locked from editing., a boolean
• mailbox (MailboxRef): The mailbox to which this conversation belongs., an instance of MailboxRef
• modified_at (DateTime): UTC time when a user last modified this conversation., a datetime object
• number (Integer): The conversation number displayed in the UI. This number can be used in combination with the id to construct a URI to the conversation on the Help Scout website. Example: https://secure.helpscout.net/conversation/<id>/<number>/, an integer
• owner (Person): The Help Scout user who is currently assigned to this conversation., an instance of Person
• preview (String): Conversation preview., a unicode string
• source (Source): Specifies the method in which this conversation was created., an instance of Source
• spam (Bool): If this conversation is marked as SPAM., a boolean
• status (StringChoice): Status of the conversation., any of “active”, “pending”, “closed”, “spam”, Default: pending
• subject (String): The subject of the conversation., a unicode string
• tags (a list of String): Tags for the conversation, a list (each item is a unicode string)
• thread_count (Integer): This count represents the number of published threads found on the conversation (it does not include line items, drafts or threads held for review by Traffic Cop)., an integer
• threads (a list of Thread): Threads associated with the conversation., a list (each item is an instance of Thread)
• type (StringChoice): The type of conversation., any of “email”, “chat”, “phone”, “spam”
• user_modified_at (DateTime): Last time that this conversation was edited by a user., a datetime object

bcc

Emails that are BCCd.

cc

Emails that are CCd.

closed_at

UTC time when this conversation was closed. Null if not closed.

closed_by

The Help Scout user who closed this conversation.

created_at

UTC time when this conversation was created.

created_by

The Person who created this conversation. The type property will specify whether it was created by a user or a customer.

created_by_type

The type of user that created this conversation.

customer

The customer who this conversation is associated with.

draft

Is this a draft conversation? This property duplicates is_draft, but both are received in API responses at the same time so neither can be considered “deprecated”.

folder_id

ID of the Mailbox Folder to which this conversation resides.

is_draft

Is this a draft conversation? This property duplicates draft, but both are received in API responses at the same time so neither can be considered “deprecated”.

locked

If this conversation is locked from editing.

mailbox

The mailbox to which this conversation belongs.

owner

The Help Scout user who is currently assigned to this conversation.

source

Specifies the method in which this conversation was created.

spam

If this conversation is marked as SPAM.

tags

Tags for the conversation

threads

Threads associated with the conversation.

type

The type of conversation.

user_modified_at

Last time that this conversation was edited by a user.

class helpscout.models.CustomField(**kwargs)

Bases: helpscout.base_model.BaseModel

This represents optional data that can defined for specific mailbox

and filled when creating or updating a Conversation.

Required Properties:

• field_name (String): The name of the field; note that this may change if a field is renamed, but the id will not., a unicode string
• field_type (StringChoice): Type of the field., any of “SINGLE_LINE”, “MULTI_LINE”, “DATA”, “NUMBER”, “DROPDOWN”, Default: SINGLE_LINE
• id (Integer): Unique identifier, an integer
• options (a list of Option): Field options, a list (each item is an instance of Option)
• order (Integer): Relative order of the custom field. Can be null or a number between 0 and 255., an integer in range [0, 255]
• required (Bool): Flag for UI to mark the field as required., a boolean

field_name

The name of the field; note that this may change if a field is renamed, but the id will not.

field_type

Type of the field.

options

Field options

order

Relative order of the custom field. Can be null or a number between 0 and 255.

required

Flag for UI to mark the field as required.

class helpscout.models.Customer(**kwargs)

Bases: helpscout.models.search_customer.SearchCustomer

This represents a customer, which is a type of person.

Required Properties:

• address (Address): The address for this customer., an instance of Address
• age (String): Age (or age range) of this customer., a unicode string
• background (String): This is the Notes field from the user interface., a unicode string
• chats (a list of Chat): Chat addresses for this customer., a list (each item is an instance of Chat)
• created_at (DateTime): UTC time when this customer was created., a datetime object
• email (String): Email, a unicode string
• emails (a list of Email): Email addresses for this customer., a list (each item is an instance of Email)
• first_name (String): First name, a unicode string
• full_name (String): Full name for the customer, a unicode string
• gender (StringChoice): Gender of this customer., any of “female”, “male”, “unknown”, Default: unknown
• id (Integer): Unique identifier, an integer
• job_title (String): Job title at company/organization., a unicode string
• last_name (String): Last name, a unicode string
• location (String): Location, a unicode string
• modified_at (DateTime): UTC time when this customer was modified., a datetime object
• organization (String): Company/Organization the customer identifies with., a unicode string
• phone (String): Phone is only populated when the Person is a customer associated with a Conversation of type phone and a phone number was specified at the time the conversation was created., a unicode string
• phones (a list of Phone): Phone numbers for this customer., a list (each item is an instance of Phone)
• photo_type (StringChoice): Type of photo., any of “unknown”, “gravatar”, “twitter”, “facebook”, “googleprofile”, “googleplus”, “linkedin”
• photo_url (String): The user’s photo, if one exists., a unicode string
• social_profiles (a list of SocialProfile): Social profiles that represent this customer., a list (each item is an instance of SocialProfile)
• type (StringChoice): The type of person., any of “user”, “customer”, “team”, Default: customer
• websites (a list of Website): Websites for this customer., a list (each item is an instance of Website)

Other Properties:

• customer_person_type (dynamic Bool): customer boolean, a boolean

address

The address for this customer.

background

This is the Notes field from the user interface.

chats

Chat addresses for this customer.

emails

Email addresses for this customer.

phones

Phone numbers for this customer.

social_profiles

Social profiles that represent this customer.

websites

Websites for this customer.

class helpscout.models.Email(**kwargs)

Bases: helpscout.base_model.BaseModel

Required Properties:

• id (Integer): Unique identifier, an integer
• location (StringChoice): Location for this email address., any of “home”, “work”, “other”, Default: other
• value (String): Email Address, a unicode string

location

Location for this email address.

value

Email Address

class helpscout.models.Field(**kwargs)

Bases: helpscout.base_model.BaseModel

The field object represents a user’s response to a custom field

in the context of a single conversation.

Required Properties:

• field_id (Integer): The field definition identifier; note that multiple conversations will each have values for the same field identifier., an integer
• id (Integer): Unique identifier, an integer
• label (String): String representation of the custom field’s value. Unlike value it contains the actual dropdown option value for DROPDOWN custom field., a unicode string
• name (String): The name of the field; note that this may change if a field is renamed, but the field_id will not., a unicode string
• type (StringChoice): Type of the custom field., any of “SINGLE_LINE”, “MULTI_LINE”, “DATE”, “NUMBER”, “DROPDOWN”
• value (String): The value the user specified for the field., a unicode string

field_id

The field definition identifier; note that multiple conversations will each have values for the same field identifier.

label

String representation of the custom field’s value. Unlike value it contains the actual dropdown option value for DROPDOWN custom field.

name

The name of the field; note that this may change if a field is renamed, but the field_id will not.

type

Type of the custom field.

value

The value the user specified for the field.

class helpscout.models.Folder(**kwargs)

Bases: helpscout.base_model.BaseModel

Required Properties:

• active_count (Integer): Total number of conversations in this folder that are in an active state (vs pending)., an integer
• id (Integer): Unique identifier, an integer
• modified_at (DateTime): UTC time when this folder was modified., a datetime object
• name (String): Folder name, a unicode string
• total_count (Integer): Total number of conversations in this folder., an integer
• type (StringChoice): The type of folder., any of “needsattention”, “drafts”, “assigned”, “open”, “closed”, “spam”, “mine”, “team”, Default: drafts
• user_id (Integer): If the folder type is MyTickets, this represents the Help Scout user to which this folder belongs. Otherwise it is empty., an integer

active_count

Total number of conversations in this folder that are in an active state (vs pending).

modified_at

UTC time when this folder was modified.

name

Folder name

total_count

Total number of conversations in this folder.

type

The type of folder.

user_id

If the folder type is MyTickets, this represents the Help Scout user to which this folder belongs. Otherwise it is empty.

class helpscout.models.Mailbox(**kwargs)

Bases: helpscout.models.mailbox_ref.MailboxRef

Required Properties:

• created_at (DateTime): UTC time when this mailbox was created., a datetime object
• email (String): Email address, a unicode string
• folders (a list of Folder): Folders that this mailbox contains., a list (each item is an instance of Folder)
• id (Integer): Unique identifier, an integer
• modified_at (DateTime): UTC time when this mailbox was modified., a datetime object
• name (String): Name of the Mailbox., a unicode string
• slug (String): Key used to represent this Mailbox., a unicode string

created_at

UTC time when this mailbox was created.

email

Email address

folders

Folders that this mailbox contains.

modified_at

UTC time when this mailbox was modified.

slug

Key used to represent this Mailbox.

class helpscout.models.MailboxRef(**kwargs)

Bases: helpscout.base_model.BaseModel

The mailbox ref is a subset of the full Mailbox object.

Required Properties:

• id (Integer): Unique identifier, an integer
• name (String): Name of the Mailbox., a unicode string

name

Name of the Mailbox.

class helpscout.models.Option(**kwargs)

Bases: helpscout.base_model.BaseModel

This represents option for a custom field of type DROPDOWN.

Required Properties:

• id (Integer): Unique identifier, an integer
• label (String): Label of the option., a unicode string
• order (Integer): Relative order of the custom field. Can be null or a number between 0 and 255., an integer in range [0, 255]

label

Label of the option.

order

Relative order of the custom field. Can be null or a number between 0 and 255.

class helpscout.models.Person(**kwargs)

Bases: helpscout.base_model.BaseModel

This is a subset of the data representing a Customer, User or Team.

The type property will specify if this person is represented by a user, customer or team.

Required Properties:

• created_at (DateTime): UTC time when this customer was created., a datetime object
• email (String): Email, a unicode string
• emails (a list of String): Email addresses for this person., a list (each item is a unicode string)
• first_name (String): First name, a unicode string
• full_name (String): Full name for the customer, a unicode string
• id (Integer): Unique identifier, an integer
• last_name (String): Last name, a unicode string
• modified_at (DateTime): UTC time when this customer was modified., a datetime object
• phone (String): Phone is only populated when the Person is a customer associated with a Conversation of type phone and a phone number was specified at the time the conversation was created., a unicode string
• photo_url (String): The user’s photo, if one exists., a unicode string
• type (StringChoice): The type of person., any of “user”, “customer”, “team”, Default: customer

Other Properties:

• customer_person_type (dynamic Bool): customer boolean, a boolean

created_at

UTC time when this customer was created.

customer_person_type

customer boolean

email

Email

emails

Email addresses for this person.

first_name

First name

full_name

Full name for the customer

last_name

Last name

modified_at

UTC time when this customer was modified.

phone

Phone is only populated when the Person is a customer associated with a Conversation of type phone and a phone number was specified at the time the conversation was created.

photo_url

The user’s photo, if one exists.

type

The type of person.

class helpscout.models.Phone(**kwargs)

Bases: helpscout.base_model.BaseModel

Required Properties:

• id (Integer): Unique identifier, an integer
• location (StringChoice): Location for this phone number., any of “home”, “fax”, “mobile”, “pager”, “work”, “other”, Default: other
• value (String): Phone Number, a unicode string

location

Location for this phone number.

value

Phone Number

class helpscout.models.Rating(**kwargs)

Bases: helpscout.base_model.BaseModel

Required Properties:

• comments (String): Additional comments, a unicode string
• created_at (DateTime): UTC time when this rating was created., a datetime object
• customer (Customer): Partial customer object., an instance of Customer
• id (Integer): Unique identifier, an integer
• mailbox (MailboxRef): Reference to the mailbox that the conversation belongs to., an instance of MailboxRef
• modified_at (DateTime): UTC time when this rating was modified., a datetime object
• rating (StringChoice): Satisfaction rating., any of “Great”, “Okay”, “Bad”
• thread_id (Integer): Thread ID, an integer
• ticket_id (Integer): Ticket ID, an integer

comments

Additional comments

created_at

UTC time when this rating was created.

customer

Partial customer object.

mailbox

Reference to the mailbox that the conversation belongs to.

modified_at

UTC time when this rating was modified.

rating

Satisfaction rating.

thread_id

Thread ID

ticket_id

Ticket ID

class helpscout.models.SearchConversation(**kwargs)

Bases: helpscout.models.base_conversation.BaseConversation

This represents a conversation as returned by search results.

Required Properties:

• customer_email (String): Email address of the customer, a unicode string
• customer_name (String): Name of the customer this conversation is regarding., a unicode string
• has_attachments (Bool): True when the conversation has at least one attachment., a boolean
• id (Integer): Unique identifier, an integer
• mailbox_id (Integer): The ID of the mailbox this conversation is in., an integer
• modified_at (DateTime): UTC time when a user last modified this conversation., a datetime object
• number (Integer): The conversation number displayed in the UI. This number can be used in combination with the id to construct a URI to the conversation on the Help Scout website. Example: https://secure.helpscout.net/conversation/<id>/<number>/, an integer
• preview (String): Conversation preview., a unicode string
• status (StringChoice): Status of the conversation., any of “active”, “pending”, “closed”, “spam”, Default: pending
• subject (String): The subject of the conversation., a unicode string
• thread_count (Integer): This count represents the number of published threads found on the conversation (it does not include line items, drafts or threads held for review by Traffic Cop)., an integer

customer_email

Email address of the customer

customer_name

Name of the customer this conversation is regarding.

has_attachments

True when the conversation has at least one attachment.

mailbox_id

The ID of the mailbox this conversation is in.

class helpscout.models.SearchCustomer(**kwargs)

Bases: helpscout.models.person.Person

This represents a customer as returned by a search.

Required Properties:

• age (String): Age (or age range) of this customer., a unicode string
• created_at (DateTime): UTC time when this customer was created., a datetime object
• email (String): Email, a unicode string
• emails (a list of String): Email addresses for the customer., a list (each item is a unicode string)
• first_name (String): First name, a unicode string
• full_name (String): Full name for the customer, a unicode string
• gender (StringChoice): Gender of this customer., any of “female”, “male”, “unknown”, Default: unknown
• id (Integer): Unique identifier, an integer
• job_title (String): Job title at company/organization., a unicode string
• last_name (String): Last name, a unicode string
• location (String): Location, a unicode string
• modified_at (DateTime): UTC time when this customer was modified., a datetime object
• organization (String): Company/Organization the customer identifies with., a unicode string
• phone (String): Phone is only populated when the Person is a customer associated with a Conversation of type phone and a phone number was specified at the time the conversation was created., a unicode string
• photo_type (StringChoice): Type of photo., any of “unknown”, “gravatar”, “twitter”, “facebook”, “googleprofile”, “googleplus”, “linkedin”
• photo_url (String): The user’s photo, if one exists., a unicode string
• type (StringChoice): The type of person., any of “user”, “customer”, “team”, Default: customer

Other Properties:

• customer_person_type (dynamic Bool): customer boolean, a boolean

age

Age (or age range) of this customer.

emails

Email addresses for the customer.

gender

Gender of this customer.

job_title

Job title at company/organization.

location

Location

organization

Company/Organization the customer identifies with.

photo_type

Type of photo.

class helpscout.models.SocialProfile(**kwargs)

Bases: helpscout.base_model.BaseModel

Required Properties:

• id (Integer): Unique identifier, an integer
• type (StringChoice): Type of social profile., any of “twitter”, “facebook”, “linkedin”, “aboutme”, “google”, “googleplus”, “tungleme”, “quora”, “foursquare”, “youtube”, “flickr”, “other”, Default: other
• value (String): Username, a unicode string

type

Type of social profile.

value

Username

class helpscout.models.Source(**kwargs)

Bases: helpscout.base_model.BaseModel

Required Properties:

• id (Integer): Unique identifier, an integer
• type (StringChoice): The method from which this conversation (or thread) was created., any of “email”, “web”, “notification”, “emailfwd”, “api”, “chat”, Default: api
• via (StringChoice): Indicates what type of entity this source represents (customer, user)., either “customer” or “user”

type

The method from which this conversation (or thread) was created.

via

Indicates what type of entity this source represents (customer, user).

class helpscout.models.Tag(**kwargs)

Bases: helpscout.base_model.BaseModel

Required Properties:

• color (Color): The tag color., a color
• count (Integer): The number of times the tag is used., an integer
• created_at (DateTime): UTC time when this tag was created., a datetime object
• id (Integer): Unique identifier, an integer
• modified_at (DateTime): UTC time when this tag was modified., a datetime object
• slug (String): Slugified version of the tag value., a unicode string
• tag (String): The tag value., a unicode string

color

The tag color.

count

The number of times the tag is used.

created_at

UTC time when this tag was created.

modified_at

UTC time when this tag was modified.

slug

Slugified version of the tag value.

tag

The tag value.

class helpscout.models.Thread(**kwargs)

Bases: helpscout.base_model.BaseModel

Required Properties:

• action_source_id (Integer): Associated with the action_type property.
• If action_type is movedFromMailbox, this will be the id of the mailbox the conversation was moved from.
• If action_type is merged, this will be the id of the original conversation.
• If action_type is imported, this will be null.
• If action_type is workflow, this will be the id of the workflow that was run.

, an integer * action_type (StringChoice): Describes an optional action associated with the line item., any of “movedFromMailbox”, “merged”, “imported”, “workflow”, “importedExternal”, “changedTicketCustomer”, “deletedTicket”, “restoredTicket”, “originalCreator” * assigned_to (Person): The Help Scout user assigned to this conversation., an instance of Person * attachments (a list of Attachment): Attachments, a list (each item is an instance of Attachment) * bcc (a list of String): BCC to, a list (each item is a unicode string) * body (String): Body text, a unicode string * cc (a list of String): CC to, a list (each item is a unicode string) * created_at (DateTime): UTC time when this thread was created., a datetime object * created_by (Person): The Person who created this thread. The type property will specify whether it was created by a user or a customer., an instance of Person * created_by_customer (Bool): Equivalent to created_by.type == "customer"., a boolean * customer (Person): If thread type is message, this is the customer associated with the conversation. If thread type is customer, this is the the customer who initiated the thread., an instance of Person * from_mailbox (MailboxRef): If the conversation was moved, this represents the MailboxRef from which it was moved., an instance of MailboxRef * id (Integer): Unique identifier, an integer * opened_at (DateTime): UTC time when this thread was viewed by the customer. Only applies to threads with a type of message., a datetime object * saved_reply_id (Integer): ID of Saved reply that was used to create this Thread., an integer * source (Source): Origin of thread, an instance of Source * state (StringChoice): The state of the thread. A state of underreview means the thread has been stopped by Traffic Cop and is waiting to be confirmed (or discarded) by the person that created the thread. A state of hidden means the thread was hidden (or removed) from customer-facing emails., any of “published”, “draft”, “underreview”, “hidden” * status (StringChoice): Status of the thread., any of “nochange”, “active”, “pending”, “closed”, “spam” * to (a list of String): Email to, a list (each item is a unicode string) * type (StringChoice): The type of thread. A lineitem represents a change of state on the conversation. This could include, but not limited to, the conversation was assigned, the status changed, the conversation was moved from one mailbox to another, etc. A line item won’t have a body, to/cc/bcc lists, or attachments. When a conversation is forwarded, a new conversation is created to represent the forwarded conversation. forwardparent ``is the type set on the thread of the original conversation that initiated the forward event. ``forwardchild is the type set on the first thread of the new forwarded conversation., any of “lineitem”, “note”, “message”, “chat”, “customer”, “forwardparent”, “forwardchild”, “phone”

action_source_id

Associated with the action_type property.

• If action_type is movedFromMailbox, this will be the id of the mailbox the conversation was moved from.
• If action_type is merged, this will be the id of the original conversation.
• If action_type is imported, this will be null.
• If action_type is workflow, this will be the id of the workflow that was run.

action_type

Describes an optional action associated with the line item.

assigned_to

The Help Scout user assigned to this conversation.

attachments

Attachments

bcc

BCC to

body

Body text

cc

CC to

created_at

UTC time when this thread was created.

created_by

The Person who created this thread. The type property will specify whether it was created by a user or a customer.

created_by_customer

Equivalent to created_by.type == "customer".

customer

If thread type is message, this is the customer associated with the conversation. If thread type is customer, this is the the customer who initiated the thread.

from_mailbox

If the conversation was moved, this represents the MailboxRef from which it was moved.

opened_at

UTC time when this thread was viewed by the customer. Only applies to threads with a type of message.

saved_reply_id

ID of Saved reply that was used to create this Thread.

source

Origin of thread

state

The state of the thread. A state of underreview means the thread has been stopped by Traffic Cop and is waiting to be confirmed (or discarded) by the person that created the thread. A state of hidden means the thread was hidden (or removed) from customer-facing emails.

status

Status of the thread.

to

Email to

type

The type of thread. A lineitem represents a change of state on the conversation. This could include, but not limited to, the conversation was assigned, the status changed, the conversation was moved from one mailbox to another, etc. A line item won’t have a body, to/cc/bcc lists, or attachments. When a conversation is forwarded, a new conversation is created to represent the forwarded conversation. forwardparent ``is the type set on the thread of the original conversation that initiated the forward event. ``forwardchild is the type set on the first thread of the new forwarded conversation.

class helpscout.models.User(**kwargs)

Bases: helpscout.models.person.Person

Required Properties:

• created_at (DateTime): UTC time when this customer was created., a datetime object
• email (String): Email, a unicode string
• emails (a list of String): Email addresses for this person., a list (each item is a unicode string)
• first_name (String): First name, a unicode string
• full_name (String): Full name for the customer, a unicode string
• id (Integer): Unique identifier, an integer
• last_name (String): Last name, a unicode string
• modified_at (DateTime): UTC time when this customer was modified., a datetime object
• phone (String): Phone is only populated when the Person is a customer associated with a Conversation of type phone and a phone number was specified at the time the conversation was created., a unicode string
• photo_url (String): The user’s photo, if one exists., a unicode string
• role (StringChoice): Role of this user., any of “owner”, “admin”, “user”
• timezone (String): Name of the user’s time zone., a unicode string
• type (StringChoice): The type of user., either “user” or “team”

Other Properties:

• customer_person_type (dynamic Bool): customer boolean, a boolean

role

Role of this user.

timezone

Name of the user’s time zone.

type

The type of user.

class helpscout.models.WebHook(**kwargs)

Bases: helpscout.base_model.BaseModel

Required Properties:

• events (a list of StringChoice): The events to subscribe to., a list (each item is any of “convo.agent.reply.created” (An agent replied to the conversation.), “convo.assigned” (Conversation was assigned.), “convo.created” (Conversation was created.), “convo.customer.reply.created” (The customer replied to the conversation.), “convo.deleted” (Conversation was deleted.), “convo.merged” (Conversation was merged.), “convo.moved” (Conversation was moved.), “convo.note.created” (A note was added to the conversation.), “convo.status” (Conversation status was updated.), “convo.tags” (Conversation tags were updated.), “customer.created” (A customer was created.), “satisfaction.ratings” (A rating was received.))
• id (Integer): Unique identifier, an integer
• secret_key (String): A randomly-generated (by you) string of 40 characters or less used to create signatures for each webhook method. Help Scout uses this secret key to generate a signature for each webhook message. When the message is received at your callback URL, you can calculate a signature and compare to the one Help Scout sends. If the signatures match, you know it’s from Help Scout., a unicode string
• url (String): The callback URL where Help Scout will post your webhook events. This is the script or location where you’ll handle the data received from Help Scout., a unicode string

events

The events to subscribe to.

secret_key

A randomly-generated (by you) string of 40 characters or less used to create signatures for each webhook method. Help Scout uses this secret key to generate a signature for each webhook message. When the message is received at your callback URL, you can calculate a signature and compare to the one Help Scout sends. If the signatures match, you know it’s from Help Scout.

url

The callback URL where Help Scout will post your webhook events. This is the script or location where you’ll handle the data received from Help Scout.

class helpscout.models.WebHookEvent(**kwargs)

Bases: helpscout.base_model.BaseModel

Required Properties:

• event_type (StringChoice): The event type that this object represents., any of “convo.agent.reply.created” (An agent replied to the conversation.), “convo.assigned” (Conversation was assigned.), “convo.created” (Conversation was created.), “convo.customer.reply.created” (The customer replied to the conversation.), “convo.deleted” (Conversation was deleted.), “convo.merged” (Conversation was merged.), “convo.moved” (Conversation was moved.), “convo.note.created” (A note was added to the conversation.), “convo.status” (Conversation status was updated.), “convo.tags” (Conversation tags were updated.), “customer.created” (A customer was created.), “satisfaction.ratings” (A rating was received.)
• id (Integer): Unique identifier, an integer
• record (BaseModel): The parsed data record that was received in the request., an instance of BaseModel

event_type

The event type that this object represents.

record

The parsed data record that was received in the request.

class helpscout.models.Website(**kwargs)

Bases: helpscout.base_model.BaseModel

Required Properties:

• id (Integer): Unique identifier, an integer
• value (String): URI, a unicode string

value

URI

class helpscout.models.Workflow(**kwargs)

Bases: helpscout.base_model.BaseModel

Required Properties:

• created_at (DateTime): UTC time when this workflow was created., a datetime object
• id (Integer): Unique identifier, an integer
• mailbox_id (Integer): The mailbox ID that this workflow is associated with., an integer
• modified_at (DateTime): UTC time when this workflow was modified., a datetime object
• name (String): Workflow name., a unicode string
• order (Integer): The order of the workflow., an integer, Default: 1
• status (StringChoice): The status of the workflow., any of “active”, “inactive”, “invalid”, Default: invalid
• type (StringChoice): The type of workflow., either “automatic” or “manual”, Default: manual

created_at

UTC time when this workflow was created.

mailbox_id

The mailbox ID that this workflow is associated with.

modified_at

UTC time when this workflow was modified.

name

Workflow name.

order

The order of the workflow.

status

The status of the workflow.

type

The type of workflow.