Package: helpscout
||||HelpScoutThis library allows you to interact with HelpScout using Python.Read The API DocumentationTable of ContentsHelpScoutInstallationUsageConnectionAPI EndpointsSearchingWeb HooksKnown Issues / RoadMapCreditsContributorsMaintainerInstallationInstallation is easiest using Pip and PyPi:pip install helpscoutIf 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 .UsageTheHelpScout objectis the primary point of interaction with the HelpScout API.ConnectionConnecting to the HelpScout API will require an API Key, which is generated from
within your HelpScout account. In the below example, our key isAPI_KEY.fromhelpscoutimportHelpScouths=HelpScout('API_KEY')API EndpointsThe HelpScout API endpoints are exposed as variables on the instantiatedHelpScoutobject. The available endpoints are:Conversations EndpointCustomers EndpointMailboxes EndpointTags EndpointTeams EndpointUsers EndpointWebHook EndpointThey can also be viewed from the__apis__property ofHelpScout:>>> 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:forcustomerinhs.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.Customerobjectat0x10783df10># 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.Customerobjectat0x101723e50>>>>frompprintimportpprint>>>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 thehelpscout.models
package.SearchingThe.search()method is implemented for the following endpoints:Conversations SearchCustomers SearchSearch accepts either an instantiatedDomain, or aniterator 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')])>>>forrinres:>>>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 HooksWeb Hookscan be received by
instantiating aHelpScoutWebHookusing
the secret key that was configured while setting up the hook in your
HelpScout account:fromhelpscoutimportHelpScoutWebHookhook=HelpScoutWebHook('your secret key')In order to actually receive the request, call thereceive methodon the instantiatedHelpScoutWebHook: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,)TheWebHookEventthat is returned contains two properties:event_type(str): The type of event that is being representedrecord(helpscout.BaseModel): The parsed data record for this requestGiven the above example:>>>event.event_type'customer.created'>>>event.record<helpscout.models.customer.Customerobjectat0x101723e50>You create a web hook using the standard endpoint create:fromhelpscout.modelsimportHelpScoutWebHookhook=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 thecustomer.createdevent using
the pre-authenticatedHelpScoutobject from above examples (hs).Known Issues / RoadMapAdd better validations (like regexes for emails)Verify required attributes, particularly when creating for API instead of
receivingAttachment handling in Conversations (Create/Delete Attachment)Raw email source handling in Conversations (Get Thread Source)Implement List Customers by MailboxImplement WorkflowsImplement 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 implementedCreditsContributorsDave Lasley <dave@laslabs.com>Brent Hughes <brent.hughes@laslabs.com>MaintainerThis module is maintained by LasLabs Inc.