Skip to main content
Join the official Python Developers Survey 2018 and win valuable prizes: Start the survey!

This library allows you to interact with HelpScout using Python.

Project description

License: MIT | PyPi Package | PyPi Versions

Build Status | Test Coverage | Code Climate

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.

Searching

The .search() method is implemented for the following endpoints:

Search accepts either an instantiated Domain, or an iterator of queries:

[('subject', 'Test1'),
 'OR',
 ('subject', 'Test2')',
 ('subject', 'Test3')',
 ]

The above is equivalent to a HelpScout query string of:

(subject:'Test1' OR subject:'Test2' OR subject:'Test3')

Following is a usage example:

>>> res = hs.Conversations.search([('subject', 'Learning')])
>>> for r in res:
>>>     r.serialize()
{'status': 'active', 'customer_email': u'help@helpscout.net', 'thread_count': 0, 'modified_at': '2017-09-16T18:38:37Z', 'number': 150, 'subject': u'Learning the basics', u'__class__': 'SearchConversation', 'has_attachments': False, 'mailbox_id': 122867, 'preview': u'Hey Dave, Above this message is what we call the Conversation Toolbar. From there you can take all sorts of actions on a Conversation. Hover your mouse over each of the icons to see what you can do....', 'id': 432907900, 'customer_name': u'Help Scout'}

Web Hooks

Web Hooks can be received by instantiating a HelpScoutWebHook using the secret key that was configured while setting up the hook in your HelpScout account:

from helpscout import HelpScoutWebHook

hook = HelpScoutWebHook('your secret key')

In order to actually receive the request, call the receive method on the instantiated HelpScoutWebHook:

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 = web_hook.receive(
    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>

You create a web hook using the standard endpoint create:

from helpscout.models import HelpScoutWebHook
hook = HelpScoutWebHook(
   url='https://example.com/my/web/hook/'
   secret_key='SuperSecretRandomizedString'
   events=[
      'customer.created',
   ],
)
hs.WebHook.create(hook)

The above example will create a hook for the customer.created event using the pre-authenticated HelpScout object from above examples (hs).

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)
  • Docs API is not implemented

Credits

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.

Filename, size & hash SHA256 hash help File type Python version Upload date
helpscout-0.1.3.tar.gz (60.7 kB) Copy SHA256 hash SHA256 Source None Dec 14, 2017

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page