Skip to main content

This library allows you to interact with HelpScout using Python.

Project description

License: MIT | PyPi Package | PyPi Versions

Build Status | Test Coverage | Code Climate

HelpScout

This library allows you to interact with HelpScout using Python.

Installation

Installation is easiest using Pip and PyPi:

pip install helpscout

If you would like to contribute, or prefer Git:

git clone https://github.com/LasLabs/python-helpscout.git
cd python-helpscout
pip install -r requirements.txt
pip install .

Usage

The HelpScout object is the primary point of interaction with the HelpScout API.

Connection

Connecting to the HelpScout API will require an API Key, which is generated from within your HelpScout account. In the below example, our key is API_KEY.

from helpscout import HelpScout
hs = HelpScout('API_KEY')

API Endpoints

The HelpScout API endpoints are exposed as variables on the instantiated HelpScout object. The available endpoints are:

They can also be viewed from the __apis__ property of HelpScout:

>>> hs.__apis__
{'Conversations': <helpscout.auth_proxy.AuthProxy object at 0x10783ddd0>,
 'Customers': <helpscout.auth_proxy.AuthProxy object at 0x10783dd90>,
 'Mailboxes': <helpscout.auth_proxy.AuthProxy object at 0x10783ded0>,
 'Users': <helpscout.auth_proxy.AuthProxy object at 0x10783df50>,
 'Teams': <helpscout.auth_proxy.AuthProxy object at 0x10783df10>,
 }

API usage is as simple as calling the method with the required parameters and iterating the results:

for customer in hs.Customers.list(first_name='Help', last_name='Scout'):
    print(customer)
    print(customer.serialize())

The output from the above would look something like the below when using the HelpScout demo data:

# This is the customer object itself (first print)
<helpscout.models.customer.Customer object at 0x10783df10>
# This is the serialized form of the customer (second print)
{'chats': [],
 'social_profiles': [],
 'first_name': u'Help',
 'last_name': u'Scout',
 'phones': [],
 'created_at': '2017-09-16T18:38:37Z',
 'modified_at': '2017-09-16T18:38:37Z',
 u'__class__': 'Customer',
 'websites': [],
 'id': 143161083,
 'location': u'Boston, MA',
 'full_name': u'Help Scout',
 'gender': 'unknown',
 'photo_type': 'gravatar',
 'type': 'customer',
 'emails': [],
 'photo_url': u'https://secure.gravatar.com/avatar/7d599977ec288a9141317b352c04d497'}

In some instances, such as in the case of browsing for a record by its ID, a singleton is expected. In these instances, the singleton is directly used instead of iterated

>>> customer = hs.Customers.get(143161083)
>>> customer
<helpscout.models.customer.Customer object at 0x101723e50>
>>> from pprint import pprint
>>> pprint(customer.serialize())
{u'__class__': 'Customer',
 'address': {u'__class__': 'Address',
             'city': u'Boston',
             'country': u'US',
             'created_at': '2017-09-16T18:38:37Z',
             'id': 4996350,
             'lines': [u'131 Tremont Street', u'3rd Floor'],
             'postal_code': u'02111-1338',
             'state': u'MA'},
 'chats': [],
 'created_at': '2017-09-16T18:38:37Z',
 'emails': [{u'__class__': 'Email',
             'id': 189240662,
             'location': 'work',
             'value': u'help@helpscout.net'}],
 'first_name': u'Help',
 'full_name': u'Help Scout',
 'gender': 'unknown',
 'id': 143161083,
 'last_name': u'Scout',
 'location': u'Boston, MA',
 'modified_at': '2017-09-16T18:38:37Z',
 'phones': [{u'__class__': 'Phone',
             'id': 189240668,
             'location': 'work',
             'value': u'855-435-7726'}],
 'photo_type': 'gravatar',
 'photo_url': u'https://secure.gravatar.com/avatar/7d599977ec288a9141317b352c04d497',
 'social_profiles': [{u'__class__': 'SocialProfile',
                      'id': 189240667,
                      'type': 'twitter',
                      'value': u'http://twitter.com/helpscout'},
                     {u'__class__': 'SocialProfile',
                      'id': 189240663,
                      'type': 'twitter',
                      'value': u'https://twitter.com/helpscout'},
                     {u'__class__': 'SocialProfile',
                      'id': 189240664,
                      'type': 'twitter',
                      'value': u'https://twitter.com/HelpScoutDev'}],
 'type': 'customer',
 'websites': [{u'__class__': 'Website',
               'id': 189240670,
               'value': u'http://developer.helpscout.net'},
              {u'__class__': 'Website',
               'id': 189240665,
               'value': u'http://status.helpscout.net/'},
              {u'__class__': 'Website',
               'id': 189240666,
               'value': u'http://www.helpscout.com'},
              {u'__class__': 'Website',
               'id': 189240671,
               'value': u'http://www.helpscout.net'}]}

Note that all of the API responses will be parsed, with proper objects being created from the results. The objects are all defined in the helpscout.models package.

Web Hooks

Web Hooks can be received using the web_hook property on an instantiated HelpScout object, which returns a WebHookEvent representing the parsed request.

signature = '2iFmnzC8SCNVF/iNiMnSe19yceU=\n'  # (``X-HelpScout-Signature`` Header)
event_type = 'customer.created'  # (``X-HelpScout-Event`` Header)
request_body = '{"firstName":"Jackie","lastName":"Chan",' \
               '"email":"jackie.chan@somewhere.com",' \
               '"gender":"male"}'

event = hs.web_hook(
    event_type, signature, request_body,
)

The WebHookEvent that is returned contains two properties:

  • event_type (str): The type of event that is being represented

  • record (helpscout.BaseModel): The parsed data record for this request

Given the above example:

>>> event.event_type
'customer.created'
>>> event.record
<helpscout.models.customer.Customer object at 0x101723e50>

Known Issues / RoadMap

  • Add better validations (like regexes for emails)

  • Verify required attributes, particularly when creating for API instead of receiving

  • Attachment handling in Conversations (Create/Delete Attachment)

  • Raw email source handling in Conversations (Get Thread Source)

  • Implement List Customers by Mailbox

  • Implement Workflows

  • Implement index lookup for the RequestPaginator (currently only response iteration is supported)

  • Make the domain add syntax more robust (right now AND + OR don’t combine well)

Credits

Contributors

Maintainer

LasLabs Inc.

This module is maintained by LasLabs Inc.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

helpscout-0.0.2b115.tar.gz (28.1 kB view details)

Uploaded Source

Built Distributions

helpscout-0.0.2b115-py3-none-any.whl (53.2 kB view details)

Uploaded Python 3

helpscout-0.0.2b115-py2-none-any.whl (53.2 kB view details)

Uploaded Python 2

File details

Details for the file helpscout-0.0.2b115.tar.gz.

File metadata

  • Download URL: helpscout-0.0.2b115.tar.gz
  • Upload date:
  • Size: 28.1 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No

File hashes

Hashes for helpscout-0.0.2b115.tar.gz
Algorithm Hash digest
SHA256 c97b3c4e020337166c66b3e4adb4f9e6271b5eb14646e5b2d1e4e7c2825b7ab3
MD5 4dc4c83b30431d56d4419ab917fc9ac1
BLAKE2b-256 95d69638c8fa5e81da49414e4a15a0a04ac0217633a0eedd8ba0bb3b16f03b45

See more details on using hashes here.

File details

Details for the file helpscout-0.0.2b115-py3-none-any.whl.

File metadata

File hashes

Hashes for helpscout-0.0.2b115-py3-none-any.whl
Algorithm Hash digest
SHA256 b47f9fb366d48e5c7533496c169aab02644ca05b99855de7cdfbdff7b3da293e
MD5 1a4357c7aa75583338624f64577d56f0
BLAKE2b-256 37a188f033a83ea05fa999c8da7152d8aec93533b337d99ad4a5a2bbd0c3fca9

See more details on using hashes here.

File details

Details for the file helpscout-0.0.2b115-py2-none-any.whl.

File metadata

File hashes

Hashes for helpscout-0.0.2b115-py2-none-any.whl
Algorithm Hash digest
SHA256 898ae05e070f7dc229353db6e867be51c1e3c15ccf24cdfb5ebb0e5d1d74a82f
MD5 3b1f3565d9ac2066c6928a112b600169
BLAKE2b-256 d8196386511227378278523d9d2e87aabbc7d8ce587db83af072482826ea1464

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page